will/mongodb-odm-docs-dash
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
4d1b823198
mongodb-odm-docs-dash/Doctrine ODM.docset/Contents/Resources/Documents/reference/indexes.html

677 lines
39 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Indexes &mdash; Doctrine MongoDB ODM 1.1.5 documentation</title>
<link rel="stylesheet" href="../_static/bootstrap/css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/layout.css" type="text/css" />
<link rel="stylesheet" href="../_static/configurationblock.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.1.5',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/configurationblock.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/configurationblock.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/configurationblock.js"></script>
<script src="../_static/bootstrap/js/bootstrap.min.js"></script>
<script type="text/javascript">
<!--
$(document).ready(function() {
$("#versions").change(function() {
var docsUrl = $(this).val();
window.location.href = docsUrl;
});
});
-->
</script>
<link rel="shortcut icon" href="../_static/doctrine.ico"/>
<link rel="search" title="Search" href="../search.html" />
<link rel="top" title="Doctrine MongoDB ODM 1.1.5 documentation" href="../index.html" />
</head>
<body>
<div id="wrapper">
<div id="header">
<h1 id="h1title"></h1>
<div id="logo">
<a href="http://www.doctrine-project.org/">Doctrine - PHP Database Libraries</a>
</div>
</div>
<div id="nav" class="cls">
<div class="tl cls">
<ul>
<li><a target="_top" href="http://www.doctrine-project.org/">Home</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/about.html">About</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/projects.html">Projects</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/contribute.html">Contribute</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/community.html">Community</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/archive.html">Blog</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/jira">Development</a></li>
</ul>
</div>
</div>
<div id="content" class="cls">
<div class="related">
<h3>Navigation</h3>
<ul>
<li><a href="/">Doctrine Homepage</a> &raquo;</li>
<li><a href="../index.html">Doctrine MongoDB ODM 1.1.5 documentation</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" >
<div class="section" id="indexes">
<h1>Indexes<a class="headerlink" href="#indexes" title="Permalink to this headline"></a></h1>
<p>Working with indexes in the MongoDB ODM is pretty straight forward.
You can have multiple indexes, they can consist of multiple fields,
they can be unique and you can give them an order. In this chapter
we'll show you examples of indexes using annotations.</p>
<p>First here is an example where we put an index on a single
property:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">namespace</span> <span class="nx">Documents</span><span class="p">;</span>
<span class="sd">/** @Document */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">public</span> <span class="nv">$id</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;string&quot;) @Index */</span>
<span class="k">public</span> <span class="nv">$username</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;field</span> <span class="na">name=</span><span class="s">&quot;username&quot;</span> <span class="na">index=</span><span class="s">&quot;true&quot;</span> <span class="nt">/&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">fields</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">username</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">index</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="index-options">
<h2>Index Options<a class="headerlink" href="#index-options" title="Permalink to this headline"></a></h2>
<p>You can customize the index with some additional options:</p>
<ul class="simple">
<li><strong>name</strong> - The name of the index. This can be useful if you are
indexing many keys and Mongo complains about the index name being
too long.</li>
<li><strong>dropDups</strong> - If a unique index is being created and duplicate
values exist, drop all but one duplicate value.</li>
<li><strong>background</strong> - Create indexes in the background while other
operations are taking place. By default, index creation happens
synchronously. If you specify TRUE with this option, index creation
will be asynchronous.</li>
<li><strong>safe</strong> - You can specify a boolean value for checking if the
index creation succeeded. The driver will throw a
MongoCursorException if index creation failed.</li>
<li><strong>expireAfterSeconds</strong> - If you specify this option then the associated
document will be automatically removed when the provided time (in seconds)
has passed. This option is bound to a number of limitations, which
are documented at <a class="reference external" href="https://docs.mongodb.com/manual/tutorial/expire-data/">https://docs.mongodb.com/manual/tutorial/expire-data/</a>.</li>
<li><strong>order</strong> - The order of the index (asc or desc).</li>
<li><strong>unique</strong> - Create a unique index.</li>
<li><strong>sparse</strong> - Create a sparse index. If a unique index is being created
the sparse option will allow duplicate null entries, but the field must be
unique otherwise.</li>
<li><strong>partialFilterExpression</strong> - Create a partial index. Partial indexes only
index the documents in a collection that meet a specified filter expression.
By indexing a subset of the documents in a collection, partial indexes have
lower storage requirements and reduced performance costs for index creation
and maintenance. This feature was introduced with MongoDB 3.2 and is not
available on older versions.</li>
</ul>
</div>
<div class="section" id="unique-index">
<h2>Unique Index<a class="headerlink" href="#unique-index" title="Permalink to this headline"></a></h2>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">namespace</span> <span class="nx">Documents</span><span class="p">;</span>
<span class="sd">/** @Document */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">public</span> <span class="nv">$id</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;string&quot;) @Index(unique=true, order=&quot;asc&quot;) */</span>
<span class="k">public</span> <span class="nv">$username</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;field</span> <span class="na">fieldName=</span><span class="s">&quot;username&quot;</span> <span class="na">index=</span><span class="s">&quot;true&quot;</span> <span class="na">unique=</span><span class="s">&quot;true&quot;</span> <span class="na">order=</span><span class="s">&quot;asc&quot;</span> <span class="nt">/&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">fields</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">username</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">index</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="l l-Scalar l-Scalar-Plain">unique</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="l l-Scalar l-Scalar-Plain">order</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
</pre></div>
</div>
</li>
</ul>
</div>
<p>For your convenience you can quickly specify a unique index with
<code class="docutils literal"><span class="pre">&#64;UniqueIndex</span></code>:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">namespace</span> <span class="nx">Documents</span><span class="p">;</span>
<span class="sd">/** @Document */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">public</span> <span class="nv">$id</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;string&quot;) @UniqueIndex(order=&quot;asc&quot;) */</span>
<span class="k">public</span> <span class="nv">$username</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;field</span> <span class="na">fieldName=</span><span class="s">&quot;username&quot;</span> <span class="na">unique=</span><span class="s">&quot;true&quot;</span> <span class="na">order=</span><span class="s">&quot;asc&quot;</span> <span class="nt">/&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">fields</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">username</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">unique</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="l l-Scalar l-Scalar-Plain">order</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
</pre></div>
</div>
</li>
</ul>
</div>
<p>If you want to specify an index that consists of multiple fields
you can specify them on the class doc block:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">namespace</span> <span class="nx">Documents</span><span class="p">;</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @UniqueIndex(keys={&quot;accountId&quot;=&quot;asc&quot;, &quot;username&quot;=&quot;asc&quot;})</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">public</span> <span class="nv">$id</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;int&quot;) */</span>
<span class="k">public</span> <span class="nv">$accountId</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;string&quot;) */</span>
<span class="k">public</span> <span class="nv">$username</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;doctrine-mongo-mapping</span> <span class="na">xmlns=</span><span class="s">&quot;http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping&quot;</span>
<span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span>
<span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping</span>
<span class="s"> http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping.xsd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;document</span> <span class="na">name=</span><span class="s">&quot;Documents\User&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;indexes&gt;</span>
<span class="nt">&lt;index&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;unique&quot;</span> <span class="na">value=</span><span class="s">&quot;true&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;key</span> <span class="na">name=</span><span class="s">&quot;accountId&quot;</span> <span class="na">order=</span><span class="s">&quot;asc&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;key</span> <span class="na">name=</span><span class="s">&quot;username&quot;</span> <span class="na">order=</span><span class="s">&quot;asc&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/index&gt;</span>
<span class="nt">&lt;/indexes&gt;</span>
<span class="nt">&lt;/document&gt;</span>
<span class="nt">&lt;/doctrine-mongo-mapping&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">Documents\User</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">indexes</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">usernameacctid</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">options</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">unique</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="l l-Scalar l-Scalar-Plain">keys</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">accountId</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">order</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">asc</span>
<span class="l l-Scalar l-Scalar-Plain">username</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">order</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">asc</span>
</pre></div>
</div>
</li>
</ul>
</div>
<p>To specify multiple indexes you must use the <code class="docutils literal"><span class="pre">&#64;Indexes</span></code>
annotation:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @Indexes({</span>
<span class="sd"> * @Index(keys={&quot;accountId&quot;=&quot;asc&quot;}),</span>
<span class="sd"> * @Index(keys={&quot;username&quot;=&quot;asc&quot;})</span>
<span class="sd"> * })</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">public</span> <span class="nv">$id</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;int&quot;) */</span>
<span class="k">public</span> <span class="nv">$accountId</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;string&quot;) */</span>
<span class="k">public</span> <span class="nv">$username</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;doctrine-mongo-mapping</span> <span class="na">xmlns=</span><span class="s">&quot;http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping&quot;</span>
<span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span>
<span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping</span>
<span class="s"> http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping.xsd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;document</span> <span class="na">name=</span><span class="s">&quot;Documents\User&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;indexes&gt;</span>
<span class="nt">&lt;index&gt;</span>
<span class="nt">&lt;key</span> <span class="na">name=</span><span class="s">&quot;accountId&quot;</span> <span class="na">order=</span><span class="s">&quot;asc&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/index&gt;</span>
<span class="nt">&lt;index&gt;</span>
<span class="nt">&lt;key</span> <span class="na">name=</span><span class="s">&quot;username&quot;</span> <span class="na">order=</span><span class="s">&quot;asc&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/index&gt;</span>
<span class="nt">&lt;/indexes&gt;</span>
<span class="nt">&lt;/document&gt;</span>
<span class="nt">&lt;/doctrine-mongo-mapping&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">Documents\User</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">indexes</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">accountId</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">keys</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">accountId</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">order</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">asc</span>
<span class="l l-Scalar l-Scalar-Plain">username</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">keys</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">username</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">order</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">asc</span>
</pre></div>
</div>
</li>
</ul>
</div>
</div>
<div class="section" id="embedded-indexes">
<h2>Embedded Indexes<a class="headerlink" href="#embedded-indexes" title="Permalink to this headline"></a></h2>
<p>You can specify indexes on embedded documents just like you do on normal documents. When Doctrine
creates the indexes for a document it will also create all the indexes from its mapped embedded
documents.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">namespace</span> <span class="nx">Documents</span><span class="p">;</span>
<span class="sd">/** @EmbeddedDocument */</span>
<span class="k">class</span> <span class="nc">Comment</span>
<span class="p">{</span>
<span class="sd">/** @Field(type=&quot;date&quot;) @Index */</span>
<span class="k">private</span> <span class="nv">$date</span><span class="p">;</span>
<span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Now if we had a <code class="docutils literal"><span class="pre">BlogPost</span></code> document with the <code class="docutils literal"><span class="pre">Comment</span></code> document embedded many times:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">namespace</span> <span class="nx">Documents</span><span class="p">;</span>
<span class="sd">/** @Document */</span>
<span class="k">class</span> <span class="nc">BlogPost</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @Field(type=&quot;string&quot;) @Index */</span>
<span class="k">private</span> <span class="nv">$slug</span><span class="p">;</span>
<span class="sd">/** @EmbedMany(targetDocument=&quot;Comment&quot;) */</span>
<span class="k">private</span> <span class="nv">$comments</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If we were to create the indexes with the <code class="docutils literal"><span class="pre">SchemaManager</span></code>:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="nv">$sm</span><span class="o">-&gt;</span><span class="na">ensureIndexes</span><span class="p">();</span>
</pre></div>
</div>
<p>It will create the indexes from the <code class="docutils literal"><span class="pre">BlogPost</span></code> document but will also create the indexes that are
defined on the <code class="docutils literal"><span class="pre">Comment</span></code> embedded document. The following would be executed on the underlying MongoDB
database:</p>
<blockquote>
<div>db.BlogPost.ensureIndexes({ 'slug' : 1, 'comments.date': 1 })</div></blockquote>
<p>Also, for your convenience you can create the indexes for your mapped documents from the
<a class="reference internal" href="console-commands.html"><span class="doc">console</span></a>:</p>
<blockquote>
<div>$ php mongodb.php mongodb:schema:create --index</div></blockquote>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you are <a class="reference internal" href="embedded-mapping.html#embed-mixing-document-types"><span class="std std-ref">mixing document types</span></a> for your
embedded documents, ODM will not be able to create indexes for their fields
unless you specify a discriminator map for the <a class="reference internal" href="embedded-mapping.html#embed-one"><span class="std std-ref">embed-one</span></a>
or <a class="reference internal" href="embedded-mapping.html#embed-many"><span class="std std-ref">embed-many</span></a> relationship.</p>
</div>
</div>
<div class="section" id="geospatial-indexing">
<h2>Geospatial Indexing<a class="headerlink" href="#geospatial-indexing" title="Permalink to this headline"></a></h2>
<p>You can specify a geospatial index by just specifying the keys and
options structures manually:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @Index(keys={&quot;coordinates&quot;=&quot;2d&quot;})</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Place</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">public</span> <span class="nv">$id</span><span class="p">;</span>
<span class="sd">/** @EmbedOne(targetDocument=&quot;Coordinates&quot;) */</span>
<span class="k">public</span> <span class="nv">$coordinates</span><span class="p">;</span>
<span class="p">}</span>
<span class="sd">/** @EmbeddedDocument */</span>
<span class="k">class</span> <span class="nc">Coordinates</span>
<span class="p">{</span>
<span class="sd">/** @Field(type=&quot;float&quot;) */</span>
<span class="k">public</span> <span class="nv">$latitude</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;float&quot;) */</span>
<span class="k">public</span> <span class="nv">$longitude</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;indexes&gt;</span>
<span class="nt">&lt;index&gt;</span>
<span class="nt">&lt;key</span> <span class="na">name=</span><span class="s">&quot;coordinates&quot;</span> <span class="na">order=</span><span class="s">&quot;2d&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/index&gt;</span>
<span class="nt">&lt;/indexes&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">indexes</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">coordinates</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">keys</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">coordinates</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">2d</span>
</pre></div>
</div>
</li>
</ul>
</div>
</div>
<div class="section" id="partial-indexes">
<h2>Partial indexes<a class="headerlink" href="#partial-indexes" title="Permalink to this headline"></a></h2>
<p>You can create a partial index by adding a <code class="docutils literal"><span class="pre">partialFilterExpression</span></code> to any
index.</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @Index(keys={&quot;city&quot;=&quot;asc&quot;}, partialFilterExpression={&quot;version&quot;={&quot;$gt&quot;=1}})</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Place</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">public</span> <span class="nv">$id</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;string&quot;) */</span>
<span class="k">public</span> <span class="nv">$city</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;int&quot;) */</span>
<span class="k">public</span> <span class="nv">$version</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;indexes&gt;</span>
<span class="nt">&lt;index&gt;</span>
<span class="nt">&lt;key</span> <span class="na">name=</span><span class="s">&quot;city&quot;</span> <span class="na">order=</span><span class="s">&quot;asc&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;partial-filter-expression&gt;</span>
<span class="nt">&lt;field</span> <span class="na">name=</span><span class="s">&quot;version&quot;</span> <span class="na">value=</span><span class="s">&quot;1&quot;</span> <span class="na">operator=</span><span class="s">&quot;gt&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/partial-filter-expression&gt;</span>
<span class="nt">&lt;/index&gt;</span>
<span class="nt">&lt;/indexes&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">indexes</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">partialIndexExample</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">keys</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">coordinates</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">asc</span>
<span class="l l-Scalar l-Scalar-Plain">options</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">partialFilterExpression</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">version</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">{</span> <span class="nv">$gt</span><span class="p p-Indicator">:</span> <span class="nv">1</span> <span class="p p-Indicator">}</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Partial indexes are only available with MongoDB 3.2 or newer. For more
information on partial filter expressions, read the
<a class="reference external" href="https://docs.mongodb.com/manual/core/index-partial/">official MongoDB documentation</a>.</p>
</div>
</div>
<div class="section" id="requiring-indexes">
<h2>Requiring Indexes<a class="headerlink" href="#requiring-indexes" title="Permalink to this headline"></a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Requiring Indexes was deprecated in 1.2 and will be removed in 2.0.</p>
</div>
<p>Sometimes you may want to require indexes for all your queries to ensure you don't let stray unindexed queries
make it to the database and cause performance problems.</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document(requireIndexes=true)</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Place</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">public</span> <span class="nv">$id</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;string&quot;) @Index */</span>
<span class="k">public</span> <span class="nv">$city</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre>// Documents.Place.dcm.xml
<span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="nt">&lt;doctrine-mongo-mapping</span> <span class="na">xmlns=</span><span class="s">&quot;http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping&quot;</span>
<span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span>
<span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping</span>
<span class="s"> http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping.xsd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;document</span> <span class="na">name=</span><span class="s">&quot;Documents\Place&quot;</span> <span class="na">require-indexes=</span><span class="s">&quot;true&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;field</span> <span class="na">fieldName=</span><span class="s">&quot;id&quot;</span> <span class="na">id=</span><span class="s">&quot;true&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;field</span> <span class="na">fieldName=</span><span class="s">&quot;city&quot;</span> <span class="na">type=</span><span class="s">&quot;string&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;indexes&gt;</span>
<span class="nt">&lt;index&gt;</span>
<span class="nt">&lt;key</span> <span class="na">name=</span><span class="s">&quot;city&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;/index&gt;</span>
<span class="nt">&lt;/indexes&gt;</span>
<span class="nt">&lt;/document&gt;</span>
<span class="nt">&lt;/doctrine-mongo-mapping&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="c1"># Documents.Place.dcm.yml</span>
<span class="l l-Scalar l-Scalar-Plain">Documents\Place</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">fields</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">id</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">id</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="l l-Scalar l-Scalar-Plain">city</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">type</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">string</span>
<span class="l l-Scalar l-Scalar-Plain">indexes</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">index1</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">keys</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">city</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">asc</span>
</pre></div>
</div>
</li>
</ul>
</div>
<p>When you run queries it will check that it is indexed and throw an exception if it is not indexed:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="nv">$qb</span> <span class="o">=</span> <span class="nv">$dm</span><span class="o">-&gt;</span><span class="na">createQueryBuilder</span><span class="p">(</span><span class="s1">&#39;Documents\Place&#39;</span><span class="p">)</span>
<span class="o">-&gt;</span><span class="na">field</span><span class="p">(</span><span class="s1">&#39;city&#39;</span><span class="p">)</span><span class="o">-&gt;</span><span class="na">equals</span><span class="p">(</span><span class="s1">&#39;Nashville&#39;</span><span class="p">);</span>
<span class="nv">$query</span> <span class="o">=</span> <span class="nv">$qb</span><span class="o">-&gt;</span><span class="na">getQuery</span><span class="p">();</span>
<span class="nv">$places</span> <span class="o">=</span> <span class="nv">$query</span><span class="o">-&gt;</span><span class="na">execute</span><span class="p">();</span>
</pre></div>
</div>
<p>When you execute the query it will throw an exception if <cite>city</cite> was not indexed in the database. You can control
whether or not an exception will be thrown by using the <cite>requireIndexes()</cite> method:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="nv">$qb</span><span class="o">-&gt;</span><span class="na">requireIndexes</span><span class="p">(</span><span class="k">false</span><span class="p">);</span>
</pre></div>
</div>
<p>You can also check if the query is indexed and with the <cite>isIndexed()</cite> method and use it to display your
own notification when a query is unindexed:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="nv">$query</span> <span class="o">=</span> <span class="nv">$qb</span><span class="o">-&gt;</span><span class="na">getQuery</span><span class="p">();</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nv">$query</span><span class="o">-&gt;</span><span class="na">isIndexed</span><span class="p">())</span> <span class="p">{</span>
<span class="nv">$notifier</span><span class="o">-&gt;</span><span class="na">addError</span><span class="p">(</span><span class="s1">&#39;Cannot execute queries that are not indexed.&#39;</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If you don't want to require indexes for all queries you can set leave <cite>requireIndexes</cite> as false and control
it on a per query basis:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="nv">$qb</span><span class="o">-&gt;</span><span class="na">requireIndexes</span><span class="p">(</span><span class="k">true</span><span class="p">);</span>
<span class="nv">$query</span> <span class="o">=</span> <span class="nv">$qb</span><span class="o">-&gt;</span><span class="na">getQuery</span><span class="p">();</span>
<span class="nv">$results</span> <span class="o">=</span> <span class="nv">$query</span><span class="o">-&gt;</span><span class="na">execute</span><span class="p">();</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<div id="searchbox" style="">
<h3>Search</h3>
<form class="search" action="http://readthedocs.org/search/project/" method="get">
<input type="text" name="q" size="18">
<input type="submit" value="Go">
<input type="hidden" name="selected_facets" value="project:">
</form>
</div>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Indexes</a><ul>
<li><a class="reference internal" href="#index-options">Index Options</a></li>
<li><a class="reference internal" href="#unique-index">Unique Index</a></li>
<li><a class="reference internal" href="#embedded-indexes">Embedded Indexes</a></li>
<li><a class="reference internal" href="#geospatial-indexing">Geospatial Indexing</a></li>
<li><a class="reference internal" href="#partial-indexes">Partial indexes</a></li>
<li><a class="reference internal" href="#requiring-indexes">Requiring Indexes</a></li>
</ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/reference/indexes.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy; Copyright 2013, Doctrine Project Team.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.6.2.
<br/>
<a target="_BLANK" href="http://www.servergrove.com"><img src="http://www.doctrine-project.org/_static/servergrove.jpg" /></a> <br/><br/>
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick" />
<input type="hidden" name="hosted_button_id" value="BAE2E3XANQ77Y" />
<input type="image" src="https://www.paypal.com/en_US/i/btn/btn_donateCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!" />
<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1" />
</form>
</div>
</div>
<div id="bot-rcnr">
<div class="tl"><!-- corner --></div>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-288343-7";
urchinTracker();
</script>
<a class="githublink" href="http://github.com/doctrine"><img src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink