2.3 KiB
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock collectionByExample
/// @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
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////