You are browsing a version that has not yet been released.

Search Indexes

In addition to standard indexes, ODM allows you to define search indexes for use with MongoDB Atlas Search. Search indexes may be queried using the $search and $searchMeta aggregation pipeline stages.

Search indexes have some notable differences from regular indexes in ODM. They may only be defined on document classes. Definitions will not be incorporated from embedded documents. Additionally, ODM will NOT translate field names in search index definitions. Database field names must be used instead of mapped field names (i.e. PHP property names).

Search Index Options

Search indexes are defined using a more complex syntax than regular indexes.

ODM supports the following search index options:

name - Name of the search index to create, which must be unique to the collection. Defaults to "default".
dynamic - Enables or disables dynamic field mapping for this index. If true, the index will include all fields with supported data types. If false, the fields attribute must be specified. Defaults to false.
fields - Associative array of field mappings that specify the fields to index (keys). Required only if dynamic mapping is disabled.
analyzer - Specifies the analyzer to apply to string fields when indexing. Defaults to the standard analyzer.
searchAnalyzer - Specifies the analyzer to apply to query text before the text is searched. Defaults to the analyzer attribute, or the standard analyzer. if both are unspecified.
analyzers - Array of custom analyzers to use in this index.
storedSource - Specifies document fields to store for queries performed using the returnedStoredSource option. Specify true to store all fields, false to store no fields, or a document to specify individual fields to include or exclude from storage. Defaults to false.
synonyms - Array of synonym mapping definitions to use in this index.

Additional documentation for defining search indexes may be found in search index definition within the MongoDB manual.

Static Mapping

Static mapping can be used to configure indexing of specific fields within a document.

The following example demonstrates how to define a search index using static mapping.

PHP

1 <?php

#[Document]
#[SearchIndex(
  name: 'usernameAndAddresses',
  fields: [
    'username' => [
      ['type' => 'string'],
      ['type' => 'autocomplete'],
    ],
    'addresses' => ['type' => 'embeddedDocuments', 'dynamic' => true],
  ],
)]
class User
{
    #[Id]
    private string $id;

    #[Field(type: 'string')]
    private string $username;

    #[EmbedMany(targetDocument: Address::class)]
    private ?Address $addresses;

    // ...
}
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

XML

1 <doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping
                    http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping.xsd">

    <document name="Documents\User">
        <search-indexes>
            <search-index name="usernameAndAddresses">
                <field name="username" type="string" />
                <field name="username" type="autocomplete" />
                <field name="addresses" type="embeddedDocuments" dynamic="true" />
            </search-index>
        </search-indexes>

        <!-- ... -->
    </document>
</doctrine-mongo-mapping>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

The username field will indexed both as a string and for autocompletion. Since the addresses field uses an embed-many relationship, it must be indexed using the embeddedDocuments type; however, embedded documents within the array are permitted to use dynamic mapping.

Dynamic Mapping

Dynamic mapping can be used to automatically index fields with supported data types within a document. Dynamically mapped indexes occupy more disk space than statically mapped indexes and may be less performant; however, they may be useful if your schema changes or for when experimenting with Atlas Search

Atlas Search does NOT dynamically index embedded documents contained within arrays (e.g. embed-many relationships). You must use static mappings with the embeddedDocument field type.

The following example demonstrates how to define a search index using dynamic mapping: