org.mongodb.morphia

Interface Datastore

All Known Subinterfaces:

AdvancedDatastore

All Known Implementing Classes:

DatastoreImpl

public interface Datastore

Datastore interface to get/delete/save objects

Author:

Scott Hernandez

Method Summary

Modifier and Type	Method and Description
AggregationPipeline	createAggregation(Class source) Returns a new query bound to the kind (a specific DBCollection)
<T> Query<T>	createQuery(Class<T> collection) Returns a new query bound to the collection (a specific DBCollection)
<T> UpdateOperations<T>	createUpdateOperations(Class<T> clazz) The builder for all update operations
<T,V> WriteResult	delete(Class<T> clazz, Iterable<V> ids) Deletes the given entities (by id)
<T,V> WriteResult	delete(Class<T> clazz, V id) Deletes the given entity (by id)
<T> WriteResult	delete(Query<T> query) Deletes entities based on the query
<T> WriteResult	delete(Query<T> query, WriteConcern wc) Deletes entities based on the query, with the WriteConcern
<T> WriteResult	delete(T entity) Deletes the given entity (by @Id)
<T> WriteResult	delete(T entity, WriteConcern wc) Deletes the given entity (by @Id), with the WriteConcern
void	ensureCaps() ensure capped DBCollections for Entity(s)
<T> void	ensureIndex(Class<T> clazz, String fields) Ensures (creating if necessary) the index including the field(s) + directions on the given collection name; eg fields = "field1, -field2" ({field1:1, field2:-1})
<T> void	ensureIndex(Class<T> clazz, String name, String fields, boolean unique, boolean dropDupsOnCreate) Ensures (creating if necessary) the index including the field(s) + directions on the given collection name; eg fields = "field1, -field2" ({field1:1, field2:-1})
void	ensureIndexes() Ensures (creating if necessary) the indexes found during class mapping (using @Indexed, @Indexes)
void	ensureIndexes(boolean background) Ensures (creating if necessary) the indexes found during class mapping (using @Indexed, @Indexes) on the given collection name, possibly in the background
<T> void	ensureIndexes(Class<T> clazz) Ensures (creating if necessary) the indexes found during class mapping (using @Indexed, @Indexes)
<T> void	ensureIndexes(Class<T> clazz, boolean background) Ensures (creating if necessary) the indexes found during class mapping (using @Indexed, @Indexes), possibly in the background
Key<?>	exists(Object keyOrEntity) Does a query to check if the keyOrEntity exists in mongodb
<T> Query<T>	find(Class<T> clazz) Find all instances by type
<T,V> Query<T>	find(Class<T> clazz, String property, V value) Find all instances by collectionName, and filter property.
<T,V> Query<T>	find(Class<T> clazz, String property, V value, int offset, int size) Find all instances by type in a different collection than what is mapped on the class given skipping some documents and returning a fixed number of the remaining.
<T> T	findAndDelete(Query<T> query) Deletes the given entities based on the query (first item only).
<T> T	findAndModify(Query<T> query, UpdateOperations<T> operations) Find the first Entity from the Query, and modify it.
<T> T	findAndModify(Query<T> query, UpdateOperations<T> operations, boolean oldVersion) Find the first Entity from the Query, and modify it.
<T> T	findAndModify(Query<T> query, UpdateOperations<T> operations, boolean oldVersion, boolean createIfMissing) Find the first Entity from the Query, and modify it.
<T,V> Query<T>	get(Class<T> clazz, Iterable<V> ids) Find the given entities (by id); shorthand for find("_id in", ids)
<T,V> T	get(Class<T> clazz, V id) Find the given entity (by id); shorthand for find("_id ", id)
<T> T	get(T entity) Find the given entity (by collectionName/id); think of this as refresh
<T> T	getByKey(Class<T> clazz, Key<T> key) Find the given entity (by collectionName/id);
<T> List<T>	getByKeys(Class<T> clazz, Iterable<Key<T>> keys) Find the given entities (by id), verifying they are of the correct type; shorthand for find("_id in", ids)
<T> List<T>	getByKeys(Iterable<Key<T>> keys) Find the given entities (by id); shorthand for find("_id in", ids)
DBCollection	getCollection(Class<?> clazz)
<T> long	getCount(Class<T> clazz) Gets the count this kind (DBCollection)
<T> long	getCount(Query<T> query) Gets the count of items returned by this query; same as query.countAll()
<T> long	getCount(T entity) Gets the count this kind (DBCollection)
DB	getDB()
WriteConcern	getDefaultWriteConcern()
<T> Key<T>	getKey(T entity) Creates a (type-safe) reference to the entity; if stored this will become a DBRef
MongoClient	getMongo() Get the underlying MongoClient that allows connection to the MongoDB instance being used.
QueryFactory	getQueryFactory()
<T> MapreduceResults<T>	mapReduce(MapreduceType type, Query q, Class<T> outputType, MapReduceCommand baseCommand) Runs a map/reduce job at the server; this should be used with a server version 1.7.4 or higher
<T> MapreduceResults<T>	mapReduce(MapreduceType type, Query q, String map, String reduce, String finalize, Map<String,Object> scopeFields, Class<T> outputType) Runs a map/reduce job at the server; this should be used with a server version 1.7.4 or higher
<T> Key<T>	merge(T entity) Work as if you did an update with each field in the entity doing a $set; Only at the top level of the entity.
<T> Key<T>	merge(T entity, WriteConcern wc) Work as if you did an update with each field in the entity doing a $set; Only at the top level of the entity.
<T> Query<T>	queryByExample(T example) Returns a new query based on the example object
<T> Iterable<Key<T>>	save(Iterable<T> entities) Saves the entities (Objects) and updates the @Id field
<T> Iterable<Key<T>>	save(Iterable<T> entities, WriteConcern wc) Saves the entities (Objects) and updates the @Id field, with the WriteConcern
<T> Iterable<Key<T>>	save(T... entities) Saves the entities (Objects) and updates the @Id field
<T> Key<T>	save(T entity) Saves an entity (Object) and updates the @Id field
<T> Key<T>	save(T entity, WriteConcern wc) Saves an entity (Object) and updates the @Id field, with the WriteConcern
void	setDefaultWriteConcern(WriteConcern wc) Sets the default WriteConcern for this Datastore
void	setQueryFactory(QueryFactory queryFactory) Replaces the current QueryFactory with the given value.
<T> UpdateResults	update(Key<T> key, UpdateOperations<T> operations) Updates an entity with the operations; this is an atomic operation
<T> UpdateResults	update(Query<T> query, UpdateOperations<T> operations) Updates all entities found with the operations; this is an atomic operation per entity
<T> UpdateResults	update(Query<T> query, UpdateOperations<T> operations, boolean createIfMissing) Updates all entities found with the operations, if nothing is found insert the update as an entity if "createIfMissing" is true; this is an atomic operation per entity
<T> UpdateResults	update(Query<T> query, UpdateOperations<T> operations, boolean createIfMissing, WriteConcern wc) Updates all entities found with the operations, if nothing is found insert the update as an entity if "createIfMissing" is true; this is an atomic operation per entity
<T> UpdateResults	update(T entity, UpdateOperations<T> operations) Updates an entity with the operations; this is an atomic operation
<T> UpdateResults	updateFirst(Query<T> query, T entity, boolean createIfMissing) updates the first entity found using the entity as a template, if nothing is found insert the update as an entity if "createIfMissing" is true.
<T> UpdateResults	updateFirst(Query<T> query, UpdateOperations<T> operations) Updates the first entity found with the operations; this is an atomic operation
<T> UpdateResults	updateFirst(Query<T> query, UpdateOperations<T> operations, boolean createIfMissing) Updates the first entity found with the operations, if nothing is found insert the update as an entity if "createIfMissing" is true.
<T> UpdateResults	updateFirst(Query<T> query, UpdateOperations<T> operations, boolean createIfMissing, WriteConcern wc) Updates the first entity found with the operations, if nothing is found insert the update as an entity if "createIfMissing" is true.

Method Detail

createAggregation

AggregationPipeline createAggregation(Class source)

Returns a new query bound to the kind (a specific DBCollection)

Parameters:

source - The class to create aggregation against

Returns:

the aggregation pipeline

createQuery

<T> Query<T> createQuery(Class<T> collection)

Returns a new query bound to the collection (a specific DBCollection)

Type Parameters:

T - the type of the query

Parameters:

collection - The collection to query

Returns:

the query

createUpdateOperations

<T> UpdateOperations<T> createUpdateOperations(Class<T> clazz)

The builder for all update operations

Type Parameters:

T - the type to update

Parameters:

clazz - the type to update

Returns:

the new UpdateOperations instance

delete

<T,V> WriteResult delete(Class<T> clazz,
                         V id)

Deletes the given entity (by id)

Type Parameters:

T - the type to delete

V - the type of the id

Parameters:

clazz - the type to delete

id - the ID of the entity to delete

Returns:

results of the delete

delete

<T,V> WriteResult delete(Class<T> clazz,
                         Iterable<V> ids)

Deletes the given entities (by id)

Type Parameters:

T - the type to delete

V - the type of the id

Parameters:

clazz - the type to delete

ids - the IDs of the entity to delete

Returns:

results of the delete

delete

<T> WriteResult delete(Query<T> query)

Deletes entities based on the query

Type Parameters:

T - the type to delete

Parameters:

query - the query to use when finding documents to delete

Returns:

results of the delete

delete

<T> WriteResult delete(Query<T> query,
                       WriteConcern wc)

Deletes entities based on the query, with the WriteConcern

Type Parameters:

T - the type to delete

Parameters:

query - the query to use when finding documents to delete

wc - the WriteConcern to use when deleting

Returns:

results of the delete

delete

<T> WriteResult delete(T entity)

Deletes the given entity (by @Id)

Type Parameters:

T - the type to delete

Parameters:

entity - the entity to delete

Returns:

results of the delete

delete

<T> WriteResult delete(T entity,
                       WriteConcern wc)

Deletes the given entity (by @Id), with the WriteConcern

Type Parameters:

T - the type to delete

Parameters:

entity - the entity to delete

wc - the WriteConcern to use when deleting

Returns:

results of the delete

ensureCaps

void ensureCaps()

ensure capped DBCollections for Entity(s)

ensureIndex

<T> void ensureIndex(Class<T> clazz,
                     String fields)

Ensures (creating if necessary) the index including the field(s) + directions on the given collection name; eg fields = "field1, -field2" ({field1:1, field2:-1})

Type Parameters:

T - the type to index

Parameters:

clazz - the class from which to get the index definitions

fields - the fields to index

ensureIndex

<T> void ensureIndex(Class<T> clazz,
                     String name,
                     String fields,
                     boolean unique,
                     boolean dropDupsOnCreate)

Ensures (creating if necessary) the index including the field(s) + directions on the given collection name; eg fields = "field1, -field2" ({field1:1, field2:-1})

Type Parameters:

T - the type to index

Parameters:

clazz - the class from which to get the index definitions

name - the name of the index to create

fields - the fields to index

unique - true if the index should enforce uniqueness on the fields indexed

dropDupsOnCreate - if unique is true and this is true, any documents with duplicated fields being indexed will be dropped. If this is false, index creation will fail.

ensureIndexes

void ensureIndexes()

Ensures (creating if necessary) the indexes found during class mapping (using @Indexed, @Indexes)

ensureIndexes

void ensureIndexes(boolean background)

Ensures (creating if necessary) the indexes found during class mapping (using @Indexed, @Indexes) on the given collection name, possibly in the background

Parameters:

background - if true, the index will be built in the background. If false, the method will block until the index is created.

ensureIndexes

<T> void ensureIndexes(Class<T> clazz)

Ensures (creating if necessary) the indexes found during class mapping (using @Indexed, @Indexes)

Type Parameters:

T - the type to index

Parameters:

clazz - the class from which to get the index definitions

ensureIndexes

<T> void ensureIndexes(Class<T> clazz,
                       boolean background)

Ensures (creating if necessary) the indexes found during class mapping (using @Indexed, @Indexes), possibly in the background

Type Parameters:

T - the type to index

Parameters:

clazz - the class from which to get the index definitions

background - if true, the index will be built in the background. If false, the method will block until the index is created.

exists

Key<?> exists(Object keyOrEntity)

Does a query to check if the keyOrEntity exists in mongodb

Parameters:

keyOrEntity - the value to check for

Returns:

the key if the entity exists

find

<T> Query<T> find(Class<T> clazz)

Find all instances by type

Type Parameters:

T - the type to query

Parameters:

clazz - the class to use for mapping the results

Returns:

the query

find

<T,V> Query<T> find(Class<T> clazz,
                    String property,
                    V value)

Find all instances by collectionName, and filter property.

This is the same as: find(clazzOrEntity).filter (property, value);

Type Parameters:

T - the type to query

V - the type to filter value

Parameters:

clazz - the class to use for mapping the results

property - the document property to query against

value - the value to check for

Returns:

the query

find

<T,V> Query<T> find(Class<T> clazz,
                    String property,
                    V value,
                    int offset,
                    int size)

Find all instances by type in a different collection than what is mapped on the class given skipping some documents and returning a fixed number of the remaining.

Type Parameters:

T - the type to query

V - the type to filter value

Parameters:

clazz - the class to use for mapping the results

property - the document property to query against

value - the value to check for

offset - the number of results to skip

size - the maximum number of results to return

Returns:

the query

findAndDelete

<T> T findAndDelete(Query<T> query)

Deletes the given entities based on the query (first item only).

Type Parameters:

T - the type to query

Parameters:

query - the query to use when finding entities to delete

Returns:

the deleted Entity

findAndModify

<T> T findAndModify(Query<T> query,
                    UpdateOperations<T> operations)

Find the first Entity from the Query, and modify it.

Type Parameters:

T - the type to query

Parameters:

query - the query to use when finding entities to update

operations - the updates to apply to the matched documents

Returns:

The modified Entity (the result of the update)

findAndModify

<T> T findAndModify(Query<T> query,
                    UpdateOperations<T> operations,
                    boolean oldVersion)

Find the first Entity from the Query, and modify it.

Type Parameters:

T - the type to query

Parameters:

query - the query to find the Entity with; You are not allowed to offset/skip in the query.

operations - the updates to apply to the matched documents

oldVersion - indicated the old version of the Entity should be returned

Returns:

The Entity (the result of the update if oldVersion is false)

findAndModify

<T> T findAndModify(Query<T> query,
                    UpdateOperations<T> operations,
                    boolean oldVersion,
                    boolean createIfMissing)

Find the first Entity from the Query, and modify it.

Type Parameters:

T - the type of the entity

Parameters:

query - the query to find the Entity with; You are not allowed to offset/skip in the query.

operations - the updates to apply to the matched documents

oldVersion - indicated the old version of the Entity should be returned

createIfMissing - if the query returns no results, then a new object will be created (sets upsert=true)

Returns:

The Entity (the result of the update if oldVersion is false)

get

<T,V> Query<T> get(Class<T> clazz,
                   Iterable<V> ids)

Find the given entities (by id); shorthand for find("_id in", ids)

Type Parameters:

T - the type to fetch

V - the type of the ID

Parameters:

clazz - the class to use for mapping

ids - the IDs to query

Returns:

the query to find the entities

get

<T,V> T get(Class<T> clazz,
            V id)

Find the given entity (by id); shorthand for find("_id ", id)

Type Parameters:

T - the type to fetch

V - the type of the ID

Parameters:

clazz - the class to use for mapping

id - the ID to query

Returns:

the matched entity. may be null.

get

<T> T get(T entity)

Find the given entity (by collectionName/id); think of this as refresh

Type Parameters:

T - the type to fetch

Parameters:

entity - The entity to search for

Returns:

the matched entity. may be null.

getByKey

<T> T getByKey(Class<T> clazz,
               Key<T> key)

Find the given entity (by collectionName/id);

Type Parameters:

T - the type to fetch

Parameters:

clazz - the class to use for mapping

key - the key search with

Returns:

the matched entity. may be null.

getByKeys

<T> List<T> getByKeys(Class<T> clazz,
                      Iterable<Key<T>> keys)

Find the given entities (by id), verifying they are of the correct type; shorthand for find("_id in", ids)

Type Parameters:

T - the type to fetch

Parameters:

clazz - the class to use for mapping

keys - the keys to search with

Returns:

the matched entities. may be null.

getByKeys

<T> List<T> getByKeys(Iterable<Key<T>> keys)

Find the given entities (by id); shorthand for find("_id in", ids)

Type Parameters:

T - the type to fetch

Parameters:

keys - the keys to search with

Returns:

the matched entities. may be null.

getCollection

DBCollection getCollection(Class<?> clazz)

Parameters:

clazz - the class to use for mapping

Returns:

the mapped collection for the collection

getCount

<T> long getCount(T entity)

Gets the count this kind (DBCollection)

Type Parameters:

T - the type to count

Parameters:

entity - The entity whose type to count

Returns:

the count

getCount

<T> long getCount(Class<T> clazz)

Gets the count this kind (DBCollection)

Type Parameters:

T - the type to count

Parameters:

clazz - The clazz type to count

Returns:

the count

getCount

<T> long getCount(Query<T> query)

Gets the count of items returned by this query; same as query.countAll()

Type Parameters:

T - the type to count

Parameters:

query - the query to filter the documents to count

Returns:

the count

getDB

DB getDB()

Returns:

the DB this Datastore uses

getDefaultWriteConcern

WriteConcern getDefaultWriteConcern()

Returns:

the default WriteConcern used by this Datastore

setDefaultWriteConcern

void setDefaultWriteConcern(WriteConcern wc)

Sets the default WriteConcern for this Datastore

Parameters:

wc - the default WriteConcern to be used by this Datastore

getKey

<T> Key<T> getKey(T entity)

Creates a (type-safe) reference to the entity; if stored this will become a DBRef

Type Parameters:

T - the type of the entity

Parameters:

entity - the entity whose key is to be returned

Returns:

the Key

getMongo

MongoClient getMongo()

Get the underlying MongoClient that allows connection to the MongoDB instance being used.

Returns:

the MongoClient being used by this datastore.

getQueryFactory

QueryFactory getQueryFactory()

Returns:

the current QueryFactory.

See Also:

QueryFactory

setQueryFactory

void setQueryFactory(QueryFactory queryFactory)

Replaces the current QueryFactory with the given value.

Parameters:

queryFactory - the QueryFactory to use

See Also:

QueryFactory

mapReduce

<T> MapreduceResults<T> mapReduce(MapreduceType type,
                                  Query q,
                                  String map,
                                  String reduce,
                                  String finalize,
                                  Map<String,Object> scopeFields,
                                  Class<T> outputType)

Runs a map/reduce job at the server; this should be used with a server version 1.7.4 or higher

Type Parameters:

T - The type of resulting data

Parameters:

outputType - The type of resulting data; inline is not working yet

type - MapreduceType

q - The query (only the criteria, limit and sort will be used)

map - The map function, in javascript, as a string

reduce - The reduce function, in javascript, as a string

finalize - The finalize function, in javascript, as a string; can be null

scopeFields - Each map entry will be a global variable in all the functions; can be null

Returns:

counts and stuff

mapReduce

<T> MapreduceResults<T> mapReduce(MapreduceType type,
                                  Query q,
                                  Class<T> outputType,
                                  MapReduceCommand baseCommand)

Runs a map/reduce job at the server; this should be used with a server version 1.7.4 or higher

Type Parameters:

T - The type of resulting data

Parameters:

type - MapreduceType

q - The query (only the criteria, limit and sort will be used)

outputType - The type of resulting data; inline is not working yet

baseCommand - The base command to fill in and send to the server

Returns:

counts and stuff

merge

<T> Key<T> merge(T entity)

Work as if you did an update with each field in the entity doing a $set; Only at the top level of the entity.

Type Parameters:

T - the type of the entity

Parameters:

entity - the entity to merge back in to the database

Returns:

the key of the entity

merge

<T> Key<T> merge(T entity,
                 WriteConcern wc)

Work as if you did an update with each field in the entity doing a $set; Only at the top level of the entity.

Type Parameters:

T - the type of the entity

Parameters:

entity - the entity to merge back in to the database

wc - the WriteConcern to use

Returns:

the key of the entity

queryByExample

<T> Query<T> queryByExample(T example)

Returns a new query based on the example object

Type Parameters:

T - the type of the entity

Parameters:

example - the example entity to use when creating the query

Returns:

the query

save

<T> Iterable<Key<T>> save(Iterable<T> entities)

Saves the entities (Objects) and updates the @Id field

Type Parameters:

T - the type of the entity

Parameters:

entities - the entities to save

Returns:

the keys of the entities

save

<T> Iterable<Key<T>> save(Iterable<T> entities,
                          WriteConcern wc)

Saves the entities (Objects) and updates the @Id field, with the WriteConcern

Type Parameters:

T - the type of the entity

Parameters:

entities - the entities to save

wc - the WriteConcern to use

Returns:

the keys of the entities

save

<T> Iterable<Key<T>> save(T... entities)

Saves the entities (Objects) and updates the @Id field

Type Parameters:

T - the type of the entity

Parameters:

entities - the entities to save

Returns:

the keys of the entities

save

<T> Key<T> save(T entity)

Saves an entity (Object) and updates the @Id field

Type Parameters:

T - the type of the entity

Parameters:

entity - the entity to save

Returns:

the keys of the entity

save

<T> Key<T> save(T entity,
                WriteConcern wc)

Saves an entity (Object) and updates the @Id field, with the WriteConcern

Type Parameters:

T - the type of the entity

Parameters:

entity - the entity to save

wc - the WriteConcern to use

Returns:

the keys of the entity

update

<T> UpdateResults update(T entity,
                         UpdateOperations<T> operations)

Updates an entity with the operations; this is an atomic operation

Type Parameters:

T - the type of the entity

Parameters:

entity - the entity to update

operations - the update operations to perform

Returns:

the update results

See Also:

UpdateResults

update

<T> UpdateResults update(Key<T> key,
                         UpdateOperations<T> operations)

Updates an entity with the operations; this is an atomic operation

Type Parameters:

T - the type of the entity

Parameters:

key - the key of entity to update

operations - the update operations to perform

Returns:

the update results

See Also:

UpdateResults

update

<T> UpdateResults update(Query<T> query,
                         UpdateOperations<T> operations)

Updates all entities found with the operations; this is an atomic operation per entity

Type Parameters:

T - the type of the entity

Parameters:

query - the query used to match the documents to update

operations - the update operations to perform

Returns:

the results of the updates

update

<T> UpdateResults update(Query<T> query,
                         UpdateOperations<T> operations,
                         boolean createIfMissing)

Updates all entities found with the operations, if nothing is found insert the update as an entity if "createIfMissing" is true; this is an atomic operation per entity

Type Parameters:

T - the type of the entity

Parameters:

query - the query used to match the documents to update

operations - the update operations to perform

createIfMissing - if true, a document will be created if none can be found that match the query

Returns:

the results of the updates

update

<T> UpdateResults update(Query<T> query,
                         UpdateOperations<T> operations,
                         boolean createIfMissing,
                         WriteConcern wc)

Updates all entities found with the operations, if nothing is found insert the update as an entity if "createIfMissing" is true; this is an atomic operation per entity

Type Parameters:

T - the type of the entity

Parameters:

query - the query used to match the documents to update

operations - the update operations to perform

createIfMissing - if true, a document will be created if none can be found that match the query

wc - the WriteConcern to use

Returns:

the results of the updates

updateFirst

<T> UpdateResults updateFirst(Query<T> query,
                              UpdateOperations<T> operations)

Updates the first entity found with the operations; this is an atomic operation

Type Parameters:

T - the type of the entity

Parameters:

query - the query used to match the document to update

operations - the update operations to perform

Returns:

the results of the update

updateFirst

<T> UpdateResults updateFirst(Query<T> query,
                              UpdateOperations<T> operations,
                              boolean createIfMissing)

Updates the first entity found with the operations, if nothing is found insert the update as an entity if "createIfMissing" is true.

Type Parameters:

T - the type of the entity

Parameters:

query - the query used to match the documents to update

operations - the update operations to perform

createIfMissing - if true, a document will be created if none can be found that match the query

Returns:

the results of the updates

updateFirst

<T> UpdateResults updateFirst(Query<T> query,
                              UpdateOperations<T> operations,
                              boolean createIfMissing,
                              WriteConcern wc)

Updates the first entity found with the operations, if nothing is found insert the update as an entity if "createIfMissing" is true.

Type Parameters:

T - the type of the entity

Parameters:

query - the query used to match the documents to update

operations - the update operations to perform

createIfMissing - if true, a document will be created if none can be found that match the query

wc - the WriteConcern to use

Returns:

the results of the updates

updateFirst

<T> UpdateResults updateFirst(Query<T> query,
                              T entity,
                              boolean createIfMissing)

updates the first entity found using the entity as a template, if nothing is found insert the update as an entity if "createIfMissing" is true.

Type Parameters:

T - the type of the entity

Parameters:

query - the query used to match the documents to update

entity - the entity whose state will be used as an update template for any matching documents

createIfMissing - if true, a document will be created if none can be found that match the query

Returns:

the results of the updates