php-doc-ru/reference/mongo/mongodb/command.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: af5f2f87b3b0bb9ee0f83ccb787a4e7db1eb6bd4 Maintainer: sergey Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="mongodb.command" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoDB::command</refname>
  <refpurpose>Выполняет команду базы данных</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>array</type><methodname>MongoDB::command</methodname>
   <methodparam><type>array</type><parameter>command</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter role="reference">hash</parameter></methodparam>
  </methodsynopsis>
  <para>
   Почти все, что не является операцией CRUD, может быть выполнено с помощью команды 
   базы данных. Нужно узнать версию базы данных? Для этого есть команда. 
   Нужно сделать агрегацию? Для этого есть команда. Нужно включить 
   запись событий? Вы поняли идею.
  </para>
  <para>
   Этот метод идентичен:
   <programlisting role="php">
<![CDATA[
<?php

public function command($data) {
    return $this->selectCollection('$cmd')->findOne($data);
}

?>
]]>
   </programlisting>
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>command</parameter>
     </term>
     <listitem>
      <para>
       Запрос на отправку.
      </para>
     </listitem>
    </varlistentry>   
    <varlistentry>
     <term>
      <parameter>options</parameter>
     </term>
     <listitem>
      <para>
       Массив опций для создания индекса. В настоящее время доступны следующие 
       варианты:
       <itemizedlist>
        &mongo.writes.parameters.sockettimeoutms;
       </itemizedlist>
      </para>
      <para>
       Следующие параметры устарели и больше не должны использоваться:
       <itemizedlist>
        &mongo.writes.parameters.timeout;
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <parameter>hash</parameter>
     </term>
     <listitem>
      <para>
       Установите хеш подключения сервера, который выполнил команду. Когда 
       результат команды подходит для создания 
       <classname>MongoCommandCursor</classname>, хеш предназначен для 
       передачи в <function>MongoCommandCursor::createFromDocument</function>.
      </para>
      <para>
       Хеш также будет соответствовать соединению, возвращенному из 
       <function>MongoClient::getConnections</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </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 mongo 1.5.0</entry>
       <entry>
        <para>
         Переименована опция <literal>"timeout"</literal> в
         <literal>"socketTimeoutMS"</literal>. Выдает
         <constant>E_DEPRECATED</constant> при использовании 
         <literal>"timeout"</literal>.
        </para>
        <para>
         Добавлен параметр ссылки на <literal>hash</literal>.
        </para>
       </entry>
      </row>
      <row>
       <entry>PECL mongo 1.2.0</entry>
       <entry>
        Добавлен параметр <literal>options</literal> с одним вариантом: 
        <literal>"timeout"</literal>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;  
  <para>
   Возвращает ответ базы данных. Каждый ответ базы данных всегда является максимум одним 
   документом, что означает, что результат команды базы данных никогда не может 
   превышать 16 Мб. Структура результирующего документа зависит от команды, но 
   большинство результатов будет иметь поле <literal>ok</literal>, указывающее успех 
   или неудачу, и <literal>results</literal>, содержащие массив каждого из 
   результирующих документов.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>Пример использования <function>MongoDB::command</function> "distinct"</title>
   <para>
    Поиск всех различных значений для ключа.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$people = $db->people;

$people->insert(array("name" => "Joe", "age" => 4));
$people->insert(array("name" => "Sally", "age" => 22));
$people->insert(array("name" => "Dave", "age" => 22));
$people->insert(array("name" => "Molly", "age" => 87));

$ages = $db->command(array("distinct" => "people", "key" => "age"));

foreach ($ages['values'] as $age) {
    echo "$age\n";
}

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
4
22
87
   </screen>
  </example>

  <example>
   <title>Пример использования <function>MongoDB::command</function> "distinct"</title>
   <para>
    Поиск всех различных значений для ключа, где значение больше 
    или равно 18.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$people = $db->people;

$people->insert(array("name" => "Joe", "age" => 4));
$people->insert(array("name" => "Sally", "age" => 22));
$people->insert(array("name" => "Dave", "age" => 22));
$people->insert(array("name" => "Molly", "age" => 87));

$ages = $db->command(
    array(
        "distinct" => "people",
        "key" => "age", 
        "query" => array("age" => array('$gte' => 18))
    )
);  

foreach ($ages['values'] as $age) {
    echo "$age\n";
}

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
22
87
   </screen>
  </example>

  <example>
   <title>Пример использования <function>MongoDB::command</function> MapReduce</title>
   <para>
    Получение всех пользователей, у которых есть хотя бы одно событие "sale", и сколько раз 
    каждый из этих пользователей совершил распродажу.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

// пример документа о событии
$events->insert(array("user_id" => $id, 
    "type" => $type, 
    "time" => new MongoDate(), 
    "desc" => $description));

// конструктор карты и reduce функции
$map = new MongoCode("function() { emit(this.user_id,1); }");
$reduce = new MongoCode("function(k, vals) { ".
    "var sum = 0;".
    "for (var i in vals) {".
        "sum += vals[i];". 
    "}".
    "return sum; }");

$sales = $db->command(array(
    "mapreduce" => "events", 
    "map" => $map,
    "reduce" => $reduce,
    "query" => array("type" => "sale"),
    "out" => array("merge" => "eventCounts")));

$users = $db->selectCollection($sales['result'])->find();

foreach ($users as $user) {
    echo "{$user['_id']} принял участие в {$user['value']} распродажах.\n";
}

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
User 47cc67093475061e3d9536d2 принял участие в 3 распродажах.
User 49902cde5162504500b45c2c принял участие в 14 распродажах.
User 4af467e4fd543cce7b0ea8e2 принял участие в 1 распродажах.
   </screen>
   <note>
    <title>Использование <classname>MongoCode</classname></title>
    <para>
     В этом примере используется <classname>MongoCode</classname>, который также может 
     принимать аргумент scope. Однако в настоящее время MongoDB не поддерживает использование 
     scope в MapReduce. Если вы хотите использовать переменные на стороне клиента в 
     функциях MapReduce, вы можете добавить их в глобальную область, используя 
     необязательное поле scope с командой базы данных. Смотрите 
     <link xlink:href="&url.mongodb.dochub.mapreduce;">документацию MapReduce</link> 
     для получения дополнительной информации.
    </para>
   </note>
   <note>
    <title>Аргумент <literal>out</literal></title>
    <para>
     До 1.8.0 аргумент <literal>out</literal> был необязательным. Если вы его 
     не используете, результаты MapReduce будут записаны во временную коллекцию, 
     которая будет удалена при закрытии вашего соединения. В 1.8.0+ требуется аргумент 
     <literal>out</literal>. Смотрите 
     <link xlink:href="&url.mongodb.dochub.mapreduce;">документацию MapReduce</link> 
     для получения дополнительной информации.
    </para>
   </note>
  </example>

  <example>
   <title>Пример использования <function>MongoDB::command</function> "geoNear"</title>
   <para>
    В этом примере показано, как использовать команду geoNear.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$d = $m->demo;
$c = $d->poiConcat;

$r = $d->command(array(
    'geoNear' => "poiConcat",      // Поиск в коллекции poiConcat
    'near' => array(-0.08, 51.48), // Поиск около 51.48° с.ш., 0.08° в.д.
    'spherical' => true,           // Включение сферический поиск
    'num' => 5,                    // Максимум 5 возвращенных документов
));
print_r($r);
?>
]]>
   </programlisting>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><methodname>MongoCollection::aggregate</methodname></member>
    <member><methodname>MongoCollection::findAndModify</methodname></member>
    <member><methodname>MongoCollection::group</methodname></member>
   </simplelist>
  </para>
  <para>
   Основная документация MongoDB по
   <link xlink:href="&url.mongodb.docs.command;">командам базы данных</link>.
  </para>
 </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
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
-->