arangodb/Documentation/DocuBlocks/collectionByExample.md

@brief constructs a query-by-example for a collection collection.byExample(example)

Fetches all documents from a collection that match the specified example and returns a cursor.

You can use toArray, next, or hasNext to access the result. The result can be limited using the skip and limit operator.

An attribute name of the form a.b is interpreted as attribute path, not as attribute. If you use

{ "a": { "c": 1 } }

as example, then you will find all documents, such that the attribute a contains a document of the form { "c": 1 }. For example the document

{ "a" : { "c" : 1 }, "b" : 1 }

will match, but the document

{ "a" : { "c" : 1, "b" : 1 } }

will not.

However, if you use

{ "a.c" : 1 }

then you will find all documents, which contain a sub-document in a that has an attribute c of value 1. Both the following documents

{ "a" : { "c" : 1 }, "b" : 1 }

and

{ "a" : { "c" : 1, "b" : 1 } }

will match.

collection.byExample(path1, value1, ...)

As alternative you can supply an array of paths and values.

@EXAMPLES

Use toArray to get all documents at once:

@EXAMPLE_ARANGOSH_OUTPUT{003_collectionByExample} ~ db._create("users"); db.users.save({ name: "Gerhard" }); db.users.save({ name: "Helmut" }); db.users.save({ name: "Angela" }); db.users.all().toArray(); db.users.byExample({ "_id" : "users/20" }).toArray(); db.users.byExample({ "name" : "Gerhard" }).toArray(); db.users.byExample({ "name" : "Helmut", "_id" : "users/15" }).toArray(); ~ db._drop("users"); @END_EXAMPLE_ARANGOSH_OUTPUT

Use next to loop over all documents:

@EXAMPLE_ARANGOSH_OUTPUT{004_collectionByExampleNext} ~ db._create("users"); db.users.save({ name: "Gerhard" }); db.users.save({ name: "Helmut" }); db.users.save({ name: "Angela" }); var a = db.users.byExample( {"name" : "Angela" } ); while (a.hasNext()) print(a.next()); ~ db._drop("users"); @END_EXAMPLE_ARANGOSH_OUTPUT