mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-25 13:28:56 +00:00
af5f2f87b3
Patch contributed by Benjamin Morel <benjamin.morel@gmail.com>. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@350988 c90b9560-bf6c-de11-be94-00142212c4b1
292 lines
8.3 KiB
XML
292 lines
8.3 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
|
|
<refentry xml:id="mongodb-driver-manager.executecommand" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<refnamediv>
|
|
<refname>MongoDB\Driver\Manager::executeCommand</refname>
|
|
<refpurpose>Execute a database command</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\Cursor</type><methodname>MongoDB\Driver\Manager::executeCommand</methodname>
|
|
<methodparam><type>string</type><parameter>db</parameter></methodparam>
|
|
<methodparam><type>MongoDB\Driver\Command</type><parameter>command</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Selects a server according to the <literal>"readPreference"</literal> option
|
|
and executes the command on that server. By default, the read preference from
|
|
the <link linkend="mongodb-driver-manager.construct-uri">MongoDB Connection
|
|
URI</link> will be used.
|
|
</para>
|
|
<para>
|
|
This method applies no special logic to the command. Although this method
|
|
accepts <literal>"readConcern"</literal> and
|
|
<literal>"writeConcern"</literal> options, which will be incorporated into
|
|
the command document, those options will not default to corresponding values
|
|
from the <link linkend="mongodb-driver-manager.construct-uri">MongoDB
|
|
Connection URI</link> nor will the MongoDB server version be taken into
|
|
account. Users are therefore encouraged to use specific read and/or write
|
|
command methods if possible.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<variablelist>
|
|
&mongodb.parameter.db;
|
|
&mongodb.parameter.command;
|
|
<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.readConcern;
|
|
&mongodb.option.readPreference;
|
|
&mongodb.option.session;
|
|
&mongodb.option.writeConcern;
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
&mongodb.option.transactionReadWriteConcern;
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
&mongodb.returns.cursor;
|
|
</refsect1>
|
|
|
|
<refsect1 role="errors">
|
|
&reftitle.errors;
|
|
<simplelist>
|
|
&mongodb.throws.session-readwriteconcern;
|
|
&mongodb.throws.session-unacknowledged;
|
|
&mongodb.throws.std;
|
|
<member>Throws <classname>MongoDB\Driver\Exception\RuntimeException</classname> on other errors (e.g. invalid command, issuing a write command to a secondary).</member>
|
|
</simplelist>
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>PECL mongodb 1.4.4</entry>
|
|
<entry>
|
|
<classname>MongoDB\Driver\Exception\InvalidArgumentException</classname>
|
|
will be thrown if the <literal>"session"</literal> option is used in
|
|
combination with an unacknowledged write concern.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>PECL mongodb 1.4.0</entry>
|
|
<entry>
|
|
The third parameter is now an <parameter>options</parameter> array.
|
|
For backwards compatibility, this paramater will still accept a
|
|
<classname>MongoDB\Driver\ReadPreference</classname> object.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<example>
|
|
<title><function>MongoDB\Driver\Manager::executeCommand</function> with a command returning a single result document</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
|
|
$command = new MongoDB\Driver\Command(['ping' => 1]);
|
|
|
|
try {
|
|
$cursor = $manager->executeCommand('admin', $command);
|
|
} catch(MongoDB\Driver\Exception $e) {
|
|
echo $e->getMessage(), "\n";
|
|
exit;
|
|
}
|
|
|
|
/* The ping command returns a single result document, so we need to access the
|
|
* first result in the cursor. */
|
|
$response = $cursor->toArray()[0];
|
|
|
|
var_dump($response);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
array(1) {
|
|
["ok"]=>
|
|
float(1)
|
|
}
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<example>
|
|
<title><function>MongoDB\Driver\Manager::executeCommand</function> with a command returning a cursor</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
|
|
|
|
$bulk = new MongoDB\Driver\BulkWrite;
|
|
$bulk->insert(['x' => 1, 'y' => 'foo']);
|
|
$bulk->insert(['x' => 2, 'y' => 'bar']);
|
|
$bulk->insert(['x' => 3, 'y' => 'bar']);
|
|
$manager->executeBulkWrite('db.collection', $bulk);
|
|
|
|
$command = new MongoDB\Driver\Command([
|
|
'aggregate' => 'collection',
|
|
'pipeline' => [
|
|
['$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
|
|
],
|
|
'cursor' => new stdClass,
|
|
]);
|
|
$cursor = $manager->executeCommand('db', $command);
|
|
|
|
/* The aggregate command can optionally return its results in a cursor instead
|
|
* of a single result document. In this case, we can iterate on the cursor
|
|
* directly to access those results. */
|
|
foreach ($cursor as $document) {
|
|
var_dump($document);
|
|
}
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
object(stdClass)#6 (2) {
|
|
["_id"]=>
|
|
string(3) "bar"
|
|
["sum"]=>
|
|
int(10)
|
|
}
|
|
object(stdClass)#7 (2) {
|
|
["_id"]=>
|
|
string(3) "foo"
|
|
["sum"]=>
|
|
int(2)
|
|
}
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Limiting execution time for a command</title>
|
|
<para>
|
|
The execution time of a command may be limited by specifying a value for
|
|
<literal>"maxTimeMS"</literal> in the
|
|
<classname>MongoDB\Driver\Command</classname> document. Note that this time
|
|
limit is enforced on the server side and does not take network latency into
|
|
account. See
|
|
<link xlink:href="&url.mongodb.docs.maxtimems;">Terminate Running Operations</link>
|
|
in the MongoDB manual for more information.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
|
|
|
|
$command = new MongoDB\Driver\Command([
|
|
'count' => 'collection',
|
|
'query' => ['x' => ['$gt' => 1]],
|
|
'maxTimeMS' => 1000,
|
|
]);
|
|
|
|
$cursor = $manager->executeCommand('db', $command);
|
|
|
|
var_dump($cursor->toArray()[0]);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
If the command fails to complete after one second of execution time on the
|
|
server, a
|
|
<classname>MongoDB\Driver\Exception\ExecutionTimeoutException</classname>
|
|
will be thrown.
|
|
</para>
|
|
</example>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
<note>
|
|
<simpara>
|
|
If a secondary <parameter>readPreference</parameter> is used, it is the
|
|
caller's responsibility to ensure that the
|
|
<parameter>command</parameter> can be executed on a secondary. No validation
|
|
is done by the driver.
|
|
</simpara>
|
|
</note>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<simplelist>
|
|
<member><classname>MongoDB\Driver\Command</classname></member>
|
|
<member><classname>MongoDB\Driver\Cursor</classname></member>
|
|
<member><function>MongoDB\Driver\Manager::executeReadCommand</function></member>
|
|
<member><function>MongoDB\Driver\Manager::executeReadWriteCommand</function></member>
|
|
<member><function>MongoDB\Driver\Manager::executeWriteCommand</function></member>
|
|
<member><function>MongoDB\Driver\Server::executeCommand</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
|
|
-->
|