Documentation for collection

pull/13/head
Thijs Cadier 9 years ago
parent 4b86f8f1f3
commit 3c56489dca

@ -1,3 +1,7 @@
//! Access to a MongoDB collection
//!
//! Collection is the main type used when accessing collections.
use std::ptr; use std::ptr;
use std::ffi::CStr; use std::ffi::CStr;
use std::borrow::Cow; use std::borrow::Cow;
@ -20,6 +24,7 @@ use super::flags::{Flags,FlagsValue,InsertFlag,QueryFlag,RemoveFlag,UpdateFlag};
use super::write_concern::WriteConcern; use super::write_concern::WriteConcern;
use super::read_prefs::ReadPrefs; use super::read_prefs::ReadPrefs;
#[doc(hidden)]
pub enum CreatedBy<'a> { pub enum CreatedBy<'a> {
BorrowedClient(&'a Client<'a>), BorrowedClient(&'a Client<'a>),
OwnedClient(Client<'a>), OwnedClient(Client<'a>),
@ -27,14 +32,18 @@ pub enum CreatedBy<'a> {
OwnedDatabase(Database<'a>) OwnedDatabase(Database<'a>)
} }
/// Provides access to a collection for most CRUD operations, I.e. insert, update, delete, find, etc.
///
/// A collection instance can be created by calling `get_collection` on a `Client` or `Database`
/// instance.
pub struct Collection<'a> { pub struct Collection<'a> {
_created_by: CreatedBy<'a>, _created_by: CreatedBy<'a>,
inner: *mut bindings::mongoc_collection_t inner: *mut bindings::mongoc_collection_t
} }
/// Options to configure a `BulkOperation`. /// Options to configure a bulk operation.
pub struct BulkOperationOptions { pub struct BulkOperationOptions {
/// If the operations must be performed in order. /// If the operations must be performed in order
pub ordered: bool, pub ordered: bool,
/// `WriteConcern` to use /// `WriteConcern` to use
pub write_concern: WriteConcern pub write_concern: WriteConcern
@ -51,13 +60,18 @@ impl BulkOperationOptions {
} }
} }
/// Options to configure a find and modify operation.
pub struct FindAndModifyOptions { pub struct FindAndModifyOptions {
/// Sort order for the query
pub sort: Option<Document>, pub sort: Option<Document>,
/// If the new version of the document should be returned
pub new: bool, pub new: bool,
/// The fields to return
pub fields: Option<Document> pub fields: Option<Document>
} }
impl FindAndModifyOptions { impl FindAndModifyOptions {
/// Default options used if none are provided.
pub fn default() -> FindAndModifyOptions { pub fn default() -> FindAndModifyOptions {
FindAndModifyOptions { FindAndModifyOptions {
sort: None, sort: None,
@ -74,21 +88,32 @@ impl FindAndModifyOptions {
} }
} }
/// Possible find and modify operations.
pub enum FindAndModifyOperation<'a> { pub enum FindAndModifyOperation<'a> {
/// Update the matching documents
Update(&'a Document), Update(&'a Document),
/// Upsert the matching documents
Upsert(&'a Document), Upsert(&'a Document),
/// Remove the matching documents
Remove Remove
} }
/// Options to configure a count operation.
pub struct CountOptions { pub struct CountOptions {
/// The query flags to use
pub query_flags: Flags<QueryFlag>, pub query_flags: Flags<QueryFlag>,
/// Number of results to skip, zero to ignore
pub skip: u32, pub skip: u32,
/// Limit to the number of results, zero to ignore
pub limit: u32, pub limit: u32,
/// Optional extra keys to add to the count
pub opts: Option<Document>, pub opts: Option<Document>,
/// Read prefs to use
pub read_prefs: Option<ReadPrefs> pub read_prefs: Option<ReadPrefs>
} }
impl CountOptions { impl CountOptions {
/// Default options used if none are provided.
pub fn default() -> CountOptions { pub fn default() -> CountOptions {
CountOptions { CountOptions {
query_flags: Flags::new(), query_flags: Flags::new(),
@ -100,12 +125,16 @@ impl CountOptions {
} }
} }
/// Options to configure an insert operation.
pub struct InsertOptions { pub struct InsertOptions {
/// Flags to use
pub insert_flags: Flags<InsertFlag>, pub insert_flags: Flags<InsertFlag>,
/// Write concern to use
pub write_concern: WriteConcern pub write_concern: WriteConcern
} }
impl InsertOptions { impl InsertOptions {
/// Default options used if none are provided.
pub fn default() -> InsertOptions { pub fn default() -> InsertOptions {
InsertOptions { InsertOptions {
insert_flags: Flags::new(), insert_flags: Flags::new(),
@ -114,12 +143,16 @@ impl InsertOptions {
} }
} }
/// Options to configure a remove operation.
pub struct RemoveOptions { pub struct RemoveOptions {
/// Flags to use
pub remove_flags: Flags<RemoveFlag>, pub remove_flags: Flags<RemoveFlag>,
/// Write concern to use
pub write_concern: WriteConcern pub write_concern: WriteConcern
} }
impl RemoveOptions { impl RemoveOptions {
/// Default options used if none are provided.
pub fn default() -> RemoveOptions { pub fn default() -> RemoveOptions {
RemoveOptions { RemoveOptions {
remove_flags: Flags::new(), remove_flags: Flags::new(),
@ -128,12 +161,16 @@ impl RemoveOptions {
} }
} }
/// Options to configure an update operation.
pub struct UpdateOptions { pub struct UpdateOptions {
/// Flags to use
pub update_flags: Flags<UpdateFlag>, pub update_flags: Flags<UpdateFlag>,
/// Write concern to use
pub write_concern: WriteConcern pub write_concern: WriteConcern
} }
impl UpdateOptions { impl UpdateOptions {
/// Default options used if none are provided.
pub fn default() -> UpdateOptions { pub fn default() -> UpdateOptions {
UpdateOptions { UpdateOptions {
update_flags: Flags::new(), update_flags: Flags::new(),
@ -142,12 +179,16 @@ impl UpdateOptions {
} }
} }
/// Options to configure a tailing query.
pub struct TailOptions { pub struct TailOptions {
/// Duration to wait before checking for new results
pub wait_duration: Duration, pub wait_duration: Duration,
/// Maximum number of retries if there is an error
pub max_retries: u32 pub max_retries: u32
} }
impl TailOptions { impl TailOptions {
/// Default options used if none are provided.
pub fn default() -> TailOptions { pub fn default() -> TailOptions {
TailOptions { TailOptions {
wait_duration: Duration::from_millis(500), wait_duration: Duration::from_millis(500),
@ -157,6 +198,7 @@ impl TailOptions {
} }
impl<'a> Collection<'a> { impl<'a> Collection<'a> {
#[doc(hidden)]
pub fn new( pub fn new(
created_by: CreatedBy<'a>, created_by: CreatedBy<'a>,
inner: *mut bindings::mongoc_collection_t inner: *mut bindings::mongoc_collection_t
@ -169,8 +211,7 @@ impl<'a> Collection<'a> {
} }
/// Execute a command on the collection /// Execute a command on the collection
/// /// This is performed lazily and therefore requires calling `next` on the resulting cursor.
/// See: http://api.mongodb.org/c/current/mongoc_collection_command.html
pub fn command( pub fn command(
&'a self, &'a self,
command: Document, command: Document,
@ -212,19 +253,14 @@ impl<'a> Collection<'a> {
)) ))
} }
/// Simplified version of command that returns the first document /// Simplified version of `command` that returns the first document immediately.
///
/// See: http://api.mongodb.org/c/current/mongoc_database_command_simple.html
pub fn command_simple( pub fn command_simple(
&'a self, &'a self,
command: Document, command: Document,
options: Option<&CommandAndFindOptions> read_prefs: Option<&ReadPrefs>
) -> Result<Document> { ) -> Result<Document> {
assert!(!self.inner.is_null()); assert!(!self.inner.is_null());
let default_options = CommandAndFindOptions::default();
let options = options.unwrap_or(&default_options);
// Bsonc to store the reply // Bsonc to store the reply
let mut reply = Bsonc::new(); let mut reply = Bsonc::new();
// Empty error that might be filled // Empty error that might be filled
@ -234,7 +270,7 @@ impl<'a> Collection<'a> {
bindings::mongoc_collection_command_simple( bindings::mongoc_collection_command_simple(
self.inner, self.inner,
try!(Bsonc::from_document(&command)).inner(), try!(Bsonc::from_document(&command)).inner(),
match options.read_prefs { match read_prefs {
Some(ref prefs) => prefs.inner(), Some(ref prefs) => prefs.inner(),
None => ptr::null() None => ptr::null()
}, },
@ -253,6 +289,10 @@ impl<'a> Collection<'a> {
} }
} }
/// Execute a count query on the underlying collection.
/// The `query` bson is not validated, simply passed along to the server. As such, compatibility and errors should be validated in the appropriate server documentation.
///
/// For more information, see the [query reference](https://docs.mongodb.org/manual/reference/operator/query/) at the MongoDB website.
pub fn count( pub fn count(
&self, &self,
query: &Document, query: &Document,
@ -294,6 +334,9 @@ impl<'a> Collection<'a> {
} }
} }
/// Create a bulk operation. After creating call various functions such as `update`,
/// `insert` and others. When calling `execute` these operations will be executed in
/// batches.
pub fn create_bulk_operation( pub fn create_bulk_operation(
&'a self, &'a self,
options: Option<&BulkOperationOptions> options: Option<&BulkOperationOptions>
@ -314,6 +357,7 @@ impl<'a> Collection<'a> {
BulkOperation::new(self, inner) BulkOperation::new(self, inner)
} }
/// Request that a collection be dropped, including all indexes associated with the collection.
pub fn drop(&mut self) -> Result<()> { pub fn drop(&mut self) -> Result<()> {
assert!(!self.inner.is_null()); assert!(!self.inner.is_null());
let mut error = BsoncError::empty(); let mut error = BsoncError::empty();
@ -330,6 +374,10 @@ impl<'a> Collection<'a> {
Ok(()) Ok(())
} }
/// Execute a query on the underlying collection.
/// If no options are necessary, query can simply contain a query such as `{a:1}`.
/// If you would like to specify options such as a sort order, the query must be placed inside of `{"$query": {}}`
/// as specified by the server documentation. See the example below for how to properly specify additional options to query.
pub fn find( pub fn find(
&'a self, &'a self,
query: &Document, query: &Document,
@ -371,10 +419,9 @@ impl<'a> Collection<'a> {
)) ))
} }
// Update and return an object. /// Update and return an object.
// /// This is a thin wrapper around the findAndModify command. Pass in
// This is a thin wrapper around the findAndModify command. Pass in /// an operation that either updates, upserts or removes.
// an operation that either updates, upserts or removes.
pub fn find_and_modify( pub fn find_and_modify(
&'a self, &'a self,
query: &Document, query: &Document,
@ -447,6 +494,7 @@ impl<'a> Collection<'a> {
} }
} }
/// Get the name of the collection.
pub fn get_name(&self) -> Cow<str> { pub fn get_name(&self) -> Cow<str> {
let cstr = unsafe { let cstr = unsafe {
CStr::from_ptr(bindings::mongoc_collection_get_name(self.inner)) CStr::from_ptr(bindings::mongoc_collection_get_name(self.inner))
@ -454,6 +502,9 @@ impl<'a> Collection<'a> {
String::from_utf8_lossy(cstr.to_bytes()) String::from_utf8_lossy(cstr.to_bytes())
} }
/// Insert document into collection.
/// If no `_id` element is found in document, then an id will be generated locally and added to the document.
// TODO: You can retrieve a generated _id from mongoc_collection_get_last_error().
pub fn insert( pub fn insert(
&'a self, &'a self,
document: &Document, document: &Document,
@ -482,6 +533,9 @@ impl<'a> Collection<'a> {
} }
} }
/// Remove documents in the given collection that match selector.
/// The bson `selector` is not validated, simply passed along as appropriate to the server. As such, compatibility and errors should be validated in the appropriate server documentation.
/// If you want to limit deletes to a single document, add the `SingleRemove` flag.
pub fn remove( pub fn remove(
&self, &self,
selector: &Document, selector: &Document,
@ -510,6 +564,8 @@ impl<'a> Collection<'a> {
} }
} }
/// Save a document into the collection. If the document has an `_id` field it will be updated.
/// Otherwise it will be inserted.
pub fn save( pub fn save(
&self, &self,
document: &Document, document: &Document,
@ -537,9 +593,8 @@ impl<'a> Collection<'a> {
} }
} }
/// This function shall update documents in collection that match selector. /// This function updates documents in collection that match selector.
/// /// By default, updates only a single document. Add `MultiUpdate` flag to update multiple documents.
/// See: http://api.mongodb.org/c/current/mongoc_collection_update.html
pub fn update( pub fn update(
&self, &self,
selector: &Document, selector: &Document,
@ -616,7 +671,7 @@ impl<'a> Drop for Collection<'a> {
/// ///
/// Create a `BulkOperation` by calling `create_bulk_operation` on a `Collection`. After adding all of /// Create a `BulkOperation` by calling `create_bulk_operation` on a `Collection`. After adding all of
/// the write operations using the functions on this struct, `execute` to execute the operation on /// the write operations using the functions on this struct, `execute` to execute the operation on
/// the server. After executing the bulk operation is consumed and cannot be used anymore. /// the server in batches. After executing the bulk operation is consumed and cannot be used anymore.
pub struct BulkOperation<'a> { pub struct BulkOperation<'a> {
_collection: &'a Collection<'a>, _collection: &'a Collection<'a>,
inner: *mut bindings::mongoc_bulk_operation_t inner: *mut bindings::mongoc_bulk_operation_t

@ -96,16 +96,24 @@ unsafe extern "C" fn mongoc_log_handler(
} }
} }
/// Options to configure both command and find operations.
pub struct CommandAndFindOptions { pub struct CommandAndFindOptions {
/// Flags to use
pub query_flags: flags::Flags<flags::QueryFlag>, pub query_flags: flags::Flags<flags::QueryFlag>,
/// Number of documents to skip, zero to ignore
pub skip: u32, pub skip: u32,
/// Max number of documents to return, zero to ignore
pub limit: u32, pub limit: u32,
/// Number of documents in each batch, zero to ignore (default is 100)
pub batch_size: u32, pub batch_size: u32,
/// Fields to return, not all commands support this option
pub fields: Option<bson::Document>, pub fields: Option<bson::Document>,
/// Read prefs to use
pub read_prefs: Option<read_prefs::ReadPrefs> pub read_prefs: Option<read_prefs::ReadPrefs>
} }
impl CommandAndFindOptions { impl CommandAndFindOptions {
/// Default options used if none are provided.
pub fn default() -> CommandAndFindOptions { pub fn default() -> CommandAndFindOptions {
CommandAndFindOptions { CommandAndFindOptions {
query_flags: flags::Flags::new(), query_flags: flags::Flags::new(),

Loading…
Cancel
Save