<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Create a new Query</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="class.mongodb-driver-query.html">MongoDB\Driver\Query</a></div>
<div class="next" style="text-align: right; float: right;"><a href="class.mongodb-driver-bulkwrite.html">MongoDB\Driver\BulkWrite</a></div>
<div class="up"><a href="class.mongodb-driver-query.html">MongoDB\Driver\Query</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongodb-driver-query.construct" class="refentry">
<div class="refnamediv">
<h1 class="refname">MongoDB\Driver\Query::__construct</h1>
<p class="verinfo">(mongodb >=1.0.0)</p><p class="refpurpose"><span class="refname">MongoDB\Driver\Query::__construct</span> — <span class="dc-title">Create a new Query</span></p>
</div>
<div class="refsect1 description" id="refsect1-mongodb-driver-query.construct-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">final</span> <span class="modifier">public</span> <span class="methodname"><strong>MongoDB\Driver\Query::__construct</strong></span>
( <span class="methodparam"><span class="type"><span class="type array|object">array|object</span></span> <code class="parameter">$filter</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$queryOptions</code></span>
] )</div>
<p class="para rdfs-comment">
Constructs a new <a href="class.mongodb-driver-query.html" class="classname">MongoDB\Driver\Query</a>, which is an
immutable value object that represents a database query. The query may then
be executed with
<span class="methodname"><a href="mongodb-driver-manager.executequery.html" class="methodname">MongoDB\Driver\Manager::executeQuery()</a></span>.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-mongodb-driver-query.construct-parameters">
<h3 class="title">Parameters</h3>
<dl>
<dt>
<code class="parameter">filter</code> (<span class="type"><span class="type array|object">array|object</span></span>)</dt>
<dd>
<p class="para">
The <a href="https://docs.mongodb.com/manual/tutorial/query-documents/" class="link external">» query predicate</a>.
An empty predicate will match all documents in the collection.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
When evaluating query criteria, MongoDB compares types and values according to its own <a href="https://docs.mongodb.com/manual/reference/bson-type-comparison-order/" class="link external">» comparison rules for BSON types</a>, which differs from PHP's <a href="types.comparisons.html" class="link">comparison</a> and <a href="language.types.type-juggling.html" class="link">type juggling</a> rules. When matching a special BSON type the query criteria should use the respective <a href="book.bson.html" class="link">BSON class</a> (e.g. use <a href="class.mongodb-bson-objectid.html" class="classname">MongoDB\BSON\ObjectId</a> to match an <a href="https://docs.mongodb.com/manual/reference/object-id/" class="link external">» ObjectId</a>).
</span>
</p></blockquote>
</dd>
<dt>
<code class="parameter">queryOptions</code></dt>
<dd>
<p class="para">
<table id="mongodb-driver-query.construct-queryOptions" class="doctable table">
<caption><strong>queryOptions</strong></caption>
<thead>
<tr>
<th>Option</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>allowPartialResults</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
<p class="para">
For queries against a sharded collection, returns partial results
from the mongos if some shards are unavailable instead of throwing
an error.
</p>
<p class="para">
Falls back to the deprecated <em>"partial"</em> option if
not specified.
</p>
</td>
</tr>
<tr>
<td>awaitData</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
Use in conjunction with the <em>"tailable"</em> option to
block a getMore operation on the cursor temporarily if at the end of
data rather than returning no data. After a timeout period, the query
returns as normal.
</td>
</tr>
<tr>
<td>batchSize</td>
<td><span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span></td>
<td>
<p class="para">
The number of documents to return in the first batch. Defaults to
101. A batch size of 0 means that the cursor will be established,
but no documents will be returned in the first batch.
</p>
<p class="para">
In versions of MongoDB before 3.2, where queries use the legacy wire
protocol OP_QUERY, a batch size of 1 will close the cursor
irrespective of the number of matched documents.
</p>
</td>
</tr>
<tr>
<td>collation</td>
<td><span class="type"><span class="type array|object">array|object</span></span></td>
<td>
<p class="para">
<a href="https://docs.mongodb.com/master/reference/collation/" class="link external">» Collation</a> allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the <em>"locale"</em> field is mandatory; all other collation fields are optional. For descriptions of the fields, see <a href="https://docs.mongodb.com/master/reference/collation/#collation-document" class="link external">» Collation Document</a>.
</p>
<p class="para">
If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons.
</p>
<p class="para">
This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
</p>
</td>
</tr>
<tr>
<td>comment</td>
<td><span class="type"><a href="language.types.string.html" class="type string">string</a></span></td>
<td>
<p class="para">
A comment to attach to the query to help interpret and trace query
profile data.
</p>
<p class="para">
Falls back to the deprecated <em>"$comment"</em> modifier
if not specified.
</p>
</td>
</tr>
<tr>
<td>exhaust</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
<p class="para">
Stream the data down full blast in multiple "more" packages, on the
assumption that the client will fully read all data queried. Faster
when you are pulling a lot of data and know you want to pull it all
down. Note: the client is not allowed to not read all the data
unless it closes the connection.
</p>
<p class="para">
This option is not supported by the find command in MongoDB 3.2+ and
will force the driver to use the legacy wire protocol version (i.e.
OP_QUERY).
</p>
</td>
</tr>
<tr>
<td>explain</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
<p class="para">
If <strong><code>TRUE</code></strong>, the returned <a href="class.mongodb-driver-cursor.html" class="classname">MongoDB\Driver\Cursor</a>
will contain a single document that describes the process and
indexes used to return the query.
</p>
<p class="para">
Falls back to the deprecated <em>"$explain"</em> modifier
if not specified.
</p>
<p class="para">
This option is not supported by the find command in MongoDB 3.2+ and
will only be respected when using the legacy wire protocol version
(i.e. OP_QUERY). The
<a href="https://docs.mongodb.com/manual/reference/command/explain/" class="link external">» explain</a>
command should be used on MongoDB 3.0+.
</p>
</td>
</tr>
<tr>
<td>hint</td>
<td><span class="type"><span class="type string|array|object">string|array|object</span></span></td>
<td>
<p class="para">
Index specification. Specify either the index name as a string or
the index key pattern. If specified, then the query system will only
consider plans using the hinted index.
</p>
<p class="para">
Falls back to the deprecated <em>"hint"</em> option if not
specified.
</p>
</td>
</tr>
<tr>
<td>limit</td>
<td><span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span></td>
<td>
<p class="para">
The maximum number of documents to return. If unspecified, then
defaults to no limit. A limit of 0 is equivalent to setting no
limit.
</p>
<p class="para">
A negative limit is will be interpreted as a positive limit with the
<em>"singleBatch"</em> option set to <strong><code>TRUE</code></strong>. This behavior
is supported for backwards compatibility, but should be considered
deprecated.
</p>
</td>
</tr>
<tr>
<td>max</td>
<td><span class="type"><span class="type array|object">array|object</span></span></td>
<td>
<p class="para">
The <em class="emphasis">exclusive</em> upper bound for a specific index.
</p>
<p class="para">
Falls back to the deprecated <em>"$max"</em> modifier if
not specified.
</p>
</td>
</tr>
<tr>
<td>maxAwaitTimeMS</td>
<td><span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span></td>
<td>
<p class="para">
Positive integer denoting the time limit in milliseconds for the
server to block a getMore operation if no data is available. This
option should only be used in conjunction with the
<em>"tailable"</em> and <em>"awaitData"</em>
options.
</p>
</td>
</tr>
<tr>
<td>maxScan</td>
<td><span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span></td>
<td>
<div class="warning"><strong class="warning">Warning</strong>
<p class="simpara">
This option is deprecated and should not be used.
</p>
</div>
<p class="para">
Positive integer denoting the maximum number of documents or index
keys to scan when executing the query.
</p>
<p class="para">
Falls back to the deprecated <em>"$maxScan"</em> modifier
if not specified.
</p>
</td>
</tr>
<tr>
<td>maxTimeMS</td>
<td><span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span></td>
<td>
<p class="para">
The cumulative time limit in milliseconds for processing operations
on the cursor. MongoDB aborts the operation at the earliest
following interrupt point.
</p>
<p class="para">
Falls back to the deprecated <em>"$maxTimeMS"</em>
modifier if not specified.
</p>
</td>
</tr>
<tr>
<td>min</td>
<td><span class="type"><span class="type array|object">array|object</span></span></td>
<td>
<p class="para">
The <em class="emphasis">inclusive</em> lower bound for a specific index.
</p>
<p class="para">
Falls back to the deprecated <em>"$min"</em> modifier if
not specified.
</p>
</td>
</tr>
<tr>
<td>modifiers</td>
<td><span class="type"><a href="language.types.array.html" class="type array">array</a></span></td>
<td>
<a href="https://docs.mongodb.com/manual/reference/operator/query-modifier/" class="link external">» Meta operators</a>
modifying the output or behavior of a query. Use of these operators
is deprecated in favor of named options.
</td>
</tr>
<tr>
<td>noCursorTimeout</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
Prevents the server from timing out idle cursors after an inactivity
period (10 minutes).
</td>
</tr>
<tr>
<td>oplogReplay</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
<p class="para">
Internal use for replica sets. To use oplogReplay, you must include
the following condition in the filter:
</p>
<p class="para">
<div class="example-contents">
<div class="textcode"><pre class="textcode">[ 'ts' => [ '$gte' => <timestamp> ] ]</pre>
</div>
</div>
</p>
</td>
</tr>
<tr>
<td>projection</td>
<td><span class="type"><span class="type array|object">array|object</span></span></td>
<td>
<p class="para">
The <a href="https://docs.mongodb.com/manual/tutorial/project-fields-from-query-results/" class="link external">» projection specification</a>
to determine which fields to include in the returned documents.
</p>
<p class="para">
If you are using the <a href="mongodb.persistence.deserialization.html" class="link">ODM
functionality</a> to deserialise documents as their original
PHP class, make sure that you include the
<span class="property">__pclass</span> field in the projection. This is
required for the deserialization to work and without it, the
driver will return (by default) a <strong class="classname">stdClass</strong>
object instead.
</p>
</td>
</tr>
<tr>
<td>readConcern</td>
<td><a href="class.mongodb-driver-readconcern.html" class="classname">MongoDB\Driver\ReadConcern</a></td>
<td>
<p class="para">
A read concern to apply to the operation. By default, the read
concern from the
<a href="mongodb-driver-manager.construct.html#mongodb-driver-manager.construct-uri" class="link">MongoDB
Connection URI</a> will be used.
</p>
<p class="para">
This option is available in MongoDB 3.2+ and will result in an
exception at execution time if specified for an older server
version.
</p>
</td>
</tr>
<tr>
<td>returnKey</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
<p class="para">
If <strong><code>TRUE</code></strong>, returns only the index keys in the resulting documents.
Default value is <strong><code>FALSE</code></strong>. If <strong><code>TRUE</code></strong> and the find command does not
use an index, the returned documents will be empty.
</p>
<p class="para">
Falls back to the deprecated <em>"$returnKey"</em>
modifier if not specified.
</p>
</td>
</tr>
<tr>
<td>showRecordId</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
<p class="para">
Determines whether to return the record identifier for each
document. If <strong><code>TRUE</code></strong>, adds a top-level <em>"$recordId"</em>
field to the returned documents.
</p>
<p class="para">
Falls back to the deprecated <em>"$showDiskLoc"</em>
modifier if not specified.
</p>
</td>
</tr>
<tr>
<td>singleBatch</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
Determines whether to close the cursor after the first batch.
Defaults to <strong><code>FALSE</code></strong>.
</td>
</tr>
<tr>
<td>skip</td>
<td><span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span></td>
<td>Number of documents to skip. Defaults to 0.</td>
</tr>
<tr>
<td>slaveOk</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>Allow query of replica set secondaries</td>
</tr>
<tr>
<td>snapshot</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
<div class="warning"><strong class="warning">Warning</strong>
<p class="simpara">
This option is deprecated and should not be used.
</p>
</div>
<p class="para">
Prevents the cursor from returning a document more than once because
of an intervening write operation.
</p>
<p class="para">
Falls back to the deprecated <em>"$snapshot"</em> modifier
if not specified.
</p>
</td>
</tr>
<tr>
<td>sort</td>
<td><span class="type"><span class="type array|object">array|object</span></span></td>
<td>
<p class="para">The sort specification for the ordering of the results.</p>
<p class="para">
Falls back to the deprecated <em>"$orderby"</em> modifier
if not specified.
</p>
</td>
</tr>
<tr>
<td>tailable</td>
<td><span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>Returns a tailable cursor for a capped collection.</td>
</tr>
</tbody>
</table>
</p>
</dd>
</dl>
</div>
<div class="refsect1 errors" id="refsect1-mongodb-driver-query.construct-errors">
<h3 class="title">Errors/Exceptions</h3>
<ul class="simplelist">
<li class="member">Throws <a href="class.mongodb-driver-exception-invalidargumentexception.html" class="classname">MongoDB\Driver\Exception\InvalidArgumentException</a> on argument parsing errors.</li>
</ul>
</div>
<div class="refsect1 changelog" id="refsect1-mongodb-driver-query.construct-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>1.5.0</td>
<td>
<p class="para">
The <em>"maxScan"</em> and <em>"snapshot"</em>
options are deprecated.
</p>
</td>
</tr>
<tr>
<td>1.3.0</td>
<td>
<p class="para">
Added the <em>"maxAwaitTimeMS"</em> option.
</p>
</td>
</tr>
<tr>
<td>1.2.0</td>
<td>
<p class="para">
Added the <em>"allowPartialResults"</em>,
<em>"collation"</em>, <em>"comment"</em>,
<em>"hint"</em>, <em>"max"</em>,
<em>"maxScan"</em>, <em>"maxTimeMS"</em>,
<em>"min"</em>, <em>"returnKey"</em>,
<em>"showRecordId"</em>, and <em>"snapshot"</em>
options.
</p>
<p class="para">
Renamed the <em>"partial"</em> option to
<em>"allowPartialResults"</em>. For backwards compatibility,
<em>"partial"</em> will still be read if
<em>"allowPartialResults"</em> is not specified.
</p>
<p class="para">
Removed the <em>"slaveOk"</em> option, which is obsolete.
For queries using the legacy wire protocol OP_QUERY, the driver will
set the <em>slaveOk</em> bit as needed in accordance with the
<a href="https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst" class="link external">» Server Selection Specification</a>.
</p>
</td>
</tr>
<tr>
<td>1.1.0</td>
<td>Added the <em>"readConcern"</em> option.</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-mongodb-driver-query.construct-examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-1695">
<p><strong>Example #1 <span class="function"><strong>MongoDB\Driver\Query::__construct()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Select only documents authord by "bjori" with at least 100 views */<br /></span><span style="color: #0000BB">$filter </span><span style="color: #007700">= [<br /> </span><span style="color: #DD0000">'author' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'bjori'</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'views' </span><span style="color: #007700">=> [<br /> </span><span style="color: #DD0000">'$gte' </span><span style="color: #007700">=> </span><span style="color: #0000BB">100</span><span style="color: #007700">,<br /> ],<br />];<br /><br /></span><span style="color: #0000BB">$options </span><span style="color: #007700">= [<br /> </span><span style="color: #FF8000">/* Only return the following fields in the matching documents */<br /> </span><span style="color: #DD0000">'projection' </span><span style="color: #007700">=> [<br /> </span><span style="color: #DD0000">'title' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'article' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">,<br /> ],<br /> </span><span style="color: #FF8000">/* Return the documents in descending order of views */<br /> </span><span style="color: #DD0000">'sort' </span><span style="color: #007700">=> [<br /> </span><span style="color: #DD0000">'views' </span><span style="color: #007700">=> -</span><span style="color: #0000BB">1<br /> </span><span style="color: #007700">],<br />];<br /><br /></span><span style="color: #0000BB">$query </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">Query</span><span style="color: #007700">(</span><span style="color: #0000BB">$filter</span><span style="color: #007700">, </span><span style="color: #0000BB">$options</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$manager </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">Manager</span><span style="color: #007700">(</span><span style="color: #DD0000">'mongodb://localhost:27017'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$readPreference </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">ReadPreference</span><span style="color: #007700">(</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">ReadPreference</span><span style="color: #007700">::</span><span style="color: #0000BB">RP_PRIMARY</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$cursor </span><span style="color: #007700">= </span><span style="color: #0000BB">$manager</span><span style="color: #007700">-></span><span style="color: #0000BB">executeQuery</span><span style="color: #007700">(</span><span style="color: #DD0000">'databaseName.collectionName'</span><span style="color: #007700">, </span><span style="color: #0000BB">$query</span><span style="color: #007700">, </span><span style="color: #0000BB">$readPreference</span><span style="color: #007700">);<br /><br />foreach(</span><span style="color: #0000BB">$cursor </span><span style="color: #007700">as </span><span style="color: #0000BB">$document</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$document</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-mongodb-driver-query.construct-seealso">
<h3 class="title">See Also</h3>
<ul class="simplelist">
<li class="member"><span class="methodname"><a href="mongodb-driver-manager.executequery.html" class="methodname" rel="rdfs-seeAlso">MongoDB\Driver\Manager::executeQuery()</a> - Execute a database query</span></li>
<li class="member"><a href="class.mongodb-driver-cursor.html" class="classname">MongoDB\Driver\Cursor</a></li>
</ul>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="class.mongodb-driver-query.html">MongoDB\Driver\Query</a></div>
<div class="next" style="text-align: right; float: right;"><a href="class.mongodb-driver-bulkwrite.html">MongoDB\Driver\BulkWrite</a></div>
<div class="up"><a href="class.mongodb-driver-query.html">MongoDB\Driver\Query</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
