[DOC-CVS] [doc-en] master: MongoDB\Driver\BulkWriteCommand and related APIs (#4610)
[email protected] (Jeremy Mikola via GitHub)
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: Jeremy Mikola (jmikola) Committer: GitHub (web-flow) Pusher: alcaeus Date: 2025-05-20T09:47:51+02:00 Commit: https://github.com/php/doc-en/commit/187032b3ea20fa28f1c9f29ba38d06820428f849 Raw diff: https://github.com/php/doc-en/commit/187032b3ea20fa28f1c9f29ba38d06820428f849.diff MongoDB\Driver\BulkWriteCommand and related APIs (#4610) * MongoDB\Driver\BulkWriteCommand * MongoDB\Driver\BulkWriteCommandResult * MongoDB\Driver\Exception\BulkWriteCommandException * Manager and Server executeBulkWriteCommand() methods * Clarify that BulkWriteCommandException exposes error details * Fix wrong duplicate property name --------- Co-authored-by: Andreas Braun <[email protected]> Changed paths: A reference/mongodb/mongodb/driver/bulkwritecommand.xml A reference/mongodb/mongodb/driver/bulkwritecommand/construct.xml A reference/mongodb/mongodb/driver/bulkwritecommand/count.xml A reference/mongodb/mongodb/driver/bulkwritecommand/deletemany.xml A reference/mongodb/mongodb/driver/bulkwritecommand/deleteone.xml A reference/mongodb/mongodb/driver/bulkwritecommand/insertone.xml A reference/mongodb/mongodb/driver/bulkwritecommand/replaceone.xml A reference/mongodb/mongodb/driver/bulkwritecommand/updatemany.xml A reference/mongodb/mongodb/driver/bulkwritecommand/updateone.xml A reference/mongodb/mongodb/driver/bulkwritecommandresult.xml A reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeletedcount.xml A reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeleteresults.xml A reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertedcount.xml A reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertresults.xml A reference/mongodb/mongodb/driver/bulkwritecommandresult/getmatchedcount.xml A reference/mongodb/mongodb/driver/bulkwritecommandresult/getmodifiedcount.xml A reference/mongodb/mongodb/driver/bulkwritecommandresult/getupdateresults.xml A reference/mongodb/mongodb/driver/bulkwritecommandresult/getupsertedcount.xml A reference/mongodb/mongodb/driver/bulkwritecommandresult/isacknowledged.xml A reference/mongodb/mongodb/driver/exception/bulkwritecommandexception.xml A reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/geterrorreply.xml A reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getpartialresult.xml A reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteconcernerrors.xml A reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteerrors.xml A reference/mongodb/mongodb/driver/manager/executebulkwritecommand.xml A reference/mongodb/mongodb/driver/server/executebulkwritecommand.xml M language-snippets.ent M reference/mongodb/exceptions.xml M reference/mongodb/mongodb.xml M reference/mongodb/versions.xml Diff: diff --git a/language-snippets.ent b/language-snippets.ent index c464faef565e..16441f8ed6fc 100644 --- a/language-snippets.ent +++ b/language-snippets.ent @@ -3431,6 +3431,16 @@ local: { </listitem> </varlistentry> '> +<!ENTITY mongodb.parameter.bulkwritecommand ' + <varlistentry xmlns="http://docbook.org/ns/docbook"> + <term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWriteCommand</classname>)</term> + <listitem> + <para> + The write(s) to execute. + </para> + </listitem> + </varlistentry> +'> <!ENTITY mongodb.parameter.command ' <varlistentry xmlns="http://docbook.org/ns/docbook"> <term><parameter>command</parameter> (<classname>MongoDB\Driver\Command</classname>)</term> @@ -3645,9 +3655,11 @@ local: { '> <!ENTITY mongodb.returns.cursor '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\Cursor</classname> on success.</para>'> <!ENTITY mongodb.returns.writeresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\WriteResult</classname> on success.</para>'> +<!ENTITY mongodb.returns.bulkwritecommandresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\BulkWriteCommandResult</classname> on success.</para>'> <!ENTITY mongodb.throws.std '&mongodb.throws.argumentparsing;&mongodb.throws.connection;&mongodb.throws.authentication;'> <!ENTITY mongodb.throws.session-readwriteconcern '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"session"</literal> option is used with an associated transaction in combination with a <literal>"readConcern"</literal> or <literal>"writeConcern"</literal> option.</member>'> <!ENTITY mongodb.throws.session-unacknowledged '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"session"</literal> option is used in combination with an unacknowledged write concern.</member>'> +<!ENTITY mongodb.throws.bulkwritecommandexception '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname> on any write failure (e.g. command failure, write or write concern error)</member>'> <!ENTITY mongodb.throws.bulkwriteexception '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\BulkWriteException</classname> on any write failure (e.g. write error, failure to apply a write concern)</member>'> <!ENTITY mongodb.throws.argumentparsing '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> on argument parsing errors.</member>'> <!ENTITY mongodb.throws.authentication '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\AuthenticationException</classname> if authentication is needed and fails.</member>'> diff --git a/reference/mongodb/exceptions.xml b/reference/mongodb/exceptions.xml index a43cee4f64b1..a46847f1f283 100644 --- a/reference/mongodb/exceptions.xml +++ b/reference/mongodb/exceptions.xml @@ -7,6 +7,7 @@ &reference.mongodb.mongodb.driver.exception.authenticationexception; &reference.mongodb.mongodb.driver.exception.bulkwriteexception; + &reference.mongodb.mongodb.driver.exception.bulkwritecommandexception; &reference.mongodb.mongodb.driver.exception.commandexception; &reference.mongodb.mongodb.driver.exception.connectionexception; &reference.mongodb.mongodb.driver.exception.connectiontimeoutexception; @@ -51,6 +52,7 @@ <listitem> <simpara><classname>MongoDB\Driver\Exception\ServerException</classname></simpara> <itemizedlist> + <listitem><simpara><classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname></simpara></listitem> <listitem><simpara><classname>MongoDB\Driver\Exception\CommandException</classname></simpara></listitem> <listitem><simpara><classname>MongoDB\Driver\Exception\ExecutionTimeoutException</classname></simpara></listitem> <listitem> diff --git a/reference/mongodb/mongodb.xml b/reference/mongodb/mongodb.xml index 01a150305681..7aeae83349e0 100644 --- a/reference/mongodb/mongodb.xml +++ b/reference/mongodb/mongodb.xml @@ -10,6 +10,7 @@ &reference.mongodb.mongodb.driver.command; &reference.mongodb.mongodb.driver.query; &reference.mongodb.mongodb.driver.bulkwrite; + &reference.mongodb.mongodb.driver.bulkwritecommand; &reference.mongodb.mongodb.driver.session; &reference.mongodb.mongodb.driver.clientencryption; &reference.mongodb.mongodb.driver.serverapi; @@ -29,4 +30,5 @@ &reference.mongodb.mongodb.driver.writeconcernerror; &reference.mongodb.mongodb.driver.writeerror; &reference.mongodb.mongodb.driver.writeresult; + &reference.mongodb.mongodb.driver.bulkwritecommandresult; </part> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand.xml b/reference/mongodb/mongodb/driver/bulkwritecommand.xml new file mode 100644 index 000000000000..6190950932a7 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand.xml @@ -0,0 +1,202 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<reference xml:id="class.mongodb-driver-bulkwritecommand" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <title>The MongoDB\Driver\BulkWriteCommand class</title> + <titleabbrev>MongoDB\Driver\BulkWriteCommand</titleabbrev> + + <partintro> + +<!-- {{{ MongoDB\Driver\BulkWriteCommand intro --> + <section xml:id="mongodb-driver-bulkwritecommand.intro"> + &reftitle.intro; + <para> + <classname>MongoDB\Driver\BulkWriteCommand</classname> collects one or more + write operations that should be sent to the server using the + <link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link> + command introduced in MongoDB 8.0. After adding any number of insert, + update, and delete operations, the command may be executed via + <methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname>. + </para> + <para> + Unlike <classname>MongoDB\Driver\BulkWrite</classname>, where all write + operations must target the same collection, each write operation within + <classname>MongoDB\Driver\BulkWriteCommand</classname> may target a + different collection. + </para> + <para> + Write operations may either be ordered (default) or unordered. Ordered write + operations are sent to the server, in the order provided, for serial + execution. If a write fails, any remaining operations will be aborted. + Unordered operations are sent to the server in an arbitrary order + where they may be executed in parallel. Any errors that occur are reported + after all operations have been attempted. + </para> + </section> +<!-- }}} --> + + <section xml:id="mongodb-driver-bulkwritecommand.synopsis"> + &reftitle.classsynopsis; + +<!-- {{{ Synopsis --> + <classsynopsis> + <ooclass><classname>MongoDB\Driver\BulkWriteCommand</classname></ooclass> + +<!-- {{{ Class synopsis --> + <classsynopsisinfo> + <modifier>final</modifier> + <ooclass> + <classname>MongoDB\Driver\BulkWriteCommand</classname> + </ooclass> + + <oointerface> + <interfacename>Countable</interfacename> + </oointerface> + </classsynopsisinfo> +<!-- }}} --> + + <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb-driver-bulkwritecommand')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" /> + </classsynopsis> +<!-- }}} --> + + </section> + + <section xml:id="mongodb-driver-bulkwritecommand.examples"> + &reftitle.examples; + + <example> + <title>Mixed write operations</title> + <para> + Mixed write operations (i.e. inserts, updates, and deletes) will be sent + to the server using a single + <link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link> + command. + </para> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; + +// Delete documents from both collections +$bulk->deleteMany('db.coll_one', []); +$bulk->deleteMany('db.coll_two', []); + +// Insert documents into two collections +$bulk->insertOne('db.coll_one', ['_id' => 1]); +$bulk->insertOne('db.coll_two', ['_id' => 2]); +$bulk->insertOne('db.coll_two', ['_id' => 3]); + +// Update a document in "coll_one" +$bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +printf("Inserted %d document(s)\n", $result->getInsertedCount()); +printf("Updated %d document(s)\n", $result->getModifiedCount()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +Inserted 3 document(s) +Updated 1 document(s) +]]> + </screen> + </example> + <example> + <title>Ordered write operations causing an error</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; + +$bulk->deleteMany('db.coll', []); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 2]); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 3]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + $result = $e->getPartialResult(); + + var_dump($e->getWriteErrors()); +} + +printf("Inserted %d document(s)\n", $result->getInsertedCount()); + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +array(1) { + [3]=> + object(MongoDB\Driver\WriteError)#5 (4) { + ["message"]=> + string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }" + ["code"]=> + int(11000) + ["index"]=> + int(3) + ["info"]=> + object(stdClass)#6 (0) { + } + } +} +Inserted 2 document(s) +]]> + </screen> + </example> + </section> + + <section xml:id="mongodb-driver-bulkwritecommand.seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + <member><classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname></member> + <member><classname>MongoDB\Driver\WriteConcern</classname></member> + <member><classname>MongoDB\Driver\WriteConcernError</classname></member> + <member><classname>MongoDB\Driver\WriteError</classname></member> + </simplelist> + </section> + + </partintro> + + &reference.mongodb.mongodb.driver.entities.bulkwritecommand; + +</reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/construct.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/construct.xml new file mode 100644 index 000000000000..d5daf49b4286 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/construct.xml @@ -0,0 +1,184 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommand.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommand::__construct</refname> + <refpurpose>Create a new BulkWriteCommand</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>public</modifier> <methodname>MongoDB\Driver\BulkWriteCommand::__construct</methodname> + <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam> + </methodsynopsis> + <para> + Constructs a new <classname>MongoDB\Driver\BulkWriteCommand</classname>, + which may be used to perform many insert, update, and delete operations on + multiple collections in a single request using the + <link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link> + command introduced in MongoDB 8.0. This differs from + <classname>MongoDB\Driver\BulkWrite</classname>, which is supported by all + server versions but limited to a single collection. + </para> + <para> + After all write operations have been added, this object may be executed with + <methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>options</parameter> (<type>array</type>)</term> + <listitem> + <para> + <table> + <title>options</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Option</entry> + <entry>Type</entry> + <entry>Description</entry> + <entry>Default</entry> + </row> + </thead> + <tbody> + <row> + <entry>bypassDocumentValidation</entry> + <entry><type>bool</type></entry> + <entry> + <para> + If &true;, allows insert and update operations to circumvent + document level validation. + </para> + </entry> + <entry>&false;</entry> + </row> + <row> + <entry>comment</entry> + <entry><type>mixed</type></entry> + <entry> + <para> + An arbitrary comment to help trace the operation through the + database profiler, currentOp output, and logs. + </para> + </entry> + </row> + &mongodb.option.let; + <row> + <entry>ordered</entry> + <entry><type>bool</type></entry> + <entry> + <para> + Whether the operations in this bulk write should be executed in + the order in which they were specified. If &false;, writes will + continue to be executed if an individual write fails. If &true;, + writes will stop executing if an individual write fails. + </para> + </entry> + <entry>&true;</entry> + </row> + <row> + <entry>verboseResults</entry> + <entry><type>bool</type></entry> + <entry> + <para> + Whether detailed results for each successful operation should be + included in the returned + <classname>MongoDB\Driver\BulkWriteCommandResult</classname>. + </para> + </entry> + <entry>&false;</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommand::__construct</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; + +// Delete documents from both collections +$bulk->deleteMany('db.coll_one', []); +$bulk->deleteMany('db.coll_two', []); + +// Insert documents into two collections +$bulk->insertOne('db.coll_one', ['_id' => 1]); +$bulk->insertOne('db.coll_two', ['_id' => 2]); +$bulk->insertOne('db.coll_two', ['_id' => 3]); + +// Update a document in "coll_one" +$bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +printf("Inserted %d document(s)\n", $result->getInsertedCount()); +printf("Updated %d document(s)\n", $result->getModifiedCount()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +Inserted 3 document(s) +Updated 1 document(s) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/count.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/count.xml new file mode 100644 index 000000000000..c5c40e24f761 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/count.xml @@ -0,0 +1,92 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommand.count" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommand::count</refname> + <refpurpose>Count number of write operations in the BulkWriteCommand</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>public</modifier> <type>int</type><methodname>MongoDB\Driver\BulkWriteCommand::count</methodname> + <void /> + </methodsynopsis> + <para> + Returns the number of write operations added to the + <classname>MongoDB\Driver\BulkWriteCommand</classname> object. + </para> + + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns number of write operations added to the + <classname>MongoDB\Driver\BulkWriteCommand</classname> object. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommand::count</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['_id' => 1, 'x' => 1]); +$bulk->insertOne('db.coll', ['_id' => 2, 'x' => 2]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['x' => 1]]); +$bulk->deleteMany('db.coll', ['x' => 1]); + +var_dump(count($bulk)); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +int(4) +]]> + </screen> + </example> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/deletemany.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/deletemany.xml new file mode 100644 index 000000000000..f6c6510eea8a --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/deletemany.xml @@ -0,0 +1,133 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommand.deletemany" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommand::deleteMany</refname> + <refpurpose>Add a deleteMany operation</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>public</modifier> <type>void</type><methodname>MongoDB\Driver\BulkWriteCommand::deleteMany</methodname> + <methodparam><type>string</type><parameter>namespace</parameter></methodparam> + <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>filter</parameter></methodparam> + <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam> + </methodsynopsis> + <para> + Add a deleteMany operation to the + <classname>MongoDB\Driver\BulkWriteCommand</classname>. All documents + matching <parameter>filter</parameter> in the collection identified by + <parameter>namespace</parameter> will be deleted. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + &mongodb.parameter.namespace; + &mongodb.parameter.filter; + <varlistentry> + <term><parameter>options</parameter></term> + <listitem> + <para> + <table> + <title>options</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Option</entry> + <entry>Type</entry> + <entry>Description</entry> + <entry>Default</entry> + </row> + </thead> + <tbody> + &mongodb.option.collation; + <row> + <entry>hint</entry> + <entry><type class="union"><type>string</type><type>array</type><type>object</type></type></entry> + <entry> + <para> + Index specification. Specify either the index name as a string or + the index key pattern. If specified, then the query system will only + consider plans using the hinted index. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.void; + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommand::deleteMany</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->deleteMany('db.coll', ['x' => ['$gt' => 1]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + </programlisting> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommand::deleteOne</methodname></member> + <member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/deleteone.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/deleteone.xml new file mode 100644 index 000000000000..15f875218ffa --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/deleteone.xml @@ -0,0 +1,133 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommand.deleteone" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommand::deleteOne</refname> + <refpurpose>Add a deleteOne operation</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>public</modifier> <type>void</type><methodname>MongoDB\Driver\BulkWriteCommand::deleteOne</methodname> + <methodparam><type>string</type><parameter>namespace</parameter></methodparam> + <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>filter</parameter></methodparam> + <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam> + </methodsynopsis> + <para> + Add a deleteOne operation to the + <classname>MongoDB\Driver\BulkWriteCommand</classname>. The first document + matching <parameter>filter</parameter> in the collection identified by + <parameter>namespace</parameter> will be deleted. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + &mongodb.parameter.namespace; + &mongodb.parameter.filter; + <varlistentry> + <term><parameter>options</parameter></term> + <listitem> + <para> + <table> + <title>options</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Option</entry> + <entry>Type</entry> + <entry>Description</entry> + <entry>Default</entry> + </row> + </thead> + <tbody> + &mongodb.option.collation; + <row> + <entry>hint</entry> + <entry><type class="union"><type>string</type><type>array</type><type>object</type></type></entry> + <entry> + <para> + Index specification. Specify either the index name as a string or + the index key pattern. If specified, then the query system will only + consider plans using the hinted index. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.void; + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommand::deleteOne</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->deleteOne('db.coll', ['x' => 1]); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + </programlisting> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommand::deleteMany</methodname></member> + <member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/insertone.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/insertone.xml new file mode 100644 index 000000000000..453bfbdb4b68 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/insertone.xml @@ -0,0 +1,131 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommand.insertone" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommand::insertOne</refname> + <refpurpose>Add an insertOne operation</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>public</modifier> <type>mixed</type><methodname>MongoDB\Driver\BulkWriteCommand::insertOne</methodname> + <methodparam><type>string</type><parameter>namespace</parameter></methodparam> + <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>document</parameter></methodparam> + </methodsynopsis> + <para> + Add an insertOne operation to the + <classname>MongoDB\Driver\BulkWriteCommand</classname>. The document will + be inserted into the collection identified by + <parameter>namespace</parameter>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + &mongodb.parameter.namespace; + <varlistentry> + <term><parameter>document</parameter> (<type class="union"><type>array</type><type>object</type></type>)</term> + <listitem> + <para> + A document to insert. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the <literal>_id</literal> of the inserted document. If the + <parameter>document</parameter> did not have an <literal>_id</literal>, the + <classname>MongoDB\BSON\ObjectId</classname> generated for the insert will + be returned. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommand::insertOne</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; + +$doc1 = ['x' => 1]; +$doc2 = ['_id' => 'custom-id', 'x' => 2]; +$doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3]; + +$id1 = $bulk->insertOne('db.coll', $doc1); +$id2 = $bulk->insertOne('db.coll', $doc2); +$id3 = $bulk->insertOne('db.coll', $doc3); + +var_dump($id1, $id2, $id3); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +object(MongoDB\BSON\ObjectId)#3 (1) { + ["oid"]=> + string(24) "67f58058d1a0aa2fd80d55d0" +} +string(9) "custom-id" +object(MongoDB\BSON\ObjectId)#4 (1) { + ["oid"]=> + string(24) "0123456789abcdef01234567" +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + <member><classname>MongoDB\BSON\ObjectId</classname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/replaceone.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/replaceone.xml new file mode 100644 index 000000000000..139e6decb6e6 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/replaceone.xml @@ -0,0 +1,165 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommand.replaceone" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommand::replaceOne</refname> + <refpurpose>Add a replaceOne operation</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>public</modifier> <type>void</type><methodname>MongoDB\Driver\BulkWriteCommand::replaceOne</methodname> + <methodparam><type>string</type><parameter>namespace</parameter></methodparam> + <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>filter</parameter></methodparam> + <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>replacement</parameter></methodparam> + <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam> + </methodsynopsis> + <para> + Add a replaceOne operation to the + <classname>MongoDB\Driver\BulkWriteCommand</classname>. The first document + matching <parameter>filter</parameter> in the collection identified by + <parameter>namespace</parameter> will be replaced. + </para> + + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + &mongodb.parameter.namespace; + &mongodb.parameter.filter; + <varlistentry> + <term><parameter>replacement</parameter> (<type class="union"><type>array</type><type>object</type></type>)</term> + <listitem> + <para> + A replacement document. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>options</parameter></term> + <listitem> + <para> + <table> + <title>options</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Option</entry> + <entry>Type</entry> + <entry>Description</entry> + <entry>Default</entry> + </row> + </thead> + <tbody> + &mongodb.option.collation; + <row> + <entry>hint</entry> + <entry><type class="union"><type>string</type><type>array</type><type>object</type></type></entry> + <entry> + <para> + Index specification. Specify either the index name as a string or + the index key pattern. If specified, then the query system will only + consider plans using the hinted index. + </para> + </entry> + </row> + <row> + <entry>sort</entry> + <entry><type class="union"><type>array</type><type>object</type></type></entry> + <entry> + <para> + Specify which document the operation replaces if the query matches + multiple documents. The first document matched by the sort order + will be replaced. + </para> + </entry> + </row> + <row> + <entry>upsert</entry> + <entry><type>bool</type></entry> + <entry> + If <parameter>filter</parameter> does not match an existing document, + insert a <emphasis>single</emphasis> document. The document will be + created from <parameter>replacement</parameter>. + </entry> + <entry>&false;</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.void; + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommand::replaceOne</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->replaceOne('db.coll', ['x' => 1], ['x' => 1, 'y' = 2]); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + </programlisting> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommand::updateOne</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommand::updateMany</methodname></member> + <member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/updatemany.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/updatemany.xml new file mode 100644 index 000000000000..b4f87fa13c75 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/updatemany.xml @@ -0,0 +1,169 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommand.updatemany" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommand::updateMany</refname> + <refpurpose>Add an updateMany operation</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>public</modifier> <type>void</type><methodname>MongoDB\Driver\BulkWriteCommand::updateMany</methodname> + <methodparam><type>string</type><parameter>namespace</parameter></methodparam> + <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>filter</parameter></methodparam> + <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>update</parameter></methodparam> + <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam> + </methodsynopsis> + <para> + Add an updateMany operation to the + <classname>MongoDB\Driver\BulkWriteCommand</classname>. All documents + matching <parameter>filter</parameter> in the collection identified by + <parameter>namespace</parameter> will be updated. + </para> + + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + &mongodb.parameter.namespace; + &mongodb.parameter.filter; + <varlistentry> + <term><parameter>update</parameter> (<type class="union"><type>array</type><type>object</type></type>)</term> + <listitem> + <para> + A document containing either update operators (e.g. + <literal>$set</literal>) or an + <link xlink:href="&url.mongodb.docs.command;update/#update-with-an-aggregation-pipeline">aggregation pipeline</link>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>options</parameter></term> + <listitem> + <para> + <table> + <title>options</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Option</entry> + <entry>Type</entry> + <entry>Description</entry> + <entry>Default</entry> + </row> + </thead> + <tbody> + <row> + <entry>arrayFilters</entry> + <entry><type>array</type></entry> + <entry> + <para> + An array of filter documents that determines which array elements to + modify for an update operation on an array field. See + <link xlink:href="&url.mongodb.docs.command;update/#update-command-arrayfilters">Specify arrayFilters for Array Update Operations</link> + in the MongoDB manual for more information. + </para> + </entry> + </row> + &mongodb.option.collation; + <row> + <entry>hint</entry> + <entry><type class="union"><type>string</type><type>array</type><type>object</type></type></entry> + <entry> + <para> + Index specification. Specify either the index name as a string or + the index key pattern. If specified, then the query system will only + consider plans using the hinted index. + </para> + </entry> + </row> + <row> + <entry>upsert</entry> + <entry><type>bool</type></entry> + <entry> + If <parameter>filter</parameter> does not match an existing document, + insert a <emphasis>single</emphasis> document. The document will be + created by applying operators in <parameter>update</parameter> to any + field values in <parameter>filter</parameter>. + </entry> + <entry>&false;</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.void; + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommand::updateMany</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->updateMany('db.coll', ['x' => ['$gt' => 1]], ['$set' => ['y' => 2]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + </programlisting> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommand::replaceOne</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommand::updateMany</methodname></member> + <member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/updateone.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/updateone.xml new file mode 100644 index 000000000000..efa7b9afacdc --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/updateone.xml @@ -0,0 +1,180 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommand.updateone" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommand::updateOne</refname> + <refpurpose>Add an updateOne operation</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>public</modifier> <type>void</type><methodname>MongoDB\Driver\BulkWriteCommand::updateOne</methodname> + <methodparam><type>string</type><parameter>namespace</parameter></methodparam> + <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>filter</parameter></methodparam> + <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>update</parameter></methodparam> + <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam> + </methodsynopsis> + <para> + Add an updateOne operation to the + <classname>MongoDB\Driver\BulkWriteCommand</classname>. The first document + matching <parameter>filter</parameter> in the collection identified by + <parameter>namespace</parameter> will be updated. + </para> + + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + &mongodb.parameter.namespace; + &mongodb.parameter.filter; + <varlistentry> + <term><parameter>update</parameter> (<type class="union"><type>array</type><type>object</type></type>)</term> + <listitem> + <para> + A document containing either update operators (e.g. + <literal>$set</literal>) or an + <link xlink:href="&url.mongodb.docs.command;update/#update-with-an-aggregation-pipeline">aggregation pipeline</link>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>options</parameter></term> + <listitem> + <para> + <table> + <title>options</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Option</entry> + <entry>Type</entry> + <entry>Description</entry> + <entry>Default</entry> + </row> + </thead> + <tbody> + <row> + <entry>arrayFilters</entry> + <entry><type>array</type></entry> + <entry> + <para> + An array of filter documents that determines which array elements to + modify for an update operation on an array field. See + <link xlink:href="&url.mongodb.docs.command;update/#update-command-arrayfilters">Specify arrayFilters for Array Update Operations</link> + in the MongoDB manual for more information. + </para> + </entry> + </row> + &mongodb.option.collation; + <row> + <entry>hint</entry> + <entry><type class="union"><type>string</type><type>array</type><type>object</type></type></entry> + <entry> + <para> + Index specification. Specify either the index name as a string or + the index key pattern. If specified, then the query system will only + consider plans using the hinted index. + </para> + </entry> + </row> + <row> + <entry>sort</entry> + <entry><type class="union"><type>array</type><type>object</type></type></entry> + <entry> + <para> + Specify which document the operation updates if the query matches + multiple documents. The first document matched by the sort order + will be updated. + </para> + </entry> + </row> + <row> + <entry>upsert</entry> + <entry><type>bool</type></entry> + <entry> + If <parameter>filter</parameter> does not match an existing document, + insert a <emphasis>single</emphasis> document. The document will be + created by applying operators in <parameter>update</parameter> to any + field values in <parameter>filter</parameter>. + </entry> + <entry>&false;</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.void; + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommand::updateOne</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 2]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + </programlisting> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommand::replaceOne</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommand::updateMany</methodname></member> + <member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult.xml new file mode 100644 index 000000000000..6f4998e8d47b --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult.xml @@ -0,0 +1,71 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<reference xml:id="class.mongodb-driver-bulkwritecommandresult" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <title>The MongoDB\Driver\BulkWriteCommandResult class</title> + <titleabbrev>MongoDB\Driver\BulkWriteCommandResult</titleabbrev> + + <partintro> + +<!-- {{{ MongoDB\Driver\BulkWriteCommandResult intro --> + <section xml:id="mongodb-driver-bulkwritecommandresult.intro"> + &reftitle.intro; + <para> + The <classname>MongoDB\Driver\BulkWriteCommandResult</classname> class + encapsulates information about an executed + <classname>MongoDB\Driver\BulkWriteCommand</classname> and is returned by + <methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname>. + </para> + </section> +<!-- }}} --> + + <section xml:id="mongodb-driver-bulkwritecommandresult.synopsis"> + &reftitle.classsynopsis; + +<!-- {{{ Synopsis --> + <classsynopsis> + <ooclass><classname>MongoDB\Driver\BulkWriteCommandResult</classname></ooclass> + +<!-- {{{ Class synopsis --> + <classsynopsisinfo> + <modifier>final</modifier> + <ooclass> + <classname>MongoDB\Driver\BulkWriteCommandResult</classname> + </ooclass> + </classsynopsisinfo> +<!-- }}} --> + + <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb-driver-bulkwritecommandresult')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" /> + </classsynopsis> +<!-- }}} --> + + </section> + + </partintro> + + &reference.mongodb.mongodb.driver.entities.bulkwritecommandresult; + +</reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeletedcount.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeletedcount.xml new file mode 100644 index 000000000000..0c8a17ea1e1e --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeletedcount.xml @@ -0,0 +1,102 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandresult.getdeletedcount" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommandResult::getDeletedCount</refname> + <refpurpose>Returns the number of documents deleted</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type>int</type><methodname>MongoDB\Driver\BulkWriteCommandResult::getDeletedCount</methodname> + <void /> + </methodsynopsis> + <para> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the total number of documents deleted by all operations. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommandResult::getDeletedCount</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getDeletedCount()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +int(3) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getDeleteResults</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</methodname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeleteresults.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeleteresults.xml new file mode 100644 index 000000000000..2667f2b56aef --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeleteresults.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandresult.getdeleteresults" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommandResult::getDeleteResults</refname> + <refpurpose>Returns verbose results for successful deletes</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type class="union"><type>MongoDB\BSON\Document</type><type>null</type></type><methodname>MongoDB\Driver\BulkWriteCommandResult::getDeleteResults</methodname> + <void /> + </methodsynopsis> + <para> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a document containing the result of each successful delete + operation, or &null; if verbose results were not requested. The document + keys will correspond to the index of the write operation from + <classname>MongoDB\Driver\BulkWriteCommand</classname>. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommandResult::getDeleteResults</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]); +$bulk->insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getDeleteResults()->toPHP()); + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +object(stdClass)#7 (1) { + ["4"]=> + object(stdClass)#6 (1) { + ["deletedCount"]=> + object(MongoDB\BSON\Int64)#5 (1) { + ["integer"]=> + string(1) "3" + } + } +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getDeletedCount</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</methodname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertedcount.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertedcount.xml new file mode 100644 index 000000000000..0a858440597d --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertedcount.xml @@ -0,0 +1,103 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandresult.getinsertedcount" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommandResult::getInsertedCount</refname> + <refpurpose>Returns the number of documents inserted</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type>int</type><methodname>MongoDB\Driver\BulkWriteCommandResult::getInsertedCount</methodname> + <void /> + </methodsynopsis> + <para> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the total number of documents inserted (excluding upserts) by all + operations. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommandResult::getInsertedCount</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getInsertedCount()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +int(1) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getInsertResults</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</methodname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertresults.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertresults.xml new file mode 100644 index 000000000000..63feaa022866 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertresults.xml @@ -0,0 +1,128 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandresult.getinsertresults" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommandResult::getInsertResults</refname> + <refpurpose>Returns verbose results for successful inserts</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type class="union"><type>MongoDB\BSON\Document</type><type>null</type></type><methodname>MongoDB\Driver\BulkWriteCommandResult::getInsertResults</methodname> + <void /> + </methodsynopsis> + <para> + Since <literal>_id</literal> fields for inserted documents are generated by + the extension, the value of <literal>insertedId</literal> in each result + will match the return value of + <methodname>MongoDB\Driver\BulkWriteCommand::insertOne</methodname> for + the corresponding insert operation. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a document containing the result of each successful insert + operation, or &null; if verbose results were not requested. The document + keys will correspond to the index of the write operation from + <classname>MongoDB\Driver\BulkWriteCommand</classname>. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommandResult::getInsertResults</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]); + +$generatedId = $bulk->insertOne('db.coll', ['x' => 1]); + +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($generatedId); + +var_dump($result->getInsertResults()->toPHP()); + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +object(MongoDB\BSON\ObjectId)#3 (1) { + ["oid"]=> + string(24) "67f7ee69783dcce702097b41" +} +object(stdClass)#8 (1) { + ["0"]=> + object(stdClass)#7 (1) { + ["insertedId"]=> + object(MongoDB\BSON\ObjectId)#6 (1) { + ["oid"]=> + string(24) "67f7ee69783dcce702097b41" + } + } +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getInsertedCount</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommand::insertOne</methodname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmatchedcount.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmatchedcount.xml new file mode 100644 index 000000000000..036a1a6fe39a --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmatchedcount.xml @@ -0,0 +1,107 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandresult.getmatchedcount" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommandResult::getMatchedCount</refname> + <refpurpose>Returns the number of documents selected for update</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type>int</type><methodname>MongoDB\Driver\BulkWriteCommandResult::getMatchedCount</methodname> + <void /> + </methodsynopsis> + <para> + If the update operation results in no change to the document (e.g. setting + the value of a field to its current value), the matched count may be greater + than the value returned by + <methodname>MongoDB\Driver\BulkWriteCommandResult::getModifiedCount</methodname>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the total number of documents selected for update by all operations. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommandResult::getMatchedCount</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getMatchedCount()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +int(1) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getModifiedCount</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getUpdateResults</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</methodname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmodifiedcount.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmodifiedcount.xml new file mode 100644 index 000000000000..eb19dc13a1a2 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmodifiedcount.xml @@ -0,0 +1,107 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandresult.getmodifiedcount" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommandResult::getModifiedCount</refname> + <refpurpose>Returns the number of existing documents updated</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type>int</type><methodname>MongoDB\Driver\BulkWriteCommandResult::getModifiedCount</methodname> + <void /> + </methodsynopsis> + <para> + If the update operation results in no change to the document (e.g. setting + the value of a field to its current value), the modified count may be less + than the value returned by + <methodname>MongoDB\Driver\BulkWriteCommandResult::getMatchedCount</methodname>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the total number of existing documents updated by all operations. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommandResult::getModifiedCount</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getModifiedCount()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +int(1) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getMatchedCount</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getUpdateResults</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</methodname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupdateresults.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupdateresults.xml new file mode 100644 index 000000000000..9f4d2de1261b --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupdateresults.xml @@ -0,0 +1,157 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandresult.getupdateresults" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommandResult::getUpdateResults</refname> + <refpurpose>Returns verbose results for successful updates</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type class="union"><type>MongoDB\BSON\Document</type><type>null</type></type><methodname>MongoDB\Driver\BulkWriteCommandResult::getUpdateResults</methodname> + <void /> + </methodsynopsis> + <para> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a document containing the result of each successful update + operation, or &null; if verbose results were not requested. The document + keys will correspond to the index of the write operation from + <classname>MongoDB\Driver\BulkWriteCommand</classname>. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommandResult::getUpdateResults</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]); +$bulk->insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getUpdateResults()->toPHP()); + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +object(stdClass)#16 (3) { + ["1"]=> + object(stdClass)#7 (2) { + ["matchedCount"]=> + object(MongoDB\BSON\Int64)#5 (1) { + ["integer"]=> + string(1) "1" + } + ["modifiedCount"]=> + object(MongoDB\BSON\Int64)#6 (1) { + ["integer"]=> + string(1) "1" + } + } + ["2"]=> + object(stdClass)#11 (3) { + ["matchedCount"]=> + object(MongoDB\BSON\Int64)#8 (1) { + ["integer"]=> + string(1) "1" + } + ["modifiedCount"]=> + object(MongoDB\BSON\Int64)#9 (1) { + ["integer"]=> + string(1) "0" + } + ["upsertedId"]=> + object(MongoDB\BSON\ObjectId)#10 (1) { + ["oid"]=> + string(24) "67f7eb9b1f198bbcb880d575" + } + } + ["3"]=> + object(stdClass)#15 (3) { + ["matchedCount"]=> + object(MongoDB\BSON\Int64)#12 (1) { + ["integer"]=> + string(1) "1" + } + ["modifiedCount"]=> + object(MongoDB\BSON\Int64)#13 (1) { + ["integer"]=> + string(1) "0" + } + ["upsertedId"]=> + object(MongoDB\BSON\ObjectId)#14 (1) { + ["oid"]=> + string(24) "67f7eb9b1f198bbcb880d576" + } + } +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getMatchedCount</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getModifiedCount</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</methodname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupsertedcount.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupsertedcount.xml new file mode 100644 index 000000000000..9cdf351b39de --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupsertedcount.xml @@ -0,0 +1,102 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandresult.getupsertedcount" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount</refname> + <refpurpose>Returns the number of documents upserted</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type>int</type><methodname>MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount</methodname> + <void /> + </methodsynopsis> + <para> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the total number of documents upserted by all operations. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getUpsertedCount()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +int(2) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::getUpdateResults</methodname></member> + <member><methodname>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</methodname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/isacknowledged.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/isacknowledged.xml new file mode 100644 index 000000000000..2983f0c457c8 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/isacknowledged.xml @@ -0,0 +1,126 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandresult.isacknowledged" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</refname> + <refpurpose>Returns whether the write was acknowledged</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type>bool</type><methodname>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</methodname> + <void /> + </methodsynopsis> + <para> + If the write is acknowledged, other fields will be available on the + <classname>MongoDB\Driver\BulkWriteCommandResult</classname> object. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns &true; if the write was acknowledged, and &false; otherwise. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + &mongodb.throws.argumentparsing; + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</function> with acknowledged write concern</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['x' => 1]); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->isAcknowledged()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +bool(true) +]]> + </screen> + </example> + <example> + <title><function>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</function> with unacknowledged write concern</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]); +$bulk->insertOne('db.coll', ['x' => 1]); + +$writeConcern = new MongoDB\Driver\WriteConcern(0); + +$result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]); + +var_dump($result->isAcknowledged()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +bool(false) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><classname>MongoDB\Driver\WriteConcern</classname></member> + <member><link xlink:href="&url.mongodb.docs.writeconcern;">Write Concern reference</link></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception.xml b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception.xml new file mode 100644 index 000000000000..545da4f63955 --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception.xml @@ -0,0 +1,165 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<reference xml:id="class.mongodb-driver-exception-bulkwritecommandexception" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <title>The MongoDB\Driver\Exception\BulkWriteCommandException class</title> + <titleabbrev>MongoDB\Driver\Exception\BulkWriteCommandException</titleabbrev> + + <partintro> + +<!-- {{{ MongoDB\Driver\Exception\BulkWriteCommandException intro --> + <section xml:id="mongodb-driver-exception-bulkwritecommandexception.intro"> + &reftitle.intro; + <para> + Exception thrown due to failed execution of a + <classname>MongoDB\Driver\BulkWriteCommand</classname>. The methods of this + class provide more details of the error that occurred, including the error + reply and partial results from the bulk write. + </para> + </section> +<!-- }}} --> + + <section xml:id="mongodb-driver-exception-bulkwritecommandexception.synopsis"> + &reftitle.classsynopsis; + +<!-- {{{ Synopsis --> + <classsynopsis> + <ooclass><classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname></ooclass> + +<!-- {{{ Class synopsis --> + <classsynopsisinfo> + <ooclass> + <classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname> + </ooclass> + + <ooclass> + <modifier>extends</modifier> + <classname>MongoDB\Driver\Exception\ServerException</classname> + </ooclass> + + <oointerface> + <interfacename>MongoDB\Driver\Exception\Exception</interfacename> + </oointerface> + </classsynopsisinfo> +<!-- }}} --> + <classsynopsisinfo role="comment">&Properties;</classsynopsisinfo> + <fieldsynopsis> + <modifier>private</modifier> + <type class="union"><type>MongoDB\BSON\Document</type><type>null</type></type> + <varname linkend="mongodb-driver-exception-bulkwritecommandexception.props.errorreply">errorReply</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>private</modifier> + <type class="union"><type>MongoDB\Driver\BulkWriteCommandResult</type><type>null</type></type> + <varname linkend="mongodb-driver-exception-bulkwritecommandexception.props.partialresult">partialResult</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>private</modifier> + <type>array</type> + <varname linkend="mongodb-driver-exception-bulkwritecommandexception.props.writeconcernerrors">writeConcernErrors</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>private</modifier> + <type>array</type> + <varname linkend="mongodb-driver-exception-bulkwritecommandexception.props.writeerrors">writeErrors</varname> + </fieldsynopsis> + + <classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo> + <!-- <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mongodb-driver-exception-serverexception.synopsis')/descendant::db:fieldsynopsis)" /> --> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mongodb-driver-exception-runtimeexception.synopsis')/descendant::db:fieldsynopsis)" /> + <!-- <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('runtimeexception.synopsis')/descendant::db:fieldsynopsis)" /> --> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('exception.synopsis')/descendant::db:fieldsynopsis)" /> + + <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb-driver-exception-bulkwritecommandexception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" /> + + <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo> + <!-- <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb-driver-exception-serverexception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" /> --> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb-driver-exception-runtimeexception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" /> + <!-- <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.runtimeexception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" /> --> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" /> + </classsynopsis> +<!-- }}} --> + + </section> + +<!-- {{{ MongoDB\Driver\Exception\BulkWriteCommandException properties --> + <section xml:id="mongodb-driver-exception-bulkwritecommandexception.props"> + &reftitle.properties; + <variablelist> + <varlistentry xml:id="mongodb-driver-exception-bulkwritecommandexception.props.errorreply"> + <term><varname>errorReply</varname></term> + <listitem> + <para> + Any top-level error that occurred when attempting to communicate with + the server or execute the bulk write. This value may be &null; if the + exception was thrown due to errors occurring on individual writes. + </para> + </listitem> + </varlistentry> + <varlistentry xml:id="mongodb-driver-exception-bulkwritecommandexception.props.partialresult"> + <term><varname>partialResult</varname></term> + <listitem> + <para> + A <classname>MongoDB\Driver\BulkWriteCommandResult</classname> reporting + the result of any successful operations that were performed before the + error was encountered. This value may not &null; if it cannot be + determined that at least one write was successfully performed (and + acknowledged). + </para> + </listitem> + </varlistentry> + <varlistentry xml:id="mongodb-driver-exception-bulkwritecommandexception.props.writeconcernerrors"> + <term><varname>writeConcernErrors</varname></term> + <listitem> + <para> + An array of any <classname>MongoDB\Driver\WriteConcernError</classname>s + that occurred while executing the bulk write. This list may have + multiple items if more than one server command was required to execute + the bulk write. + </para> + </listitem> + </varlistentry> + <varlistentry xml:id="mongodb-driver-exception-bulkwritecommandexception.props.writeerrors"> + <term><varname>writeErrors</varname></term> + <listitem> + <para> + An array of any <classname>MongoDB\Driver\WriteError</classname>s + that occurred during the execution of individual write operations. Array + keys will correspond to the index of the write operation from + <classname>MongoDB\Driver\BulkWriteCommand</classname>. This map will + contain at most one entry if the bulk write was ordered. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> +<!-- }}} --> + + </partintro> + + &reference.mongodb.mongodb.driver.exception.entities.bulkwritecommandexception; + +</reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/geterrorreply.xml b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/geterrorreply.xml new file mode 100644 index 000000000000..bf44de90eb4f --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/geterrorreply.xml @@ -0,0 +1,144 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandexception.geterrorreply" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply</refname> + <refpurpose>Returns any top-level command error</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type class="union"><type>MongoDB\BSON\Document</type><type>null</type></type><methodname>MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply</methodname> + <void /> + </methodsynopsis> + <para> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns any top-level error that occurred when attempting to communicate + with the server or execute the bulk write. This value may be &null; if the + exception was thrown due to errors occurring on individual writes. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +// This example uses configureFailPoint to simulate a top-level command error +$manager->executeCommand('admin', new MongoDB\Driver\Command([ + 'configureFailPoint' => 'failCommand', + 'mode' => ['times' => 1], + 'data' => [ + 'failCommands' => ['bulkWrite'], + 'errorCode' => 8, /* UnknownError */ + ], +])); + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['x' => 1]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + var_dump($e->getErrorReply()?->toPHP()); +} + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +object(stdClass)#12 (6) { + ["ok"]=> + float(0) + ["errmsg"]=> + string(43) "Failing command via 'failCommand' failpoint" + ["code"]=> + int(8) + ["codeName"]=> + string(12) "UnknownError" + ["$clusterTime"]=> + object(stdClass)#10 (2) { + ["clusterTime"]=> + object(MongoDB\BSON\Timestamp)#6 (2) { + ["increment"]=> + string(1) "7" + ["timestamp"]=> + string(10) "1744319389" + } + ["signature"]=> + object(stdClass)#9 (2) { + ["hash"]=> + object(MongoDB\BSON\Binary)#7 (2) { + ["data"]=> + string(20) "" + ["type"]=> + int(0) + } + ["keyId"]=> + object(MongoDB\BSON\Int64)#8 (1) { + ["integer"]=> + string(1) "0" + } + } + } + ["operationTime"]=> + object(MongoDB\BSON\Timestamp)#11 (2) { + ["increment"]=> + string(1) "7" + ["timestamp"]=> + string(10) "1744319389" + } +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><function>MongoDB\Driver\Manager::executeBulkWriteCommand</function></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getpartialresult.xml b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getpartialresult.xml new file mode 100644 index 000000000000..4301076defe1 --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getpartialresult.xml @@ -0,0 +1,134 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandexception.getpartialresult" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult</refname> + <refpurpose>Returns the result of any successful write operations</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type class="union"><type>MongoDB\Driver\BulkWriteCommandResult</type><type>null</type></type><methodname>MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult</methodname> + <void /> + </methodsynopsis> + <para> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a <classname>MongoDB\Driver\BulkWriteCommandResult</classname> + reporting the result of any successful operations that were performed before + the error was encountered. The return value will be &null; if it cannot be + determined that at least one write was successfully performed (and + acknowledged). + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>Partial result if at least one write is successful</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->deleteMany('db.coll', []); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 1]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + $result = $e->getPartialResult(); +} + +var_dump($result?->getInsertedCount()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +int(1) +]]> + </screen> + </example> + <example> + <title>No partial result if no writes are successful</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->deleteMany('db.coll', []); +$bulk->insertOne('db.coll', ['_id' => 1]); +$manager->executeBulkWriteCommand($bulk); + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['_id' => 1]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + $result = $e->getPartialResult(); +} + +var_dump($result?->getInsertedCount()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +NULL +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + <member><function>MongoDB\Driver\Manager::executeBulkWriteCommand</function></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteconcernerrors.xml b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteconcernerrors.xml new file mode 100644 index 000000000000..f38abe10c551 --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteconcernerrors.xml @@ -0,0 +1,118 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandexception.getwriteconcernerrors" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors</refname> + <refpurpose>Returns any write concern errors</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type>array</type><methodname>MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors</methodname> + <void /> + </methodsynopsis> + <para> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + An array of any <classname>MongoDB\Driver\WriteConcernError</classname>s + that occurred while executing the bulk write. This list may have multiple + items if more than one server command was required to execute the bulk + write. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['x' => 1]); + +$writeConcern = new MongoDB\Driver\WriteConcern(50); + +try { + $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + var_dump($e->getWriteConcernErrors()); +} + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +array(1) { + [0]=> + object(MongoDB\Driver\WriteConcernError)#6 (3) { + ["message"]=> + string(29) "Not enough data-bearing nodes" + ["code"]=> + int(100) + ["info"]=> + object(stdClass)#8 (1) { + ["writeConcern"]=> + object(stdClass)#7 (3) { + ["w"]=> + int(50) + ["wtimeout"]=> + int(0) + ["provenance"]=> + string(14) "clientSupplied" + } + } + } +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><function>MongoDB\Driver\Manager::executeBulkWriteCommand</function></member> + <member><classname>MongoDB\Driver\WriteConcern</classname></member> + <member><classname>MongoDB\Driver\WriteConcernError</classname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteerrors.xml b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteerrors.xml new file mode 100644 index 000000000000..959423862f52 --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteerrors.xml @@ -0,0 +1,124 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-bulkwritecommandexception.getwriteerrors" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors</refname> + <refpurpose>Returns any write errors</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type>array</type><methodname>MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors</methodname> + <void /> + </methodsynopsis> + <para> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + An array of any <classname>MongoDB\Driver\WriteError</classname>s that + occurred during the execution of individual write operations. Array keys + will correspond to the index of the write operation from + <classname>MongoDB\Driver\BulkWriteCommand</classname>. This map will + contain at most one entry if the bulk write was ordered. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]); +$bulk->deleteMany('db.coll', []); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 1]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + var_dump($e->getWriteErrors()); +} + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +array(2) { + [2]=> + object(MongoDB\Driver\WriteError)#5 (4) { + ["message"]=> + string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }" + ["code"]=> + int(11000) + ["index"]=> + int(2) + ["info"]=> + object(stdClass)#6 (0) { + } + } + [3]=> + object(MongoDB\Driver\WriteError)#7 (4) { + ["message"]=> + string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }" + ["code"]=> + int(11000) + ["index"]=> + int(3) + ["info"]=> + object(stdClass)#8 (0) { + } + } +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><function>MongoDB\Driver\Manager::executeBulkWriteCommand</function></member> + <member><classname>MongoDB\Driver\WriteError</classname></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/manager/executebulkwritecommand.xml b/reference/mongodb/mongodb/driver/manager/executebulkwritecommand.xml new file mode 100644 index 000000000000..f4343515a9fc --- /dev/null +++ b/reference/mongodb/mongodb/driver/manager/executebulkwritecommand.xml @@ -0,0 +1,211 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-manager.executebulkwritecommand" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\Manager::executeBulkWriteCommand</refname> + <refpurpose>Execute write operations using the bulkWrite command</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\BulkWriteCommandResult</type><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname> + <methodparam><type>MongoDB\Driver\BulkWriteCommand</type><parameter>bulk</parameter></methodparam> + <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam> + </methodsynopsis> + <para> + Executes one or more write operations on the primary server using the + <link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link> + command introduced in MongoDB 8.0. + </para> + <para> + A <classname>MongoDB\Driver\BulkWriteCommand</classname> can be constructed + with one or more write operations of varying types (e.g. inserts, updates, + and deletes). Each write operation may target a different collection. + </para> + <para> + The default value for the <literal>"writeConcern"</literal> option will be + inferred from an active transaction (indicated by the + <literal>"session"</literal> option), followed by the + <link linkend="mongodb-driver-manager.construct-uri">connection URI</link>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + &mongodb.parameter.bulkwritecommand; + <varlistentry> + <term><parameter>options</parameter></term> + <listitem> + <para> + <table> + <title>options</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Option</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + &mongodb.option.session; + &mongodb.option.writeConcern; + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + &mongodb.returns.bulkwritecommandresult; + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + <member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>bulk</parameter> does not contain any write operations.</member> + <member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>bulk</parameter> has already been executed. <classname>MongoDB\Driver\BulkWriteCommand</classname> objects may not be executed multiple times.</member> + &mongodb.throws.session-unacknowledged; + &mongodb.throws.std; + &mongodb.throws.bulkwritecommandexception; + <member>Throws <classname>MongoDB\Driver\Exception\RuntimeException</classname> on other errors.</member> + </simplelist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>Mixed write operations</title> + <para> + Mixed write operations (i.e. inserts, updates, and deletes) will be sent + to the server using a single + <link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link> + command. + </para> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; + +// Delete documents from both collections +$bulk->deleteMany('db.coll_one', []); +$bulk->deleteMany('db.coll_two', []); + +// Insert documents into two collections +$bulk->insertOne('db.coll_one', ['_id' => 1]); +$bulk->insertOne('db.coll_two', ['_id' => 2]); +$bulk->insertOne('db.coll_two', ['_id' => 3]); + +// Update a document in "coll_one" +$bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +printf("Inserted %d document(s)\n", $result->getInsertedCount()); +printf("Updated %d document(s)\n", $result->getModifiedCount()); + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +Inserted 3 document(s) +Updated 1 document(s) +]]> + </screen> + </example> + <example> + <title>Ordered write operations causing an error</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$manager = new MongoDB\Driver\Manager; + +$bulk = new MongoDB\Driver\BulkWriteCommand; + +$bulk->deleteMany('db.coll', []); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 2]); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 3]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + $result = $e->getPartialResult(); + + var_dump($e->getWriteErrors()); +} + +printf("Inserted %d document(s)\n", $result->getInsertedCount()); + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +array(1) { + [3]=> + object(MongoDB\Driver\WriteError)#5 (4) { + ["message"]=> + string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }" + ["code"]=> + int(11000) + ["index"]=> + int(3) + ["info"]=> + object(stdClass)#6 (0) { + } + } +} +Inserted 2 document(s) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><classname>MongoDB\Driver\BulkWriteCommand</classname></member> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + <member><classname>MongoDB\Driver\WriteConcern</classname></member> + <member><function>MongoDB\Driver\Server::executeBulkWriteCommand</function></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/mongodb/driver/server/executebulkwritecommand.xml b/reference/mongodb/mongodb/driver/server/executebulkwritecommand.xml new file mode 100644 index 000000000000..b99bad1916da --- /dev/null +++ b/reference/mongodb/mongodb/driver/server/executebulkwritecommand.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="mongodb-driver-server.executebulkwritecommand" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>MongoDB\Driver\Server::executeBulkWriteCommand</refname> + <refpurpose>Execute write operations on this server using the bulkWrite command</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\BulkWriteCommandResult</type><methodname>MongoDB\Driver\Server::executeBulkWriteCommand</methodname> + <methodparam><type>MongoDB\Driver\BulkWriteCommand</type><parameter>bulk</parameter></methodparam> + <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam> + </methodsynopsis> + <para> + Executes one or more write operations on this server using the + <link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link> + command introduced in MongoDB 8.0. + </para> + <para> + A <classname>MongoDB\Driver\BulkWriteCommand</classname> can be constructed + with one or more write operations of varying types (e.g. inserts, updates, + and deletes). Each write operation may target a different collection. + </para> + <para> + The default value for the <literal>"writeConcern"</literal> option will be + inferred from an active transaction (indicated by the + <literal>"session"</literal> option), followed by the + <link linkend="mongodb-driver-manager.construct-uri">connection URI</link>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + &mongodb.parameter.bulkwritecommand; + <varlistentry> + <term><parameter>options</parameter></term> + <listitem> + <para> + <table> + <title>options</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Option</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + &mongodb.option.session; + &mongodb.option.writeConcern; + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + &mongodb.returns.bulkwritecommandresult; + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simplelist> + <member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>bulk</parameter> does not contain any write operations.</member> + <member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>bulk</parameter> has already been executed. <classname>MongoDB\Driver\BulkWriteCommand</classname> objects may not be executed multiple times.</member> + &mongodb.throws.session-unacknowledged; + &mongodb.throws.std; + &mongodb.throws.bulkwritecommandexception; + <member>Throws <classname>MongoDB\Driver\Exception\RuntimeException</classname> on other errors.</member> + </simplelist> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><classname>MongoDB\Driver\BulkWriteCommand</classname></member> + <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> + <member><classname>MongoDB\Driver\WriteConcern</classname></member> + <member><function>MongoDB\Driver\Manager::executeBulkWriteCommand</function></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/mongodb/versions.xml b/reference/mongodb/versions.xml index 6ea70d670935..9525120cb915 100644 --- a/reference/mongodb/versions.xml +++ b/reference/mongodb/versions.xml @@ -65,6 +65,7 @@ <function name='mongodb\driver\manager::addsubscriber' from='mongodb >=1.10.0'/> <function name='mongodb\driver\manager::createclientencryption' from='mongodb >=1.7.0'/> <function name='mongodb\driver\manager::executebulkwrite' from='mongodb >=1.0.0'/> + <function name='mongodb\driver\manager::executebulkwritecommand' from='mongodb >=2.1.0'/> <function name='mongodb\driver\manager::executecommand' from='mongodb >=1.0.0'/> <function name='mongodb\driver\manager::executequery' from='mongodb >=1.0.0'/> <function name='mongodb\driver\manager::executereadcommand' from='mongodb >=1.4.0'/> @@ -100,6 +101,7 @@ <function name='mongodb\driver\server' from='mongodb >=1.0.0'/> <function name='mongodb\driver\server::__construct' from='mongodb >=1.0.0'/> <function name='mongodb\driver\server::executebulkwrite' from='mongodb >=1.0.0'/> + <function name='mongodb\driver\server::executebulkwritecommand' from='mongodb >=2.1.0'/> <function name='mongodb\driver\server::executecommand' from='mongodb >=1.0.0'/> <function name='mongodb\driver\server::executequery' from='mongodb >=1.0.0'/> <function name='mongodb\driver\server::executereadcommand' from='mongodb >=1.4.0'/> @@ -160,6 +162,27 @@ <function name='mongodb\driver\bulkwrite::delete' from='mongodb >=1.0.0'/> <function name='mongodb\driver\bulkwrite::count' from='mongodb >=1.0.0'/> + <function name='mongodb\driver\bulkwritecommand' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommand::__construct' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommand::count' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommand::deletemany' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommand::deleteone' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommand::insertone' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommand::replaceone' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommand::updatemany' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommand::updateone' from='mongodb >=2.1.0'/> + + <function name='mongodb\driver\bulkwritecommandresult' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommandresult::getdeletedcount' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommandresult::getinsertedcount' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommandresult::getmatchedcount' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommandresult::getmodifiedcount' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommandresult::getupsertedcount' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommandresult::getdeleteresults' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommandresult::getinsertresults' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommandresult::getupdateresults' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\bulkwritecommandresult::isacknowledged' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\writeconcern' from='mongodb >=1.0.0'/> <function name='mongodb\driver\writeconcern::__construct' from='mongodb >=1.0.0'/> <function name='mongodb\driver\writeconcern::bsonserialize' from='mongodb >=1.2.0'/> @@ -211,6 +234,12 @@ <function name='mongodb\driver\exception\writeexception' from='mongodb >= 1.0.0' deprecated='mongodb 1.20.0'/> <function name='mongodb\driver\exception\writeexception::getwriteresult' from='mongodb >= 1.0.0' deprecated='mongodb 1.20.0'/> + <function name='mongodb\driver\exception\bulkwritecommandexception' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\exception\bulkwritecommandexception::geterrorreply' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\exception\bulkwritecommandexception::getpartialresult' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\exception\bulkwritecommandexception::getwriteerrors' from='mongodb >=2.1.0'/> + <function name='mongodb\driver\exception\bulkwritecommandexception::getwriteconcernerrors' from='mongodb >=2.1.0'/> + <!-- Monitoring interfaces --> <function name='mongodb\driver\monitoring\subscriber' from='mongodb >=1.3.0'/> <function name='mongodb\driver\monitoring\commandsubscriber' from='mongodb >=1.3.0'/>