Aggregation framework
Aggregation framework
Aggregator context
Aggregator context
Builder for delete operations.
Builder for delete operations.
Delete command element
Delete command element
Result for a delete command
Result for a delete command
A modify operation, part of a FindAndModify command
A modify operation, part of a FindAndModify command
Result for a find-and-modify command
Result for a find-and-modify command
Last error for a find-and-update command
Last error for a find-and-update command
Update (part of a FindAndModify command).
Update (part of a FindAndModify command).
Update (part of a FindAndModify command).
Update (part of a FindAndModify command).
An index hint
An index hint
Builder for insert operations.
Builder for insert operations.
The result of a bulk write operation.
The result of a bulk write operation.
Aggregation pipeline operator/stage
Aggregation pipeline operator/stage
A builder that helps to make a fine-tuned query to MongoDB.
A builder that helps to make a fine-tuned query to MongoDB.
When the query is ready, you can call cursor
to get a Cursor, or one
if you want to retrieve just one document.
Builder for update operations.
Builder for update operations.
Result for the update operations.
Result for the update operations.
An upserted element
An upserted element
A builder for the watch
collection helper,
which allows to consume the collection's ChangeStream.
A builder for the watch
collection helper,
which allows to consume the collection's ChangeStream.
The database which this collection belongs to.
The database which this collection belongs to.
The name of the collection.
The name of the collection.
The serialization pack (BSON by default).
The serialization pack (BSON by default).
Used to resolve the types of values
(by default BSONValue
, BSONDocument
, ...), and the related typeclasses
(e.g. BSONDocumentReader
...).
The default read preference
The default read preference
Returns a new reference to the same collection, with the given read preference.
The aggregation framework for this collection
The aggregation framework for this collection
Remove (part of a FindAndModify command).
Remove (part of a FindAndModify command).
Aggregates the matching documents.
Aggregates the matching documents.
The type of the result elements. An implicit Reader[T]
typeclass for handling it has to be in the scope.
if true indicates to return the information on the processing of the pipeline
if true enables writing to temporary files
the flag to bypass document validation during the operation (default: false
)
the read concern
the read preference for the result (default: primary)
the batch size (for the aggregation cursor; if None
use the default one)
the function to create the aggregation pipeline using the aggregation framework depending on the collection type
the result reader
EXPERIMENTAL:
Returns an update modifier, to be used with findAndModify
.
EXPERIMENTAL:
Returns an update modifier, to be used with findAndModify
.
the aggregation pipeline
the command result must be the new object instead of the old one
if true, creates a new document if no document is matching, otherwise if at least one document matches, an update is applied
Aggregates the matching documents.
Aggregates the matching documents.
import scala.concurrent.Future import scala.concurrent.ExecutionContext.Implicits.global import reactivemongo.api.Cursor import reactivemongo.api.bson._ import reactivemongo.api.bson.collection.BSONCollection def populatedStates(cities: BSONCollection): Future[List[BSONDocument]] = { import cities.AggregationFramework import AggregationFramework.{ Group, Match, SumField } cities.aggregatorContext[BSONDocument]( List(Group(BSONString(f"$$state"))( "totalPop" -> SumField("population")), Match(BSONDocument("totalPop" -> BSONDocument(f"$$gte" -> 10000000L)))) ).prepared.cursor.collect[List]( maxDocs = 3, err = Cursor.FailOnError[List[BSONDocument]]() ) }
The type of the result elements. An implicit Reader[T]
typeclass for handling it has to be in the scope.
the aggregation pipeline
if true indicates to return the information on the processing of the pipeline (default: false
)
if true enables writing to temporary files (default: false
)
the flag to bypass document validation during the operation (default: false
)
the read concern
the read preference for the result
the writer concern to be used
the batch size (for the aggregation cursor; if None
use the default one)
the options for the result cursor
In practice, this parameter controls the duration of the long-polling behavior of the cursor.
the index to use (either the index name or the index document)
the comment to annotation the aggregation command
the collation
the result reader
Converts this collection to a capped one.
Converts this collection to a capped one.
import scala.concurrent.{ ExecutionContext, Future } def capColl(coll: reactivemongo.api.bson.collection.BSONCollection)( implicit ec: ExecutionContext): Future[Unit] = coll.convertToCapped(size = 10L, maxDocuments = Some(100))
the size of the collection (number of bytes)
the maximum number of documents this capped collection can contain
Counts the matching documents.
Counts the matching documents.
the document selector
the maximum number of matching documents to count
the number of matching documents to skip before counting
the index to use (either the index name or the index document; see hint(..)
)
the read concern
the read preference for the result
Creates this collection.
Creates this collection.
import scala.concurrent.{ ExecutionContext, Future } import reactivemongo.api.collections.GenericCollection def createIfNotExists(coll: GenericCollection[_])( implicit ec: ExecutionContext): Future[Unit] = coll.create(failsIfExists = true)
if true fails if the collection already exists (default: false)
the writer concern to be used
Creates this collection.
Creates this collection.
The returned future will be completed, with an error if this collection already exists.
import scala.concurrent.ExecutionContext import reactivemongo.api.collections.GenericCollection import reactivemongo.api.commands.CommandException def createColl( coll: GenericCollection[_])(implicit ec: ExecutionContext) = coll.create().recover { case CommandException.Code(48) => // NamespaceExists println(s"Collection \${coll} already exists") }
Creates this collection as a capped one.
Creates this collection as a capped one.
The returned future will be completed with an error if this collection already exists.
import scala.concurrent.{ ExecutionContext, Future } def capped(coll: reactivemongo.api.bson.collection.BSONCollection)( implicit ec: ExecutionContext): Future[Unit] = coll.createCapped(size = 10, maxDocuments = Some(100))
the size of the collection (number of bytes)
the maximum number of documents this capped collection can contain
Creates a view on this collection, using an aggregation pipeline.
Creates a view on this collection, using an aggregation pipeline.
the name of the view to be created
the first (required) operator for the aggregation pipeline
the other pipeline operators
the view collation
MongoDB 3.4
import scala.concurrent.ExecutionContext import reactivemongo.api.bson.{ BSONDocument, BSONString } import reactivemongo.api.bson.collection.BSONCollection def foo(coll: BSONCollection)(implicit ec: ExecutionContext) = { import coll.AggregationFramework import AggregationFramework.{ Group, Match, SumField } // See http://docs.mongodb.org/manual/tutorial/aggregation-zip-code-data-set/#return-states-with-populations-above-10-million // Create 'myview' coll.createView( name = "myview", operator = Group(BSONString(f"$$state"))( "totalPop" -> SumField("population")), pipeline = Seq(Match( BSONDocument("totalPop" -> BSONDocument(f"$$gte" -> 10000000L))))) // Then the view can be resolved as any collection // (but won't be writeable) coll.db[BSONCollection]("myview") }
Prepares a delete builder.
Prepares a delete builder.
the ordered behaviour
the writer concern to be used
import scala.concurrent.ExecutionContext import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def foo(coll: BSONCollection, query: BSONDocument)( implicit ec: ExecutionContext) = coll.delete(true).one(query)
Prepares an unordered delete builder.
Prepares an unordered delete builder.
import scala.concurrent.ExecutionContext import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def doIt(coll: BSONCollection, query: BSONDocument)( implicit ec: ExecutionContext) = coll.delete.one(query) def equivalentTo(coll: BSONCollection) = coll.delete(false)
Returns the distinct values for a specified field across a single collection.
Returns the distinct values for a specified field across a single collection.
the element type of the distinct values
the container, that must be a scala.collection.Iterable
the field for which to return distinct values
the document selector, that specifies the documents from which to retrieve the distinct values.
the read concern
the collation
import scala.concurrent.ExecutionContext import reactivemongo.api.ReadConcern import reactivemongo.api.bson.collection.BSONCollection def distinctStates(coll: BSONCollection)(implicit ec: ExecutionContext) = coll.distinct[String, Set]("state", None, ReadConcern.Local, None)
Drops this collection.
Drops this collection.
If the collection existed and is successfully dropped, the returned future will be completed with true.
If failIfNotFound
is false and the collection doesn't exist,
the returned future will be completed with false.
Otherwise in case, the future will be completed with the encountered error.
import scala.concurrent.{ ExecutionContext, Future } import reactivemongo.api.collections.GenericCollection def dropIfNotFound(coll: GenericCollection[_])( implicit ec: ExecutionContext): Future[Boolean] = coll.drop(failIfNotFound = true)
the flag to request whether it should fail
Drops this collection.
Drops this collection.
The returned future will be completed with an error if this collection does not exist.
Finds the documents matching the given criteria (selector), with the projection applied.
Finds the documents matching the given criteria (selector), with the projection applied.
The type of the selector. An implicit Writer[S]
typeclass for handling it has to be in the scope.
the document selector
the projection document to select only a subset of each matching documents
the writer for the selector
the writer for the projection
A query builder you can use to customize the query. You can obtain a cursor by calling the method reactivemongo.api.Cursor on this query builder.
Finds the documents matching the given criteria (selector), with the projection applied.
Finds the documents matching the given criteria (selector), with the projection applied.
The type of the selector. An implicit Writer[S]
typeclass for handling it has to be in the scope.
the document selector
the writer for the selector
A query builder you can use to customize the query. You can obtain a cursor by calling the method reactivemongo.api.Cursor on this query builder.
Applies a findAndModify operation.
Applies a findAndModify operation. See findAndUpdate
and findAndRemove
convenient functions.
import scala.concurrent.{ ExecutionContext, Future } import reactivemongo.api.bson.{ BSONDocument, BSONDocumentReader } import reactivemongo.api.bson.collection.BSONCollection case class Person(name: String, age: Int) def foo(coll: BSONCollection)( implicit ec: ExecutionContext, r: BSONDocumentReader[Person]) = { val updateOp = coll.updateModifier( BSONDocument(f"$$set" -> BSONDocument("age" -> 35))) val personBeforeUpdate: Future[Option[Person]] = coll.findAndModify(BSONDocument("name" -> "Joline"), updateOp). map(_.result[Person]) val removedPerson: Future[Option[Person]] = coll.findAndModify( BSONDocument("name" -> "Jack"), coll.removeModifier). map(_.result[Person]) val _ = List(personBeforeUpdate, removedPerson) }
the document selector
the modify operator to be applied
the document indicating the sort criteria (default: None
)
the projection fields
the flag to bypass document validation during the operation (default: false
)
the writer concern to be used
the time limit for processing operations on a cursor (maxTimeMS
)
the collation
an array of filter documents that determines which array elements to modify for an update operation on an array field
the writer for the selector
Finds some matching document, and removes it (using findAndModify
).
Finds some matching document, and removes it (using findAndModify
).
import scala.concurrent.{ ExecutionContext, Future } import reactivemongo.api.bson.{ BSONDocument, BSONDocumentReader } import reactivemongo.api.bson.collection.BSONCollection case class Person(name: String, age: Int) def removed(coll: BSONCollection)( implicit ec: ExecutionContext, r: BSONDocumentReader[Person]): Future[Option[Person]] = coll.findAndRemove( BSONDocument("name" -> "Foo")).map(_.result[Person])
The type of the selector. An implicit Writer[S]
typeclass for handling it has to be in the scope.
the document selector
the document indicating the sort criteria
the projection fields
the writer concern to be used
the time limit for processing operations on a cursor (maxTimeMS
)
the collation
an array of filter documents that determines which array elements to modify for an update operation on an array field
the writer for the selector
Finds some matching document, and updates it (using findAndModify
).
Finds some matching document, and updates it (using findAndModify
).
import scala.concurrent.{ ExecutionContext, Future } import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def findPerson(coll: BSONCollection)( implicit ec: ExecutionContext): Future[Option[BSONDocument]] = coll.findAndUpdate( BSONDocument("name" -> "James"), BSONDocument(f"$$set" -> BSONDocument("age" -> 17)), fetchNewObject = true).map(_.value) // on success, return the update document: { "age": 17 }
the document selector
the update to be applied
the command result must be the new object instead of the old one (default: false
)
if true, creates a new document if no document is matching, otherwise if at least one document matches, an update is applied (default: false
)
the document indicating the sort criteria (default: None
)
the projection fields
the flag to bypass document validation during the operation (default: false
)
the writer concern to be used
the time limit for processing operations on a cursor (maxTimeMS
)
the collation
an array of filter documents that determines which array elements to modify for an update operation on an array field
the writer for the selector
the writer to create the document
EXPERIMENTAL:
Finds some matching document, and updates it (using findAndModify
).
EXPERIMENTAL:
Finds some matching document, and updates it (using findAndModify
).
import scala.concurrent.{ ExecutionContext, Future } import reactivemongo.api.bson.{ BSONArray, BSONDocument } import reactivemongo.api.bson.collection.BSONCollection def findPerson(coll: BSONCollection)( implicit ec: ExecutionContext): Future[Option[BSONDocument]] = { import coll.AggregationFramework.{ PipelineOperator, Set } val pipeline = List[PipelineOperator]( Set(BSONDocument("age" -> BSONDocument( f"$$add" -> BSONArray(f"$$age", 2))))) coll.findAndUpdateWithPipeline( BSONDocument("name" -> "James"), pipeline, fetchNewObject = true).map(_.value) // on success, return the update document: { "age": 17 } }
the document selector
the aggregation pipeline
the command result must be the new object instead of the old one (default: false
)
if true, creates a new document if no document is matching, otherwise if at least one document matches, an update is applied (default: false
)
the document indicating the sort criteria (default: None
)
the projection fields
the flag to bypass document validation during the operation (default: false
)
the writer concern to be used
the time limit for processing operations on a cursor (maxTimeMS
)
the collation
an array of filter documents that determines which array elements to modify for an update operation on an array field
the writer for the selector
Returns a hint for the given index specification
document.
Returns a hint for the given index specification
document.
the index specification document
Returns a hint for the given index name
.
Returns a hint for the given index name
.
the index name
Returns an index manager for this collection.
Returns an index manager for this collection.
import scala.concurrent.{ ExecutionContext, Future } import reactivemongo.api.collections.GenericCollection def listIndexes(coll: GenericCollection[_])( implicit ec: ExecutionContext): Future[List[String]] = coll.indexesManager.list().map(_.flatMap { idx => idx.name.toList })
Returns a builder for insert operations.
Returns a builder for insert operations.
the ordered behaviour
the writer concern to be used
the flag to bypass document validation during the operation
import scala.concurrent.ExecutionContext import reactivemongo.api.WriteConcern import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def withDefaultWriteConcern(coll: BSONCollection, query: BSONDocument)( implicit ec: ExecutionContext) = coll.insert(true, WriteConcern.Journaled, true).one(query)
Returns a builder for insert operations.
Returns a builder for insert operations. Uses the default write concern.
the ordered behaviour
the flag to bypass document validation during the operation
import scala.concurrent.ExecutionContext import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def withDefaultWriteConcern(coll: BSONCollection, query: BSONDocument)( implicit ec: ExecutionContext) = coll.insert(true, false).one(query)
Returns a builder for insert operations.
Returns a builder for insert operations.
the ordered behaviour
the writer concern to be used
import scala.concurrent.ExecutionContext import reactivemongo.api.WriteConcern import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def withDefaultWriteConcern(coll: BSONCollection, query: BSONDocument)( implicit ec: ExecutionContext) = coll.insert(true, WriteConcern.Journaled).one(query)
Returns an ordered builder for insert operations.
Returns an ordered builder for insert operations.
the writer concern to be used
import scala.concurrent.ExecutionContext import reactivemongo.api.WriteConcern import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def one(coll: BSONCollection, singleDoc: BSONDocument)( implicit ec: ExecutionContext) = coll.insert(writeConcern = WriteConcern.Default).one(singleDoc) def many(coll: BSONCollection, multiInserts: Iterable[BSONDocument])( implicit ec: ExecutionContext) = coll.insert(writeConcern = WriteConcern.Default).many(multiInserts)
Returns a builder for insert operations.
Returns a builder for insert operations. Uses the default write concern.
the ordered behaviour
import scala.concurrent.ExecutionContext import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def one(coll: BSONCollection, singleDoc: BSONDocument)( implicit ec: ExecutionContext) = coll.insert(ordered = true).one(singleDoc) def many(coll: BSONCollection, multiInserts: Iterable[BSONDocument])( implicit ec: ExecutionContext) = coll.insert(ordered = true).many(multiInserts)
Returns an unordered builder for insert operations.
Returns an unordered builder for insert operations. Uses the default write concern.
The default read concern
The default read concern
Returns a removal modifier, to be used with findAndModify
.
Returns a removal modifier, to be used with findAndModify
.
The command runner
The command runner
Returns various information about this collection.
Returns various information about this collection.
import scala.concurrent.{ ExecutionContext, Future } def getSize(coll: reactivemongo.api.bson.collection.BSONCollection)( implicit ec: ExecutionContext): Future[Double] = coll.stats(scale = 1024).map(_.size)
the scale factor (for example, to get all the sizes in kilobytes)
Returns various information about this collection.
Returns various information about this collection.
import scala.concurrent.{ ExecutionContext, Future } def isCapped(coll: reactivemongo.api.bson.collection.BSONCollection)( implicit ec: ExecutionContext): Future[Boolean] = coll.stats().map(_.capped)
Returns an update builder.
Returns an update builder.
import scala.concurrent.ExecutionContext import reactivemongo.api.WriteConcern import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def myUpdate( coll: BSONCollection, query: BSONDocument, update: BSONDocument, wc: WriteConcern )(implicit ec: ExecutionContext) = coll.update( ordered = false, writeConcern = wc, bypassDocumentValidation = true ).one(query, update)
the ordered behaviour
the writer concern to be used
the flag to bypass document validation during the operation
Returns an update builder.
Returns an update builder. Uses the default write concern.
import scala.concurrent.ExecutionContext import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def withDefaultWriteConcern( coll: BSONCollection, query: BSONDocument, update: BSONDocument )(implicit ec: ExecutionContext) = coll.update( ordered = false, bypassDocumentValidation = true ).one(query, update)
the ordered behaviour
the flag to bypass document validation during the operation
Returns an update builder.
Returns an update builder.
import scala.concurrent.ExecutionContext import reactivemongo.api.WriteConcern import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def myUpdate( coll: BSONCollection, query: BSONDocument, update: BSONDocument, wc: WriteConcern )(implicit ec: ExecutionContext) = coll.update(ordered = false, writeConcern = wc).one(query, update)
the ordered behaviour
the writer concern to be used
Returns an ordered update builder.
Returns an ordered update builder.
import scala.concurrent.ExecutionContext import reactivemongo.api.WriteConcern import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def orderedUpdate( coll: BSONCollection, query: BSONDocument, update: BSONDocument, wc: WriteConcern )(implicit ec: ExecutionContext) = coll.update(writeConcern = wc).one(query, update)
the writer concern to be used
Returns an update builder.
Returns an update builder. Uses the default write concern.
import scala.concurrent.ExecutionContext import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def withDefaultWriteConcern( coll: BSONCollection, query: BSONDocument, update: BSONDocument )(implicit ec: ExecutionContext) = { coll.update(ordered = true). one(query, update, upsert = false, multi = false) }
the ordered behaviour
Returns an unordered update builder.
Returns an unordered update builder. Uses the default write concern.
import scala.concurrent.ExecutionContext import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def withDefaultWriteConcern( coll: BSONCollection, query: BSONDocument, update: BSONDocument )(implicit ec: ExecutionContext) = { coll.update.one(query, update, upsert = false, multi = false) }
Returns an update modifier, to be used with findAndModify
.
Returns an update modifier, to be used with findAndModify
.
the update to be applied
the command result must be the new object instead of the old one
if true, creates a new document if no document is matching, otherwise if at least one document matches, an update is applied
Upper MongoDB version (used for version checks)
Upper MongoDB version (used for version checks)
EXPERIMENTAL: Prepares a builder for watching the change stream of this collection.
EXPERIMENTAL: Prepares a builder for watching the change stream of this collection.
Note: The target mongo instance MUST be a replica-set (even in the case of a single node deployement).
import reactivemongo.api.Cursor import reactivemongo.api.bson.BSONDocument import reactivemongo.api.bson.collection.BSONCollection def events(coll: BSONCollection): Cursor[BSONDocument] = coll.watch[BSONDocument]().cursor
the type into which Change Events are deserialized
the change stream offset
The sequence of aggregation stages to apply on events in the stream (see MongoDB documentation for a list of valid stages for a change stream).
if set to UpdateLookup, every update change event will be joined with the current version of the relevant document.
the reader of the resulting change events
MongoDB 3.6
The default write concern
The default write concern
The read preference for the write operations (primary)
The read preference for the write operations (primary)
A Collection that provides default methods using a
SerializationPack
.Some methods of this collection accept instances of
Reader[T]
andWriter[T]
, that transform anyT
instance into a document, compatible with the selected serialization pack, and vice-versa.the serialization pack