@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