1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 317663 $ -->
<refentry xml:id="mongocursor.addoption" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCursor::addOption</refname>
<refpurpose>Adds a top-level key/value pair to a query</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>MongoCursor</type><methodname>MongoCursor::addOption</methodname>
<methodparam><type>string</type><parameter>key</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
</methodsynopsis>
<para>
This is an advanced function and should not be used unless you know what
you're doing.
</para>
<para>
A query can optionally be nested in a "query" field if other options, such as
a sort or hint, are given. For instance, adding a sort causes the query
to become a subfield of a bigger query object, like:
<programlisting role="php">
<![CDATA[
<?php
$query = array("query" => $query, "orderby" => $sort);
?>
]]>
</programlisting>
</para>
<para>
This method is for adding a top-level field to a query. It makes the query a
subobject (if it isn't already) and adds the key/value pair of your chosing
to the top level.
</para>
<warning>
<para>
It cannot be used to add extra criteria to a query on the fly. For instance,
this <emphasis>will not</emphasis> work:
<programlisting role="php">
<![CDATA[
<?php
// NOT CORRECT
$cursor = $users->find()->addOption("name", "joe")->addOption("age", 20);
?>
]]>
</programlisting>
This <emphasis>does not</emphasis> query for a user named "joe" with an age of 20.
</para>
</warning>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>key</parameter>
</term>
<listitem>
<para>
Fieldname to add.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>value</parameter>
</term>
<listitem>
<para>
Value to add.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns this cursor.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoCursorException</classname> if this cursor has started iterating.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCursor::addOption</function> example</title>
<para>
Using <function>MongoCursor::skip</function> to skip over millions of
results can become slow. One way around this is to use
<literal>$min</literal> or <literal>$max</literal> options for the query.
These can be handy, but they require an index on exactly the fields being
searched for. This is an example of how to use <literal>$min</literal> as
an alternative to <function>MongoCursor::skip</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
// make sure we have an index
$c->ensureIndex(array("ts" => 1));
// you may have to modify this to run in a reasonable amount of time on slow
// machines (should take about 30 seconds on a good machine)
for ($i = 0; $i < 30000000; $i++) {
$c->insert(array("ts" => new MongoDate(), "i" => $i));
}
$now = strtotime("now");
// find documents inserted in the last 2 seconds
$cursor = $c->find()->addOption('$min', array("ts" => $now-2));
?>
]]>
</programlisting>
</example>
</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
-->
|
