github.com/cozy/cozy-stack@v0.0.0-20240603063001-31110fa4cae1/docs/mango.md (about) 1 [Table of contents](README.md#table-of-contents) 2 3 # Mango 4 5 ## Create an index for some documents 6 7 The body should contain a `index` JSON field containing a `fields` which is an 8 ordered array of fields to index. 9 10 ### Request 11 12 ```http 13 POST /data/:doctype/_index HTTP/1.1 14 ``` 15 16 ```http 17 POST /data/io.cozy.events/_index HTTP/1.1 18 Content-Type: application/json 19 ``` 20 21 ```json 22 { 23 "index": { 24 "fields": ["calendar", "date"] 25 } 26 } 27 ``` 28 29 ### Response OK 30 31 ```http 32 HTTP/1.1 200 OK 33 Date: Mon, 27 Sept 2016 12:28:53 GMT 34 Content-Length: ... 35 Content-Type: application/json 36 ``` 37 38 ```json 39 { 40 "result": "created", 41 "id": "_design/a5f4711fc9448864a13c81dc71e660b524d7410c", 42 "name": "a5f4711fc9448864a13c81dc71e660b524d7410c" 43 } 44 ``` 45 46 ### Details 47 48 - if the doctype does not exist, the database is created. 49 - if the index already exists, a `{result: "exists"}` is returned, but the 50 response code is still 200 51 - design doc & name can be provided in request. **This is not recommended**, 52 let couchdb handle naming and deduplication. 53 54 ```json 55 { 56 "name": "by-calendar-and-date", 57 "ddoc": "_design/some-ddoc-name", 58 "index": { "fields": ... } 59 } 60 ``` 61 62 ### Possible errors 63 64 - 401 unauthorized (no authentication has been provided) 65 - 403 forbidden (the authentication does not provide permissions for this 66 action) 67 - 500 internal server error 68 69 ## Find documents 70 71 Find allows to find documents using a mango selector. You can read more about 72 mango selectors 73 [here](http://docs.couchdb.org/en/stable/api/database/find.html#selector-syntax) 74 75 ### Request 76 77 ```http 78 POST /data/:doctype/_find HTTP/1.1 79 ``` 80 81 ```http 82 POST /data/io.cozy.events/_find HTTP/1.1 83 Content-Type: application/json 84 ``` 85 86 ```json 87 { 88 "selector": { 89 "calendar": "perso", 90 "date": { "$gt": "20161001T00:00:00" } 91 }, 92 "limit": 2, 93 "sort": ["calendar", "date"], 94 "fields": ["_id", "_type", "_date"], 95 "execution_stats": true, 96 "use_index": "_design/a5f4711fc9448864a13c81dc71e660b524d7410c" 97 } 98 ``` 99 100 ### Response OK 101 102 ```http 103 HTTP/1.1 200 OK 104 Date: Mon, 27 Sept 2016 12:28:53 GMT 105 Content-Length: ... 106 Content-Type: application/json 107 ``` 108 109 ```json 110 { 111 "docs": [ 112 { 113 "_id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee", 114 "_type": "io.cozy.events", 115 "date": "20161023T160000Z" 116 }, 117 { 118 "_id": "6494e0ac-dfcb-472e84a9cbee", 119 "_type": "io.cozy.events", 120 "date": "20161013T160000Z" 121 } 122 ], 123 "execution_stats": { 124 "total_docs_examined": 10, 125 "results_returned": 2, 126 "execution_time_ms": 8.833 127 }, 128 "bookmark": "g1AAAAB2eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJB", 129 "limit": 2, 130 "next": true 131 } 132 ``` 133 134 ### Details 135 136 - If an index does not exist for the selector, an error 400 is returned 137 - The sort field must contains all fields used in selector 138 - The sort field must match an existing index 139 - It is possible to sort in reverse direction 140 `sort:[{"calendar":"desc"}, {"date": "desc"}]` but **all fields** must be 141 sorted in same direction. 142 - `use_index` is optional but recommended. 143 - `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. 144 145 ## Pagination cookbook 146 147 Pagination of mango query should be handled by the client. The stack will limit 148 query results to a maximum of 100 documents. This limit can be raised up to 149 1000 documents per page with the `limit` parameter, but not further. 150 151 The limit applied to a query is visible in the HTTP response. 152 153 If the limit cause some docs to not be returned, the response will have a 154 `next=true` top level values. Then, the returned `bookmark` value can be used in 155 the next query to get the missing docs. It is also possible to use `skip`, 156 to paginate, although this is not recommended for performances. For more details, see the 157 [CouchDB documentation](https://docs.couchdb.org/en/latest/api/database/find.html#pagination). 158 159 ```json 160 { 161 "limit": 100, 162 "next": true, 163 "docs": ["... first hundred docs ..."], 164 "bookmark": "g1AAAAB2eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYorGKQYpVqaJRoZm1paWFiapFkamhknGpilJiampZkYJRmC9HHA9OUAdTASpS0rCwAlah76" 165 } 166 ``` 167 168 If the number of docs is lower than the limit, next will be false. 169 170 ```json 171 { 172 "limit": 100, 173 "next": false, 174 "docs": ["... less than a hundred docs ..."] 175 } 176 ``` 177 178 179 ### Example: 180 181 Index on io.cozy.events with fields `["calendar", "date"]` 182 183 Try to get all events for a month: 184 185 ```json 186 "selector": { 187 "calendar": "my-calendar", 188 "date": { "$gt": "20161001", "$lt": "20161030" } 189 } 190 ``` 191 192 If there is less than 100 events, the response `next` field will be false and 193 there is nothing more to do. If there is more than 100 events for this month, we 194 have a `next=true` in the response. 195 196 To keep iterating, we can use the `bookmark` field we received in the next 197 request. 198 199 ```json 200 "selector": { 201 "calendar": "my-calendar", 202 "date": { "$gte": "20161001", "$lt": "20161030" } 203 }, 204 "bookmark": "g1AAAAB2eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYorGKQYpVqaJRoZm1paWFiapFkamhknGpilJiampZkYJRmC9HHA9OUAdTASpS0rCwAlah76" 205 ```