Making requests¶
Query syntax¶
Query parameters can be used on either GET, PATCH, PUT or DELETE requests.
url parameter | description |
---|---|
_m=<method> |
tunnel any http method using GET, e.g. _m=POST [1] |
_limit=<n> |
limit the returned collection to <n> results (default: 20, max limit: 100 for unauthenticated users) |
_sort=<field_name> |
sort collection by <field_name> |
_start=<n> |
start collection from the <n>th resource |
_page=<n> |
start collection at page <n> (n * _limit) |
_fields=<field_list> |
display only specific fields, use - before field
names to exclude those fields, e.g. _fields=-descripton |
Query syntax for Elasticsearch¶
Additional parameters are available when using an Elasticsearch-enabled collection (see ESBaseDocument in the Wrapper API section of this documentation).
url parameter | description |
---|---|
<field_name>=<keywords> |
to filter a collection using full-text search on <field_name>, ES operators [2] can be used, e.g. ?title=foo AND bar |
<field_name>=(!<keywords>) |
to filter a collection using negative search |
q=<keywords> |
to filter a collection using full-text search on all fields |
_search_fields=<field_list> |
use with ?q=<keywords> to restrict search to specific fields |
_refresh_index=true |
to refresh the ES index after performing the operation [3] |
_aggregations.<dot_notation_object> |
to use ES search aggregations,
e.g. ?_aggregations.my_agg.terms.field=tag [4] |
Updating listfields¶
Items in listfields can be removed using “-” prefix.
$ curl -XPATCH 'http://localhost:6543/api/<collection>/<id>' -d '{
"<list_field_name>": [-<item>]
}
'
Items can be both added and removed at the same time.
$ curl -XPATCH 'http://localhost:6543/api/<collection>/<id>' -d '{
"<list_field_name>": [<item_to_add>,-<item_to_remove>]
}
'
Listfields can be emptied by setting their value to “” or null.
$ curl -XPATCH 'http://localhost:6543/api/<collection>/<id>' -d '{
"<list_field_name>": ""
}
'
Updating collections¶
If update_many() is defined in your view, you will be able to update a single field across an entire collection or a filtered collection. E.g.
$ curl -XPATCH 'http://localhost:6543/api/<collection>?q=<keywords>' -d '{
"<field_name>": "<new_value>"
}
'
Deleting collections¶
Similarly, if delete_many() is defined, you will be able to delete entire collections or filtered collections. E.g.
$ curl -XDELETE 'http://localhost:6543/api/<collection>?_missing_=<field_name>'
[1] | Set enable_get_tunneling = true in your .ini file to enable this feature. To update listfields and dictfields, you can use the following syntax: _m=PATCH&<listfield>.<value>&<dictfield>.<key>=<value> |
[2] | The full syntax of Elasticsearch querying is beyond the scope of this documentation. You can read more on the Elasticsearch Query String Query documentation to do things like fuzzy search: ?name=fuzzy~ or date range search: ?date=[2015-01-01 TO *] |
[3] | Set elasticsearch.enable_refresh_query = true in your .ini file to enable this feature. This parameter only works with POST, PATCH, PUT and DELETE methods. Read more on Elasticsearch Bulk API documentation. |
[4] | Set elasticsearch.enable_aggregations = true in your .ini file to enable this feature. You can also use the short name _aggs. Read more on Elasticsearch Aggregations. |