PHPLIB-1143: Document Atlas Search index helpers and fix aggregate "collation" docs (#1189)

jmikola · web-flow · commit 53ccbc41f154 · 2023-11-09T09:31:52.000-05:00
* PHPLIB-1143: Docs for Atlas Search index helpers * PHPLIB-1306: Add missing docs for aggregate "collation" option
diff --git a/docs/includes/apiargs-MongoDBCollection-method-aggregate-option.yaml b/docs/includes/apiargs-MongoDBCollection-method-aggregate-option.yaml
@@ -10,6 +10,10 @@ source:
   file: apiargs-aggregate-option.yaml
   ref: bypassDocumentValidation
 ---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
+---
 source:
   file: apiargs-common-option.yaml
   ref: comment
diff --git a/docs/includes/apiargs-MongoDBCollection-method-createSearchIndex-option.yaml b/docs/includes/apiargs-MongoDBCollection-method-createSearchIndex-option.yaml
@@ -0,0 +1,17 @@
+arg_name: option
+name: name
+type: string
+description: |
+  Name of the search index to create.
+
+  You cannot create multiple indexes with the same name on a single collection.
+
+  If you do not specify a name, the index is named "default".
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+...
diff --git a/docs/includes/apiargs-MongoDBCollection-method-createSearchIndex-param.yaml b/docs/includes/apiargs-MongoDBCollection-method-createSearchIndex-param.yaml
@@ -0,0 +1,14 @@
+arg_name: param
+name: $definition
+type: array|object
+description: |
+  Document describing the index to create. For details on definition syntax, see 
+  :manual:`Search Index Definition Syntax </reference/command/createSearchIndexes/#search-index-definition-syntax>`.
+interface: phpmethod
+operation: ~
+optional: false
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...
diff --git a/docs/includes/apiargs-MongoDBCollection-method-createSearchIndexes-option.yaml b/docs/includes/apiargs-MongoDBCollection-method-createSearchIndexes-option.yaml
@@ -0,0 +1,4 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+...
diff --git a/docs/includes/apiargs-MongoDBCollection-method-createSearchIndexes-param.yaml b/docs/includes/apiargs-MongoDBCollection-method-createSearchIndexes-param.yaml
@@ -0,0 +1,21 @@
+arg_name: param
+name: $indexes
+type: array
+description: |
+  Array of documents describing the indexes to create.
+
+  A required ``definition`` document field describes the index to create. For
+  details on definition syntax, see 
+  :manual:`Search Index Definition Syntax </reference/command/createSearchIndexes/#search-index-definition-syntax>`.
+
+  An optional ``name`` string field specifies the name of the search index to
+  create. You cannot create multiple indexes with the same name on a single
+  collection. If you do not specify a name, the index is named "default".
+interface: phpmethod
+operation: ~
+optional: false
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...
diff --git a/docs/includes/apiargs-MongoDBCollection-method-dropSearchIndex-option.yaml b/docs/includes/apiargs-MongoDBCollection-method-dropSearchIndex-option.yaml
@@ -0,0 +1,4 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+...
diff --git a/docs/includes/apiargs-MongoDBCollection-method-dropSearchIndex-param.yaml b/docs/includes/apiargs-MongoDBCollection-method-dropSearchIndex-param.yaml
@@ -0,0 +1,13 @@
+arg_name: param
+name: $name
+type: string
+description: |
+  Name of the index to drop.
+interface: phpmethod
+operation: ~
+optional: false
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...
diff --git a/docs/includes/apiargs-MongoDBCollection-method-listSearchIndexes-option.yaml b/docs/includes/apiargs-MongoDBCollection-method-listSearchIndexes-option.yaml
@@ -0,0 +1,44 @@
+source:
+  file: apiargs-aggregate-option.yaml
+  ref: batchSize
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: collation
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+---
+arg_name: option
+name: name
+type: string
+description: |
+  Name of the index to return information about.
+
+  If name is not specified, information for all indexes on the collection will
+  be returned.
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: maxTimeMS
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: readConcern
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: readPreference
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: session
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: typeMap
+...
diff --git a/docs/includes/apiargs-MongoDBCollection-method-listSearchIndexes-param.yaml b/docs/includes/apiargs-MongoDBCollection-method-listSearchIndexes-param.yaml
@@ -0,0 +1,4 @@
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...
diff --git a/docs/includes/apiargs-MongoDBCollection-method-updateSearchIndex-option.yaml b/docs/includes/apiargs-MongoDBCollection-method-updateSearchIndex-option.yaml
@@ -0,0 +1,4 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+...
diff --git a/docs/includes/apiargs-MongoDBCollection-method-updateSearchIndex-param.yaml b/docs/includes/apiargs-MongoDBCollection-method-updateSearchIndex-param.yaml
@@ -0,0 +1,25 @@
+arg_name: param
+name: $name
+type: string
+description: |
+  Name of the index to update.
+interface: phpmethod
+operation: ~
+optional: false
+---
+arg_name: param
+name: $definition
+type: array|object
+description: |
+  Document describing the updated search index definition. The specified
+  definition replaces the prior definition in the search index. For details on
+  definition syntax, see 
+  :manual:`Search Index Definition Syntax </reference/command/createSearchIndexes/#search-index-definition-syntax>`.
+interface: phpmethod
+operation: ~
+optional: false
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...
diff --git a/docs/includes/apiargs-MongoDBCollection-method-watch-option.yaml b/docs/includes/apiargs-MongoDBCollection-method-watch-option.yaml
@@ -4,7 +4,7 @@ source:
   ref: batchSize
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
 source:
diff --git a/docs/includes/apiargs-MongoDBDatabase-method-aggregate-option.yaml b/docs/includes/apiargs-MongoDBDatabase-method-aggregate-option.yaml
@@ -10,6 +10,10 @@ source:
   file: apiargs-aggregate-option.yaml
   ref: bypassDocumentValidation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: collation
+---
 source:
   file: apiargs-common-option.yaml
   ref: comment
diff --git a/docs/includes/extracts-note.yaml b/docs/includes/extracts-note.yaml
@@ -9,4 +9,24 @@ content: |
   <manual/en/book.bson.php>` in the driver (e.g. use
   :php:`MongoDB\\BSON\\ObjectId <class.mongodb-bson-objectid>` to match an
   :manual:`ObjectId </reference/object-id/>`).
+---
+ref: note-atlas-search-requirement
+content: |
+  .. note::
+
+     This command can only be run on a deployment hosted on
+     :manual:`MongoDB Atlas </atlas>` and requires an Atlas cluster tier of at
+     least M10. A
+     `Local Atlas Deployment <https://www.mongodb.com/docs/atlas/cli/stable/atlas-cli-deploy-local/#use-atlas-search-with-a-local-atlas-deployment>`__
+     can also be used for development.
+---
+ref: note-atlas-search-async
+content: |
+   .. note::
+
+      Atlas Search indexes are managed asynchronously. After creating or
+      updating an index, you can periodically execute
+      :phpmethod:`MongoDB\\Collection::listSearchIndexes()` and check the
+      ``queryable`` :manual:`output field  </reference/operator/aggregation/listSearchIndexes/#output>`
+      to determine whether it is ready to be used.
 ...
diff --git a/docs/reference/class/MongoDBCollection.txt b/docs/reference/class/MongoDBCollection.txt
@@ -65,12 +65,15 @@ Methods
    /reference/method/MongoDBCollection-countDocuments
    /reference/method/MongoDBCollection-createIndex
    /reference/method/MongoDBCollection-createIndexes
+   /reference/method/MongoDBCollection-createSearchIndex
+   /reference/method/MongoDBCollection-createSearchIndexes
    /reference/method/MongoDBCollection-deleteMany
    /reference/method/MongoDBCollection-deleteOne
    /reference/method/MongoDBCollection-distinct
    /reference/method/MongoDBCollection-drop
    /reference/method/MongoDBCollection-dropIndex
    /reference/method/MongoDBCollection-dropIndexes
+   /reference/method/MongoDBCollection-dropSearchIndex
    /reference/method/MongoDBCollection-estimatedDocumentCount
    /reference/method/MongoDBCollection-explain
    /reference/method/MongoDBCollection-find
@@ -89,10 +92,12 @@ Methods
    /reference/method/MongoDBCollection-insertMany
    /reference/method/MongoDBCollection-insertOne
    /reference/method/MongoDBCollection-listIndexes
+   /reference/method/MongoDBCollection-listSearchIndexes
    /reference/method/MongoDBCollection-mapReduce
    /reference/method/MongoDBCollection-rename
    /reference/method/MongoDBCollection-replaceOne
    /reference/method/MongoDBCollection-updateMany
    /reference/method/MongoDBCollection-updateOne
+   /reference/method/MongoDBCollection-updateSearchIndex
    /reference/method/MongoDBCollection-watch
    /reference/method/MongoDBCollection-withOptions
diff --git a/docs/reference/method/MongoDBCollection-createSearchIndex.txt b/docs/reference/method/MongoDBCollection-createSearchIndex.txt
@@ -0,0 +1,88 @@
+========================================
+MongoDB\\Collection::createSearchIndex()
+========================================
+
+.. versionadded:: 1.17
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\Collection::createSearchIndex()
+
+   Create an Atlas Search index for the collection.
+
+   .. code-block:: php
+
+      function createSearchIndex(array|object $definition, array $options = []): string
+
+   This method has the following parameters:
+
+   .. include:: /includes/apiargs/MongoDBCollection-method-createSearchIndex-param.rst
+
+   The ``$options`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBCollection-method-createSearchIndex-option.rst
+
+   .. include:: /includes/extracts/note-atlas-search-requirement.rst
+   .. include:: /includes/extracts/note-atlas-search-async.rst
+
+Return Values
+-------------
+
+The name of the created Atlas Search index as a string.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-unsupportedexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
+Examples
+--------
+
+Create an Index with Dynamic Mappings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following example creates an Atlas Search index using
+`dynamic mappings <https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/#dynamic-mappings>`__
+to index all document fields containing
+`supported data types <https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/#std-label-bson-data-chart>`__.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->selectCollection('test', 'articles');
+
+   $indexName = $collection->createSearchIndex(
+      ['mappings' => ['dynamic' => true]],
+      ['name' => 'test-search-index']
+   );
+
+   var_dump($indexName);
+
+The output would then resemble:
+
+.. code-block:: none
+
+   string(17) "test-search-index"
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\Collection::createSearchIndexes()`
+- :phpmethod:`MongoDB\\Collection::dropSearchIndex()`
+- :phpmethod:`MongoDB\\Collection::listSearchIndexes()`
+- :phpmethod:`MongoDB\\Collection::updateSearchIndex()`
+- :manual:`createSearchIndexes </reference/command/createSearchIndexes>` command
+  reference in the MongoDB manual
+- `Atlas Search <https://www.mongodb.com/docs/atlas/atlas-search/>`__ documentation in the MongoDB Manual
diff --git a/docs/reference/method/MongoDBCollection-createSearchIndexes.txt b/docs/reference/method/MongoDBCollection-createSearchIndexes.txt
diff --git a/docs/reference/method/MongoDBCollection-dropSearchIndex.txt b/docs/reference/method/MongoDBCollection-dropSearchIndex.txt
diff --git a/docs/reference/method/MongoDBCollection-listSearchIndexes.txt b/docs/reference/method/MongoDBCollection-listSearchIndexes.txt
diff --git a/docs/reference/method/MongoDBCollection-updateSearchIndex.txt b/docs/reference/method/MongoDBCollection-updateSearchIndex.txt

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +source:
 +  file: apiargs-common-option.yaml
 +  ref: comment
 +...