diff --git a/source/includes/write/delete.php b/source/includes/write/delete.php new file mode 100644 index 00000000..50a5f910 --- /dev/null +++ b/source/includes/write/delete.php @@ -0,0 +1,34 @@ +sample_restaurants->restaurants; +// end-db-coll + +// Deletes a document that has a "name" value of "Ready Penny Inn" +// start-delete-one +$collection->deleteOne(['name' => 'Ready Penny Inn']); +// end-delete-one + +// Deletes documents that have a "borough" value of "Brooklyn" +// start-delete-many +$collection->deleteMany(['borough' => 'Brooklyn']); +// end-delete-many + +// Deletes matching documents and attaches a comment to the operation +// start-delete-options +$collection->deleteMany( + ['name' => new MongoDB\BSON\Regex('Mongo')], + ['comment' => 'Deleting Mongo restaurants'], +); +// end-delete-options + +// Deletes and prints the number of documents that have a "cuisine" value of "Greek" +// start-delete-count +$result = $collection->deleteMany(['cuisine' => 'Greek']); +echo 'Deleted documents: ' , $result->getDeletedCount() , PHP_EOL; +// end-delete-count + diff --git a/source/write.txt b/source/write.txt index 01df4cb8..6d95c80a 100644 --- a/source/write.txt +++ b/source/write.txt @@ -8,6 +8,7 @@ Write Data to MongoDB :titlesonly: :maxdepth: 1 + /write/delete /write/replace /write/insert /write/update diff --git a/source/write/delete.txt b/source/write/delete.txt new file mode 100644 index 00000000..c45f16dd --- /dev/null +++ b/source/write/delete.txt @@ -0,0 +1,199 @@ +.. _php-write-delete: + +================ +Delete Documents +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: remove, drop, code example + +Overview +-------- + +In this guide, you can learn how to use the {+php-library+} to remove +documents from a MongoDB collection by performing **delete operations**. + +A delete operation removes one or more documents from a MongoDB collection. +You can perform a delete operation by using the ``MongoDB\Collection::deleteOne()`` +or ``MongoDB\Collection::deleteMany()`` methods. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To access this collection +from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster +and assign the following value to your ``$collection`` variable: + +.. literalinclude:: /includes/write/delete.php + :language: php + :dedent: + :start-after: start-db-coll + :end-before: end-db-coll + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +Delete Operations +----------------- + +You can perform delete operations by using the following methods: + +- ``MongoDB\Collection::deleteOne()``, which deletes *the first document* + that matches the search criteria +- ``MongoDB\Collection::deleteMany()``, which deletes *all documents* that + match the search criteria + +Each delete method requires a **query filter** document, which specifies the +search criteria to determine which documents to select for removal. +For more information about query filters, see the +:manual:`Query Filter Documents section ` in +the {+mdb-server+} manual. + +Delete One Document +~~~~~~~~~~~~~~~~~~~ + +The following example uses the ``deleteOne()`` method to remove a document in +the ``restaurants`` collection that has a ``name`` value of ``'Ready Penny Inn'``: + +.. literalinclude:: /includes/write/delete.php + :start-after: start-delete-one + :end-before: end-delete-one + :language: php + :dedent: + +Delete Multiple Documents +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example uses the ``deleteMany()`` method to remove all documents +in the ``restaurants`` collection that have a ``borough`` value of ``'Brooklyn'``: + +.. literalinclude:: /includes/write/delete.php + :start-after: start-delete-many + :end-before: end-delete-many + :language: php + :dedent: + +Modify the Delete Operation +--------------------------- + +You can modify the behavior of the ``MongoDB\Collection::deleteOne()`` and +``MongoDB\Collection::deleteMany()`` methods by passing an array that +specifies option values as a parameter. The following table describes the +options you can set in the array: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Option + - Description + + * - ``collation`` + - | Specifies the kind of language collation to use when comparing + strings. For more information, see :manual:`Collation ` + in the {+mdb-server+} manual. + + * - ``writeConcern`` + - | Sets the write concern for the operation. This option defaults to + the collection's write concern. + For more information, see :manual:`Write Concern ` + in the {+mdb-server+} manual. + + * - ``hint`` + - | Gets or sets the index to scan for documents. + For more information, see the :manual:`hint statement ` + in the {+mdb-server+} manual. + + * - ``let`` + - | Specifies a document with a list of values to improve operation readability. + Values must be constant or closed expressions that don't reference document + fields. For more information, see the :manual:`let statement + ` in the + {+mdb-server+} manual. + + * - ``session`` + - | Specifies the client session to associate with the operation. For more + information, see :manual:`Session ` in the + {+mdb-server+} manual. + + * - ``comment`` + - | Attaches a comment to the operation. For more information, see the :manual:`delete command + fields ` guide in the + {+mdb-server+} manual. + +Example +~~~~~~~ + +The following example calls the ``deleteMany()`` method to delete all documents in +the ``restaurants`` collection that have a ``name`` value containing the string ``'Mongo'``. +It also sets the ``comment`` option in an array parameter to add a comment to the +operation: + +.. literalinclude:: /includes/write/delete.php + :start-after: start-delete-options + :end-before: end-delete-options + :language: php + :dedent: + +.. note:: + + If you replace the ``deleteMany()`` method with ``deleteOne()`` in + the preceding example, the library deletes only the first document that has + a ``name`` value containing ``'Mongo'``. + +Return Value +------------ + +The ``MongoDB\Collection::deleteOne()`` and ``MongoDB\Collection::deleteMany()`` +methods return a ``MongoDB\DeleteResult`` object. This class contains the +following member functions: + +- ``isAcknowledged()``, which returns a boolean indicating whether the operation + was acknowledged. +- ``getDeletedCount()``, which returns the number of documents deleted. If the write + operation was not acknowledged, this method throws an error. + +If the query filter does not match any documents, the driver doesn't delete any +documents and ``getDeletedCount()`` returns ``0``. + +Example +~~~~~~~ + +The following example calls the ``deleteMany()`` method to delete documents +that have a ``cuisine`` value of ``'Greek'``. It then calls the ``getDeletedCount()`` +member function to print the number of deleted documents: + +.. io-code-block:: + :copyable: + + .. input:: /includes/write/delete.php + :start-after: start-delete-count + :end-before: end-delete-count + :language: php + :dedent: + + .. output:: + :visible: false + + Deleted documents: 111 + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoDB\\Collection::deleteOne() <{+api+}/method/MongoDBCollection-deleteOne/>`__ +- `MongoDB\\Collection::deleteMany() <{+api+}/method/MongoDBCollection-deleteMany/>`__ +- `MongoDB\\DeleteResult <{+api+}/class/MongoDBDeleteResult/>`__