Skip to content

Commit 53ccbc4

Browse files
jmikolajmikola
authored
PHPLIB-1143: Document Atlas Search index helpers and fix aggregate "collation" docs (#1189)
* PHPLIB-1143: Docs for Atlas Search index helpers * PHPLIB-1306: Add missing docs for aggregate "collation" option
1 parent a01f3cf commit 53ccbc4

20 files changed

+525
-1
lines changed

‎docs/includes/apiargs-MongoDBCollection-method-aggregate-option.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ source:
1010
file: apiargs-aggregate-option.yaml
1111
ref: bypassDocumentValidation
1212
---
13+
source:
14+
file: apiargs-MongoDBCollection-common-option.yaml
15+
ref: collation
16+
---
1317
source:
1418
file: apiargs-common-option.yaml
1519
ref: comment

‎docs/includes/apiargs-MongoDBCollection-method-createSearchIndex-option.yaml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
arg_name: option
2+
name: name
3+
type: string
4+
description: |
5+
Name of the search index to create.
6+
7+
You cannot create multiple indexes with the same name on a single collection.
8+
9+
If you do not specify a name, the index is named "default".
10+
interface: phpmethod
11+
operation: ~
12+
optional: true
13+
---
14+
source:
15+
file: apiargs-common-option.yaml
16+
ref: comment
17+
...

‎docs/includes/apiargs-MongoDBCollection-method-createSearchIndex-param.yaml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
arg_name: param
2+
name: $definition
3+
type: array|object
4+
description: |
5+
Document describing the index to create. For details on definition syntax, see
6+
:manual:`Search Index Definition Syntax </reference/command/createSearchIndexes/#search-index-definition-syntax>`.
7+
interface: phpmethod
8+
operation: ~
9+
optional: false
10+
---
11+
source:
12+
file: apiargs-common-param.yaml
13+
ref: $options
14+
...

‎docs/includes/apiargs-MongoDBCollection-method-createSearchIndexes-option.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
source:
2+
file: apiargs-common-option.yaml
3+
ref: comment
4+
...

‎docs/includes/apiargs-MongoDBCollection-method-createSearchIndexes-param.yaml

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
arg_name: param
2+
name: $indexes
3+
type: array
4+
description: |
5+
Array of documents describing the indexes to create.
6+
7+
A required ``definition`` document field describes the index to create. For
8+
details on definition syntax, see
9+
:manual:`Search Index Definition Syntax </reference/command/createSearchIndexes/#search-index-definition-syntax>`.
10+
11+
An optional ``name`` string field specifies the name of the search index to
12+
create. You cannot create multiple indexes with the same name on a single
13+
collection. If you do not specify a name, the index is named "default".
14+
interface: phpmethod
15+
operation: ~
16+
optional: false
17+
---
18+
source:
19+
file: apiargs-common-param.yaml
20+
ref: $options
21+
...

‎docs/includes/apiargs-MongoDBCollection-method-dropSearchIndex-option.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
source:
2+
file: apiargs-common-option.yaml
3+
ref: comment
4+
...

‎docs/includes/apiargs-MongoDBCollection-method-dropSearchIndex-param.yaml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
arg_name: param
2+
name: $name
3+
type: string
4+
description: |
5+
Name of the index to drop.
6+
interface: phpmethod
7+
operation: ~
8+
optional: false
9+
---
10+
source:
11+
file: apiargs-common-param.yaml
12+
ref: $options
13+
...

‎docs/includes/apiargs-MongoDBCollection-method-listSearchIndexes-option.yaml

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
source:
2+
file: apiargs-aggregate-option.yaml
3+
ref: batchSize
4+
---
5+
source:
6+
file: apiargs-common-option.yaml
7+
ref: collation
8+
---
9+
source:
10+
file: apiargs-common-option.yaml
11+
ref: comment
12+
---
13+
arg_name: option
14+
name: name
15+
type: string
16+
description: |
17+
Name of the index to return information about.
18+
19+
If name is not specified, information for all indexes on the collection will
20+
be returned.
21+
interface: phpmethod
22+
operation: ~
23+
optional: true
24+
---
25+
source:
26+
file: apiargs-common-option.yaml
27+
ref: maxTimeMS
28+
---
29+
source:
30+
file: apiargs-MongoDBCollection-common-option.yaml
31+
ref: readConcern
32+
---
33+
source:
34+
file: apiargs-MongoDBCollection-common-option.yaml
35+
ref: readPreference
36+
---
37+
source:
38+
file: apiargs-common-option.yaml
39+
ref: session
40+
---
41+
source:
42+
file: apiargs-MongoDBCollection-common-option.yaml
43+
ref: typeMap
44+
...

‎docs/includes/apiargs-MongoDBCollection-method-listSearchIndexes-param.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
source:
2+
file: apiargs-common-param.yaml
3+
ref: $options
4+
...

‎docs/includes/apiargs-MongoDBCollection-method-updateSearchIndex-option.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
source:
2+
file: apiargs-common-option.yaml
3+
ref: comment
4+
...

‎docs/includes/apiargs-MongoDBCollection-method-updateSearchIndex-param.yaml

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
arg_name: param
2+
name: $name
3+
type: string
4+
description: |
5+
Name of the index to update.
6+
interface: phpmethod
7+
operation: ~
8+
optional: false
9+
---
10+
arg_name: param
11+
name: $definition
12+
type: array|object
13+
description: |
14+
Document describing the updated search index definition. The specified
15+
definition replaces the prior definition in the search index. For details on
16+
definition syntax, see
17+
:manual:`Search Index Definition Syntax </reference/command/createSearchIndexes/#search-index-definition-syntax>`.
18+
interface: phpmethod
19+
operation: ~
20+
optional: false
21+
---
22+
source:
23+
file: apiargs-common-param.yaml
24+
ref: $options
25+
...

‎docs/includes/apiargs-MongoDBCollection-method-watch-option.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ source:
44
ref: batchSize
55
---
66
source:
7-
file: apiargs-common-option.yaml
7+
file: apiargs-MongoDBCollection-common-option.yaml
88
ref: collation
99
---
1010
source:

‎docs/includes/apiargs-MongoDBDatabase-method-aggregate-option.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ source:
1010
file: apiargs-aggregate-option.yaml
1111
ref: bypassDocumentValidation
1212
---
13+
source:
14+
file: apiargs-common-option.yaml
15+
ref: collation
16+
---
1317
source:
1418
file: apiargs-common-option.yaml
1519
ref: comment

‎docs/includes/extracts-note.yaml

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,24 @@ content: |
99
<manual/en/book.bson.php>` in the driver (e.g. use
1010
:php:`MongoDB\\BSON\\ObjectId <class.mongodb-bson-objectid>` to match an
1111
:manual:`ObjectId </reference/object-id/>`).
12+
---
13+
ref: note-atlas-search-requirement
14+
content: |
15+
.. note::
16+
17+
This command can only be run on a deployment hosted on
18+
:manual:`MongoDB Atlas </atlas>` and requires an Atlas cluster tier of at
19+
least M10. A
20+
`Local Atlas Deployment <https://www.mongodb.com/docs/atlas/cli/stable/atlas-cli-deploy-local/#use-atlas-search-with-a-local-atlas-deployment>`__
21+
can also be used for development.
22+
---
23+
ref: note-atlas-search-async
24+
content: |
25+
.. note::
26+
27+
Atlas Search indexes are managed asynchronously. After creating or
28+
updating an index, you can periodically execute
29+
:phpmethod:`MongoDB\\Collection::listSearchIndexes()` and check the
30+
``queryable`` :manual:`output field </reference/operator/aggregation/listSearchIndexes/#output>`
31+
to determine whether it is ready to be used.
1232
...

‎docs/reference/class/MongoDBCollection.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,12 +65,15 @@ Methods
6565
/reference/method/MongoDBCollection-countDocuments
6666
/reference/method/MongoDBCollection-createIndex
6767
/reference/method/MongoDBCollection-createIndexes
68+
/reference/method/MongoDBCollection-createSearchIndex
69+
/reference/method/MongoDBCollection-createSearchIndexes
6870
/reference/method/MongoDBCollection-deleteMany
6971
/reference/method/MongoDBCollection-deleteOne
7072
/reference/method/MongoDBCollection-distinct
7173
/reference/method/MongoDBCollection-drop
7274
/reference/method/MongoDBCollection-dropIndex
7375
/reference/method/MongoDBCollection-dropIndexes
76+
/reference/method/MongoDBCollection-dropSearchIndex
7477
/reference/method/MongoDBCollection-estimatedDocumentCount
7578
/reference/method/MongoDBCollection-explain
7679
/reference/method/MongoDBCollection-find
@@ -89,10 +92,12 @@ Methods
8992
/reference/method/MongoDBCollection-insertMany
9093
/reference/method/MongoDBCollection-insertOne
9194
/reference/method/MongoDBCollection-listIndexes
95+
/reference/method/MongoDBCollection-listSearchIndexes
9296
/reference/method/MongoDBCollection-mapReduce
9397
/reference/method/MongoDBCollection-rename
9498
/reference/method/MongoDBCollection-replaceOne
9599
/reference/method/MongoDBCollection-updateMany
96100
/reference/method/MongoDBCollection-updateOne
101+
/reference/method/MongoDBCollection-updateSearchIndex
97102
/reference/method/MongoDBCollection-watch
98103
/reference/method/MongoDBCollection-withOptions

‎docs/reference/method/MongoDBCollection-createSearchIndex.txt

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
========================================
2+
MongoDB\\Collection::createSearchIndex()
3+
========================================
4+
5+
.. versionadded:: 1.17
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Definition
16+
----------
17+
18+
.. phpmethod:: MongoDB\\Collection::createSearchIndex()
19+
20+
Create an Atlas Search index for the collection.
21+
22+
.. code-block:: php
23+
24+
function createSearchIndex(array|object $definition, array $options = []): string
25+
26+
This method has the following parameters:
27+
28+
.. include:: /includes/apiargs/MongoDBCollection-method-createSearchIndex-param.rst
29+
30+
The ``$options`` parameter supports the following options:
31+
32+
.. include:: /includes/apiargs/MongoDBCollection-method-createSearchIndex-option.rst
33+
34+
.. include:: /includes/extracts/note-atlas-search-requirement.rst
35+
.. include:: /includes/extracts/note-atlas-search-async.rst
36+
37+
Return Values
38+
-------------
39+
40+
The name of the created Atlas Search index as a string.
41+
42+
Errors/Exceptions
43+
-----------------
44+
45+
.. include:: /includes/extracts/error-unsupportedexception.rst
46+
.. include:: /includes/extracts/error-invalidargumentexception.rst
47+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
48+
49+
Examples
50+
--------
51+
52+
Create an Index with Dynamic Mappings
53+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
54+
55+
The following example creates an Atlas Search index using
56+
`dynamic mappings <https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/#dynamic-mappings>`__
57+
to index all document fields containing
58+
`supported data types <https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/#std-label-bson-data-chart>`__.
59+
60+
.. code-block:: php
61+
62+
<?php
63+
64+
$collection = (new MongoDB\Client)->selectCollection('test', 'articles');
65+
66+
$indexName = $collection->createSearchIndex(
67+
['mappings' => ['dynamic' => true]],
68+
['name' => 'test-search-index']
69+
);
70+
71+
var_dump($indexName);
72+
73+
The output would then resemble:
74+
75+
.. code-block:: none
76+
77+
string(17) "test-search-index"
78+
79+
See Also
80+
--------
81+
82+
- :phpmethod:`MongoDB\\Collection::createSearchIndexes()`
83+
- :phpmethod:`MongoDB\\Collection::dropSearchIndex()`
84+
- :phpmethod:`MongoDB\\Collection::listSearchIndexes()`
85+
- :phpmethod:`MongoDB\\Collection::updateSearchIndex()`
86+
- :manual:`createSearchIndexes </reference/command/createSearchIndexes>` command
87+
reference in the MongoDB manual
88+
- `Atlas Search <https://www.mongodb.com/docs/atlas/atlas-search/>`__ documentation in the MongoDB Manual

0 commit comments

Comments
 (0)