98 lines
3.4 KiB
ReStructuredText
98 lines
3.4 KiB
ReStructuredText
.. _storage_strategies:
|
|
|
|
Storage Strategies
|
|
==================
|
|
|
|
Doctrine MongoDB ODM implements several different strategies for persisting changes
|
|
to mapped fields. These strategies apply to the following mapping types:
|
|
|
|
- :ref:`int`
|
|
- :ref:`float`
|
|
- :ref:`embed_many`
|
|
- :ref:`reference_many`
|
|
|
|
For collections, Doctrine tracks changes via the PersistentCollection class. The
|
|
strategies described on this page are implemented by the CollectionPersister
|
|
class. The ``increment`` strategy cannot be used for collections.
|
|
|
|
increment
|
|
---------
|
|
|
|
The ``increment`` strategy does not apply to collections but can be used for
|
|
``int`` and ``float`` fields. When using the ``increment`` strategy, the field
|
|
value will be updated using the `$inc`_ operator.
|
|
|
|
addToSet
|
|
--------
|
|
|
|
The ``addToSet`` strategy uses MongoDB's `$addToSet`_ operator to insert
|
|
elements into the array. This strategy is useful for ensuring that duplicate
|
|
values will not be inserted into the collection. Like the `pushAll`_ strategy,
|
|
elements are inserted in a separate query after removing deleted elements.
|
|
|
|
set
|
|
---
|
|
|
|
The ``set`` strategy uses MongoDB's `$set`_ operator to update the entire
|
|
collection with a single update query.
|
|
|
|
.. note::
|
|
|
|
Doctrine's Collection interface is modeled after PHP's associative arrays,
|
|
so they cannot always be represented as a BSON array. If the collection's
|
|
keys are not sequential integers starting with zero, the ``set`` strategy
|
|
will store the collection as a BSON object instead of an array. Use the
|
|
`setArray`_ strategy if you want to ensure that the collection is always
|
|
stored as a BSON array.
|
|
|
|
setArray
|
|
--------
|
|
|
|
The ``setArray`` strategy uses MongoDB's `$set`_ operator, just like the ``set``
|
|
strategy, but will first numerically reindex the collection to ensure that it is
|
|
stored as a BSON array.
|
|
|
|
pushAll
|
|
-------
|
|
|
|
The ``pushAll`` strategy uses MongoDB's `$pushAll`_ operator to insert
|
|
elements into the array. MongoDB does not allow elements to be added and removed
|
|
from an array in a single operation, so this strategy relies on multiple update
|
|
queries to remove and insert elements (in that order).
|
|
|
|
.. _atomic_set:
|
|
|
|
atomicSet
|
|
---------
|
|
|
|
The ``atomicSet`` strategy uses MongoDB's `$set`_ operator to update the entire
|
|
collection with a single update query. Unlike with ``set`` strategy there will
|
|
be only one query for updating both parent document and collection itself. This
|
|
strategy can be especially useful when dealing with high concurrency and
|
|
:ref:`versioned documents <annotations_reference_version>`.
|
|
|
|
.. note::
|
|
|
|
The ``atomicSet`` and ``atomicSetArray`` strategies may only be used for
|
|
collections mapped directly in a top-level document.
|
|
|
|
.. _atomic_set_array:
|
|
|
|
atomicSetArray
|
|
--------------
|
|
|
|
The ``atomicSetArray`` strategy works exactly like ``atomicSet`` strategy, but
|
|
will first numerically reindex the collection to ensure that it is stored as a
|
|
BSON array.
|
|
|
|
.. note::
|
|
|
|
The ``atomicSet`` and ``atomicSetArray`` strategies may only be used for
|
|
collections mapped directly in a top-level document.
|
|
|
|
.. _`$addToSet`: https://docs.mongodb.com/manual/reference/operator/update/addToSet/
|
|
.. _`$inc`: https://docs.mongodb.com/manual/reference/operator/update/inc/
|
|
.. _`$pushAll`: https://docs.mongodb.com/manual/reference/operator/update/pushAll/
|
|
.. _`$set`: https://docs.mongodb.com/manual/reference/operator/update/set/
|
|
.. _`$unset`: https://docs.mongodb.com/manual/reference/operator/update/unset/
|