MONGODB.COMMAND(3)							 1							MONGODB.COMMAND(3)

MongoDB::command - Execute a database command

SYNOPSIS

       public array MongoDB::command (array  $command, [array  $options = array()], [string  &$hash])

DESCRIPTION

	Almost	everything  that is not a CRUD operation can be done with a database command. Need to know the database version? There's a command
       for that. Need to do aggregation? There's a command for that. Need to turn up logging? You get the idea.

	This method is identical to:

       <?php

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

       ?>

PARAMETERS

	      o $command
		- The query to send.

	      o $options
		- An array of options for the index creation. Currently available options include:

		     o "socketTimeoutMS"This option specifies the time limit, in milliseconds, for socket communication. If the  server  does  not
		       respond	within	the  timeout period, a MongoCursorTimeoutException will be thrown and there will be no way to determine if
		       the server actually handled the write or not. A value of -1 may be specified to block indefinitely. The default	value  for
		       MongoClient is 30000 (30 seconds).

	       The following options are deprecated and should no longer be used:

		     o "timeout"Deprecated alias for "socketTimeoutMS".

	      o $hash
		- Set to the connection hash of the server that executed the command. When the command result is suitable for creating a MongoCom-
		mandCursor, the hash is intended to be passed to MongoCommandCursor.createFromDocument(3).  The hash will  also  correspond  to  a
		connection returned from MongoClient.getConnections(3).

CHANGELOG

       +--------+---------------------------------------------------+
       |Version |						    |
       |	|						    |
       |	|		     Description		    |
       |	|						    |
       +--------+---------------------------------------------------+
       | 1.5.0	|						    |
       |	|						    |
       |	|  Renamed  the  "timeout"  option  to "socketTime- |
       |	| outMS".  Emits  E_DEPRECATED	when  "timeout"  is |
       |	| used.  Added hash by-reference parameter.	    |
       |	|						    |
       | 1.2.0	|						    |
       |	|						    |
       |	|  Added  options  parameter  with a single option: |
       |	| "timeout".					    |
       |	|						    |
       +--------+---------------------------------------------------+
RETURN VALUES

	Returns database response. Every database response is always maximum one document, which means that the result of a database  command  can
       never  exceed  16MB. The resulting document's structure depends on the command, but most results will have the ok field to indicate success
       or failure and results containing an array of each of the resulting documents.

EXAMPLES

       Example #1

	      MongoDB.command(3) "distinct" example

	       Finding all of the distinct values for a key.

	      <?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
";
	      }

	      ?>

	      The above example will output something similar to:

	      22 87

       Example #2

	      MongoDB.command(3) "distinct" example

	       Finding all of the distinct values for a key, where the value is larger than or equal to 18.

	      <?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
";
	      }

	      ?>

	      The above example will output something similar to:

	      87

       Example #3

	      MongoDB.command(3) MapReduce example

	       Get all users with at least on "sale" event, and how many times each of these users has had a sale.

	      <?php

	      // sample event document
	      $events->insert(array("user_id" => $id,
		  "type" => $type,
		  "time" => new MongoDate(),
		  "desc" => $description));

	      // construct map and reduce functions
	      $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']} had {$user['value']} sale(s).
";
	      }

	      ?>

	      The above example will output something similar to:

	      User 49902cde5162504500b45c2c had 14 sale(s).  User 4af467e4fd543cce7b0ea8e2 had 1 sale(s).

	      Note

		     Using MongoCode

		      This example uses MongoCode, which can also take a scope argument. However, at the moment, MongoDB does  not  support  using
		     scopes  in  MapReduce.  If  you  would  like to use client-side variables in the MapReduce functions, you can add them to the
		     global scope by using the optional scope field with the database command. See the MapReduce documentation for  more  informa-
		     tion.

	      Note

		     The out argument

		      Before  1.8.0,  the out argument was optional. If you did not use it, MapReduce results would be written to a temporary col-
		     lection, which would be deleted when your connection was closed. In 1.8.0+, the out argument is required. See  the  MapReduce
		     documentation for more information.

       Example #4

	      MongoDB.command(3) "geoNear" example

	       This example shows how to use the geoNear command.

	      <?php
	      $m = new MongoClient();
	      $d = $m->demo;
	      $c = $d->poiConcat;

	      $r = $d->command(array(
		  'geoNear' => "poiConcat",	 // Search in the poiConcat collection
		  'near' => array(-0.08, 51.48), // Search near 51.48oN, 0.08oE
		  'spherical' => true,		 // Enable spherical search
		  'num' => 5,			 // Maximum 5 returned documents
	      ));
	      print_r($r);
	      ?>

SEE ALSO

       MongoCollection::aggregate, MongoCollection::findAndModify, MongoCollection::group.

	MongoDB  core  docs  on  database commands and on individual commands: findAndModify, getLastError, and repairDatabase (dozens more exist,
       there are merely a few examples).

PHP Documentation Group 													MONGODB.COMMAND(3)