svn: /phpdoc/en/trunk/reference/mongo/ mongocursor.xml

From: Date: Mon, 18 Apr 2011 14:33:01 +0000
Subject: svn: /phpdoc/en/trunk/reference/mongo/ mongocursor.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-7969@lists.php.net to get a copy of this message
kristina Mon, 18 Apr 2011 14:33:01 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=310314 Log: added better explanation of what cursors are Changed paths: U phpdoc/en/trunk/reference/mongo/mongocursor.xml Modified: phpdoc/en/trunk/reference/mongo/mongocursor.xml =================================================================== --- phpdoc/en/trunk/reference/mongo/mongocursor.xml 2011-04-18 14:01:04 UTC (rev 310313) +++ phpdoc/en/trunk/reference/mongo/mongocursor.xml 2011-04-18 14:33:01 UTC (rev 310314) @@ -12,16 +12,66 @@ <section xml:id="mongocursor.intro"> &reftitle.intro; <para> - Result object for database query. + A cursor is used to iterate through the results of a database query. For + example, to query the database and see all results, you could do: + <programlisting role="php"> +<![CDATA[ +<?php + +$cursor = $collection->find(); +var_dump(iterator_to_array($cursor)); + +?> +]]> + </programlisting> </para> <para> + You don't generally create cursors using the + <classname>MongoCursor</classname> constructor, you get a new cursor by + calling <function>MongoCollection::find</function> (as shown above). + </para> + <para> + Suppose that, in the example above, <literal>$collection</literal> was a + 50GB collection. We certainly wouldn't want to load that into memory all + at once, which is what a cursor is for: allowing the client to access the + collection in dribs and drabs. + </para> + <para> + If we have a large result set, we can iterate through it, loading a few + megabytes of results into memory at a time. For example, we could do: + <programlisting role="php"> +<![CDATA[ +<?php + +$cursor = $collection->find(); + +foreach ($cursor as $doc) { + // do something to each document +} + +?> +]]> + </programlisting> + This will go through each document in the collection, loading and garbage + collecting documents as needed. + </para> + <para> + Note that this means that a cursor does not "contain" the database results, + it just manages them. Thus, if you print a cursor (with, say, + <function>var_dump</function> or <function>print_r</function>), you'll just + get the cursor object, not your documents. To get the documents themselves, + you can use one of the methods shown above. + </para> + </section> + + <section> + <title>Cursor Stages</title> + <para> A <classname>MongoCursor</classname> has two "life stages": pre- and post- - query. A cursor can be created manually by calling the constructor, but it - is most often created by calling <function>MongoCollection::find</function>. - When a cursor is created, it has not yet contacted the database, so it is in - its pre-query state. In this state, the client can further specify what - they want the query to do, including adding limits, skips, sorts, and more - advanced options. + query. When a cursor is created, it has not yet contacted the database, so + it is in its pre-query state. In this state, the client can further specify + what they want the query to do, including adding limits, skips, sorts, and + more advanced options. </para> <para> When the client attempts to get a result (by calling

« previous php.doc.cvs (#7969) next »