php-doc-en/reference/mongo/queries.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<section xml:id="mongo.queries" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Querying</title>

 <section>
  <title>Querying by _id</title>
  <para>
   Every object inserted is automatically assigned a unique _id field, which is
   often a useful field to use in queries.
  </para>
  <para>
   Suppose that we wish to find the document we just inserted.  Inserting adds
   and _id field to the document, so we can query by that:

   <programlisting role="php">
<![CDATA[
<?php

$person = array("name" => "joe");

$people->insert($person);

// now $joe has an _id field
$joe = $people->findOne(array("_id" => $person['_id']));

?>
]]>
   </programlisting>
  </para>
  <para>
   Unless the user has specified otherwise, the _id field is a 
   <classname>MongoId</classname>.  The most common mistake is attepting to use 
   a string to match a <classname>MongoId</classname>.  Keep in mind that these 
   are two different datatypes, and will not match each other in the same way 
   that the string "array()" is not the same as an empty array.  For example:

   <programlisting role="php">
<![CDATA[
<?php

$person = array("name" => "joe");

$people->insert($person);

// convert the _id to a string
$pid = $person['_id'] . "";

// FAILS - $pid is a string, not a MongoId
$joe = $people->findOne(array("_id" => $pid));

?>
]]>
   </programlisting>
  </para>
 </section>

 <section>
  <title>Arrays</title>

  <para>
   Arrays are special in a couple ways.  First, there are two types that 
   MongoDB uses: "normal" arrays and associative arrays.  Associative arrays can
   have any mix of key types and values.  "Normal" arrays are defined as arrays 
   with ascending numeric indexes starting at 0 and increasing by one for each 
   element.  These are, typically, just your usual PHP array.  
  </para>

  <para>
   For instance, if you want to save a list of awards in a document, you could
   say:
  </para>

  <programlisting role="php">
<![CDATA[
<?php

$collection->save(array("awards" => array("gold", "silver", "bronze")));

?>
]]>
  </programlisting>

  <para>
   Queries can reach into arrays to search for elements.  Suppose that we wish 
   to find all documents with an array element of a given value. For example, 
   documents with a "gold" award, such as:
  </para>

  <programlisting>
<![CDATA[
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "awards" : ["gold", "silver", "bronze"]}
]]>
  </programlisting>
  
  <para>
   This can be done with a simple query, ignoring the fact that "awards" is an 
   array:
  </para>

  <programlisting role="php">
<![CDATA[
<?php

  $cursor = $collection->find(array("awards" => "gold"));

?>
]]>
  </programlisting>

  <para>
   Suppose we are querying for a more complex object, if each element of the
   array were an object itself, such as:
  </para>

  <programlisting>
<![CDATA[
{ 
     "_id" : ObjectId("4b06c282edb87a281e09dad9"), 
     "awards" : 
     [
        {
            "first place" : "gold"
        },
        {
            "second place" : "silver" 
        },
        {
            "third place" :  "bronze"
        }
     ]
}
]]>
  </programlisting>

  <para>
   Still ignoring that this is an array, we can use dot notation to query the
   subobject:
  </para>

  <programlisting role="php">
<![CDATA[
<?php

$cursor = $collection->find(array("awards.first place" => "gold"));

?>
]]>
  </programlisting>

  <para>
   Notice that it doesn't matter that there is a space in the the field name
   (although it may be best not to use spaces, just to make things more 
   readable).
  </para>

  <para>
   You can also use an array to query for a number of possible values.  For
   instance, if we were looking for documents "gold" or "copper", we could do:
  </para>

  <programlisting role="php">
<![CDATA[
<?php

$cursor = $collection->find(array("awards" => array('$in' => array("gold", "copper"))));

?>
]]>
  </programlisting>

 </section>
</section>

<!-- 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
-->