arangodb/Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_by_example.md

@startDocuBlock put_api_simple_by_example @brief returns all documents of a collection matching a given example

@RESTHEADER{PUT /_api/simple/by-example, Simple query by-example}

@HINTS {% hint 'warning' %} This route should no longer be used. All endpoints for Simple Queries are deprecated from version 3.4.0 on. They are superseded by AQL queries. {% endhint %}

{% hint 'warning' %} Till ArangoDB versions 3.2.13 and 3.3.7 this API is quite expensive. A more lightweight alternative is to use the HTTP Cursor API. Starting from versions 3.2.14 and 3.3.8 this performance impact is not an issue anymore, as the internal implementation of the API has changed. {% endhint %}

@RESTBODYPARAM{collection,string,required,string} The name of the collection to query.

@RESTBODYPARAM{example,string,required,string} The example document.

@RESTBODYPARAM{skip,string,required,string} The number of documents to skip in the query (optional).

@RESTBODYPARAM{limit,string,required,string} The maximal amount of documents to return. The skip is applied before the limit restriction. (optional)

@RESTBODYPARAM{batchSize,integer,optional,int64} maximum number of result documents to be transferred from the server to the client in one roundtrip. If this attribute is not set, a server-controlled default value will be used. A batchSize value of 0 is disallowed.

@RESTDESCRIPTION

This will find all documents matching a given example.

Returns a cursor containing the result, see HTTP Cursor for details.

@RESTRETURNCODES

@RESTRETURNCODE{201} is returned if the query was executed successfully.

@RESTRETURNCODE{400} is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case.

@RESTRETURNCODE{404} is returned if the collection specified by collection is unknown. The response body contains an error document in this case.

@EXAMPLES

Matching an attribute

@EXAMPLE_ARANGOSH_RUN{RestSimpleByExample} var cn = "products"; db._drop(cn); var products = db._create(cn); products.save({ "a": { "k": 1, "j": 1 }, "i": 1}); products.save({ "a": { "j": 1 }, "i": 1}); products.save({ "i": 1}); products.save({ "a": { "k": 2, "j": 2 }, "i": 1}); var url = "/_api/simple/by-example"; var body = { "collection": "products", "example" : { "i" : 1 } };

var response = logCurlRequest('PUT', url, body);

assert(response.code === 201);

logJsonResponse(response);
db._drop(cn);

@END_EXAMPLE_ARANGOSH_RUN

Matching an attribute which is a sub-document

@EXAMPLE_ARANGOSH_RUN{RestSimpleByExample2} var cn = "products"; db._drop(cn); var products = db._create(cn); products.save({ "a": { "k": 1, "j": 1 }, "i": 1}); products.save({ "a": { "j": 1 }, "i": 1}); products.save({ "i": 1}); products.save({ "a": { "k": 2, "j": 2 }, "i": 1}); var url = "/_api/simple/by-example"; var body = { "collection": "products", "example" : { "a.j" : 1 } };

var response = logCurlRequest('PUT', url, body);

assert(response.code === 201);

logJsonResponse(response);
db._drop(cn);

@END_EXAMPLE_ARANGOSH_RUN

Matching an attribute within a sub-document

@EXAMPLE_ARANGOSH_RUN{RestSimpleByExample3} var cn = "products"; db._drop(cn); var products = db._create(cn); products.save({ "a": { "k": 1, "j": 1 }, "i": 1}); products.save({ "a": { "j": 1 }, "i": 1}); products.save({ "i": 1}); products.save({ "a": { "k": 2, "j": 2 }, "i": 1}); var url = "/_api/simple/by-example"; var body = { "collection": "products", "example" : { "a" : { "j" : 1 } } };

var response = logCurlRequest('PUT', url, body);

assert(response.code === 201);

logJsonResponse(response);
db._drop(cn);

@END_EXAMPLE_ARANGOSH_RUN @endDocuBlock