From c7c3a2f31748e0632c8b7a8115834ef78c365216 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 10:40:56 -0500 Subject: [PATCH 01/19] DOCSP-45770: atlas search queries --- snooty.toml | 51 ++-- source/aggregation.txt | 73 ++--- source/aggregation/atlas-search.txt | 264 ++++++++++++++++++ source/aggregation/vector-search.txt | 216 ++++++++++++++ .../{ => aggregation}/aggregation.php | 0 source/includes/aggregation/atlas-search.php | 60 ++++ source/includes/aggregation/vector-search.php | 49 ++++ 7 files changed, 656 insertions(+), 57 deletions(-) create mode 100644 source/aggregation/atlas-search.txt create mode 100644 source/aggregation/vector-search.txt rename source/includes/{ => aggregation}/aggregation.php (100%) create mode 100644 source/includes/aggregation/atlas-search.php create mode 100644 source/includes/aggregation/vector-search.php diff --git a/snooty.toml b/snooty.toml index c0d688f0..3600f791 100644 --- a/snooty.toml +++ b/snooty.toml @@ -2,34 +2,35 @@ name = "php-library" title = "PHP Library Manual" intersphinx = [ - "https://www.mongodb.com/docs/manual/objects.inv", - "https://www.mongodb.com/docs/drivers/objects.inv", - "https://www.mongodb.com/docs/atlas/objects.inv", + "https://www.mongodb.com/docs/manual/objects.inv", + "https://www.mongodb.com/docs/drivers/objects.inv", + "https://www.mongodb.com/docs/atlas/objects.inv", ] toc_landing_pages = [ - "/reference/class/MongoDBClient", - "/reference/class/MongoDBCollection", - "/reference/class/MongoDBDatabase", - "/reference/class/MongoDBGridFSBucket", - "/reference/class/MongoDBBulkWriteResult", - "/reference/class/MongoDBDeleteResult", - "/reference/class/MongoDBInsertManyResult", - "/reference/class/MongoDBUpdateResult", - "/reference/class/MongoDBChangeStream", - "/reference/class/MongoDBMapReduceResult", - "/reference/class/MongoDBModelCollectionInfo", - "/reference/class/MongoDBModelDatabaseInfo", - "/reference/class/MongoDBModelIndexInfo", - "/get-started", - "/connect", - "/read", - "/databases-collections", - "/write", - "/indexes", - "/security", - "/data-formats", - "/upgrade", + "/reference/class/MongoDBClient", + "/reference/class/MongoDBCollection", + "/reference/class/MongoDBDatabase", + "/reference/class/MongoDBGridFSBucket", + "/reference/class/MongoDBBulkWriteResult", + "/reference/class/MongoDBDeleteResult", + "/reference/class/MongoDBInsertManyResult", + "/reference/class/MongoDBUpdateResult", + "/reference/class/MongoDBChangeStream", + "/reference/class/MongoDBMapReduceResult", + "/reference/class/MongoDBModelCollectionInfo", + "/reference/class/MongoDBModelDatabaseInfo", + "/reference/class/MongoDBModelIndexInfo", + "/get-started", + "/connect", + "/read", + "/databases-collections", + "/write", + "/indexes", + "/security", + "/data-formats", + "/upgrade", + "/aggregation" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/aggregation.txt b/source/aggregation.txt index 96e7f63e..6c34ddca 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -18,12 +18,12 @@ Transform Your Data with Aggregation :depth: 2 :class: singlecol -.. TODO: - .. toctree:: - :titlesonly: - :maxdepth: 1 - - /aggregation/aggregation-tutorials +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Atlas Search + Atlas Vector Search Overview -------- @@ -78,9 +78,9 @@ Consider the following limitations when performing aggregation operations: .. important:: $graphLookup Exception - The :manual:`$graphLookup - ` stage has a strict - memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. + The :manual:`$graphLookup + ` stage has a strict + memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. .. _php-aggregation-example: @@ -110,21 +110,21 @@ of New York. To do so, it uses an aggregation pipeline that contains the followi .. io-code-block:: :copyable: - .. input:: /includes/aggregation.php - :start-after: start-match-group - :end-before: end-match-group - :language: php - :dedent: + .. input:: /includes/aggregation/aggregation.php + :start-after: start-match-group + :end-before: end-match-group + :language: php + :dedent: .. output:: - :visible: false + :visible: false - {"_id":"Brooklyn","count":173} - {"_id":"Queens","count":204} - {"_id":"Bronx","count":71} - {"_id":"Staten Island","count":20} - {"_id":"Missing","count":2} - {"_id":"Manhattan","count":221} + {"_id":"Brooklyn","count":173} + {"_id":"Queens","count":204} + {"_id":"Bronx","count":71} + {"_id":"Staten Island","count":20} + {"_id":"Missing","count":2} + {"_id":"Manhattan","count":221} Explain an Aggregation ~~~~~~~~~~~~~~~~~~~~~~ @@ -146,20 +146,20 @@ from the preceding :ref:`php-aggregation-example`: .. io-code-block:: :copyable: - .. input:: /includes/aggregation.php - :start-after: start-explain - :end-before: end-explain - :language: php - :dedent: + .. input:: /includes/aggregation/aggregation.php + :start-after: start-explain + :end-before: end-explain + :language: php + :dedent: .. output:: - :visible: false + :visible: false - {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", - "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", - "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, - "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ - ... } + {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", + "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", + "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, + "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ + ... } Additional Information ---------------------- @@ -188,6 +188,15 @@ pages in the {+mdb-server+} manual: :manual:`Explain Output ` and :manual:`Query Plans `. +Atlas Search and Vector Search +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can perform full-text searches by using the Atlas Search feature. To +learn more, see the :ref:`php-atlas-search` guide. + +You can perform similarity searches on vector embeddings by using the +Atlas Vector Search feature. To learn more, see the :ref:`php-vector-search` guide. + .. TODO: Aggregation Tutorials ~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt new file mode 100644 index 00000000..b2768376 --- /dev/null +++ b/source/aggregation/atlas-search.txt @@ -0,0 +1,264 @@ +.. _php-atlas-search: + +============ +Atlas Search +============ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, semantic, text + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to perform searches on your documents +by using the Atlas Search feature. The {+library-short+} allows you to +perform Atlas Search queries by using the :ref:`Aggregation Builder API +`. This guide provides examples of how to use the +{+library-short+} to perform searches. + +.. note:: Deployment Compatibility + + You can use the Atlas Search feature only when + you connect to MongoDB Atlas clusters. This feature is not + available for self-managed deployments. + +To learn more about Atlas Search, see the :atlas:`Overview +` in the +Atlas documentation. The Atlas Search implementation for the +{+library-short+} internally uses the ``$search`` aggregation operator +to perform queries. To learn more about this operator, see the +:atlas:`$search ` reference in +the Atlas documentation. + +.. note:: + + You might not be able to use the methods described in + this guide for every type of Atlas Search query. For more complex use + cases, you can follow the standard way to create aggregation + pipelines in the {+library-short+}. To learn more, see the + :ref:`php-aggregation` guide. + + To perform searches on vector embeddings in MongoDB, you can use the + Atlas Vector Search API. To learn about this feature, see + the :ref:`php-vector-search` guide. + +Atlas Search Index +~~~~~~~~~~~~~~~~~~ + +Before you can perform Atlas Search queries, you must create an Atlas +Search index on your collection. To learn more about creating this index +type, see the :ref:`php-atlas-search-index` guide. + +Search Aggregation Stage +------------------------ + +Import the following classes into your application to perform Atlas +Search queries by using the Aggregation Builder: + +.. code-block:: php + + use MongoDB\Builder\Pipeline; + use MongoDB\Builder\Search; + use MongoDB\Builder\Stage; + +To create a ``$search`` stage in your aggregation pipeline, you must +perform the following actions: + +1. Create a ``Pipeline`` class instance to create the pipeline + +#. Within the ``Pipeline`` instance, call the ``Stage::search()`` method + to create the Atlas Search stage + +#. Within the body of the ``search()`` method, use methods from the + ``Search`` builder class to construct your Search query criteria + +The following code demonstrates the template for constructing basic Atlas Search +queries: + +.. code-block:: php + + $pipeline = new Pipeline( + Stage::search( + // Atlas Search query specifications + // Search::compound(...) + ), + ); + +Atlas Search Query Examples +--------------------------- + +In this section, you can learn how to perform different types of Atlas +Search queries by using the Aggregation Builder. The examples in this +section use sample data from the ``sample_restaurants.restaurants`` +collection. + +Compound Query with Filter +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the ``Search::compound()`` method to combine two or more operators +into a single query. This method takes named arguments for your clauses, +such as ``must`` and ``filter``. In each clause, use the +``Search::text()`` method to specify the strings to look for when +performing the full-text search. + +This example performs an Atlas Search query that has the following +specifications: + +- Includes a ``must`` clause to search the ``name`` field for the string + ``"kitchen"`` +- Includes a ``should`` clause to highly rank documents in which the + ``cuisine`` field includes ``"american"`` +- Includes a ``filter`` field to include only documents in which the + ``borough`` value is ``"Queens"`` in the results + +.. io-code-block:: + :copyable: true + + .. input:: /includes/aggregation/atlas-search.php + :language: php + :dedent: + :start-after: start-compound-search-query + :end-before: end-compound-search-query + + .. output:: + :language: json + :visible: false + + {"_id": ...,"borough":"Queens","cuisine":"American","name":"Suite Kitchen",...} + {"_id": ...,"borough":"Queens","cuisine":"American","name":"Silver Kitchen",...} + // Results truncated + +Autocomplete Query +~~~~~~~~~~~~~~~~~~ + +The {+library-short+} provides the ``Search::autocomplete()`` method to run +autocomplete searches on documents in your collections. + +To learn more about this type of Atlas Search query, see the +:atlas:`autocomplete ` reference in the +Atlas documentation. + +.. note:: + + Your Atlas Search index must be configured for autocomplete queries. + To learn more, see :atlas:`How to Index Fields for Autocompletion + ` in the Atlas + documentation. + +The following code performs an Atlas Search autocomplete query for the +string ``"Lucy"`` on the ``name`` field: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/aggregation/atlas-search.php + :language: php + :dedent: + :start-after: start-autocomplete-search-query + :end-before: end-autocomplete-search-query + + .. output:: + :language: json + :visible: false + + {"name":"Lucy'S Asian Kitchen"} + {"name":"Lucy'S Cantina Royale"} + {"name":"Lucy'S Vietnamese Kitchen"} + // Results Truncated + +You can also pass the following optional parameters to the ``autocomplete()`` +method to customize the query: + +.. list-table:: + :header-rows: 1 + + * - Optional Parameter + - Description + - Default Value + + * - ``fuzzy`` + - Enables fuzzy search and fuzzy search options + - ``false`` + + * - ``tokenOrder`` + - Specifies order in which to search for tokens + - ``'any'`` + +To learn more about these parameters, see the :atlas:`Options +` section of the +``autocomplete`` operator reference in the Atlas documentation. + +Search Options +~~~~~~~~~~~~~~ + +You can use the ``search()`` method to perform many types of Atlas +Search queries. Depending on your desired query, you can pass the +following optional parameters to ``search()``: + +.. list-table:: + :header-rows: 1 + + * - Optional Parameter + - Type + - Description + + * - ``index`` + - ``string`` + - Provides the name of the Atlas Search index to use + + * - ``highlight`` + - ``array`` + - Specifies highlighting options for displaying search terms in their + original context + + * - ``concurrent`` + - ``bool`` + - Parallelizes search query across segments on dedicated search nodes + + * - ``count`` + - ``string`` + - Specifies the count options for retrieving a count of the results + + * - ``searchAfter`` + - ``string`` + - Specifies a reference point for returning documents starting + immediately following that point + + * - ``searchBefore`` + - ``string`` + - Specifies a reference point for returning documents starting + immediately preceding that point + + * - ``scoreDetails`` + - ``bool`` + - Specifies whether to retrieve a detailed breakdown of the score + for results + + * - ``sort`` + - ``array`` + - Specifies the fields on which to sort the results + + * - ``returnStoredSource`` + - ``bool`` + - Specifies whether to perform a full document lookup on the + backend database or return only stored source fields directly + from Atlas Search + + * - ``tracking`` + - ``array`` + - Specifies the tracking option to retrieve analytics information + on the search terms + +To learn more about these parameters, see the :atlas:`Fields +` section of the +``$search`` operator reference in the Atlas documentation. diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt new file mode 100644 index 00000000..fe2044f8 --- /dev/null +++ b/source/aggregation/vector-search.txt @@ -0,0 +1,216 @@ +.. _php-vector-search: + +=================== +Atlas Vector Search +=================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, semantic, text, embeddings + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to perform searches on your documents +by using the Atlas Vector Search feature. The {+library-short+} allows you to +perform Atlas Vector Search queries by using the :ref:`Aggregation Builder API +`. This guide provides examples of how to use the +{+library-short+} to perform Atlas Vector Search queries. + +.. note:: Deployment Compatibility + + You can use the Atlas Search feature only when + you connect to MongoDB Atlas clusters. This feature is not + available for self-managed deployments. + +To learn more about Atlas Vector Search, see the :atlas:`Overview +` in the +Atlas documentation. The Atlas Vector Search implementation for the +{+library-short+} internally uses the ``$vectorSearch`` aggregation operator +to perform queries. To learn more about this operator, see the +:atlas:`$vectorSearch +` reference in the +Atlas documentation. + +.. note:: + + You might not be able to use the methods described in + this guide for every type of Atlas Search query. For more complex use + cases, you can follow the standard way to create aggregation + pipelines in the {+library-short+}. To learn more, see the + :ref:`php-aggregation` guide. + + To perform advanced full-text search on your documents, you can use the + Atlas Search API. To learn about this feature, see the + :ref:`php-atlas-search` guide. + +Atlas Vector Search Index +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before you can perform Atlas Vector Search queries, you must create an +Atlas Vector Search index on your collection. To learn more about +creating this index type, see the :ref:`php-atlas-search-index` guide. + +Vector Search Aggregation Stage +------------------------------- + +Import the following classes into your application to perform Atlas +Search queries by using the Aggregation Builder: + +.. code-block:: php + + use MongoDB\Builder\Pipeline; + use MongoDB\Builder\Query; + use MongoDB\Builder\Stage; + +To create a ``$search`` stage in your aggregation pipeline, you must +perform the following actions: + +1. Create a ``Pipeline`` class instance to create the pipeline + +#. Within the ``Pipeline`` instance, call the ``Stage::vectorSearch()`` method + to create the Atlas Vector Search stage + +#. Within the body of the ``vectorSearch()`` method, specify the + criteria for your vector query + +The following code demonstrates the template for constructing basic Atlas Search +queries: + +.. code-block:: php + + $pipeline = new Pipeline( + Stage::vectorSearch( + // Atlas Vector Search query specifications + // index: '', + // path: '', + // ... + ), + ); + +You must pass the following parameters to the ``vectorSearch()`` method: + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Type + - Description + + * - ``index`` + - ``string`` + - Name of the vector search index + + * - ``path`` + - ``array`` or ``string`` + - Field that stores vector embeddings + + * - ``queryVector`` + - ``array`` + - Vector representation of your query + + * - ``limit`` + - ``int`` + - Number of results to return + +Atlas Search Query Examples +--------------------------- + +In this section, you can learn how to perform Atlas Vector +Search queries by using the Aggregation Builder. The examples in this +section use sample data from the ``sample_mflix.embedded_movies`` +collection. + +Basic Vector Search Query +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code performs an Atlas Vector Search query on the +``plot_embedding`` vector field: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/aggregation/vector-search.php + :language: php + :dedent: + :start-after: start-basic-query + :end-before: end-basic-query + + .. output:: + :language: json + :visible: false + + {"_id": ...,"title":"About Time",...} + {"_id": ...,"title":"Tomorrowland",...} + {"_id": ...,"title":"Timecop",...} + // Results truncated + +Vector Search Score +~~~~~~~~~~~~~~~~~~~ + +The following code performs the same query as in the preceding example, +but outputs only the ``title`` field and ``vectorSearchScore`` meta +field, which describes how well the document matches the query vector: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/aggregation/vector-search.php + :language: php + :dedent: + :start-after: start-score-query + :end-before: end-score-query + + .. output:: + :language: json + :visible: false + + {"title":"About Time","score":0.7843604683876038} + {"title":"Timecop","score":0.7771612405776978} + {"title":"Tomorrowland","score":0.7669923901557922} + // Results truncated + +Vector Search Options +~~~~~~~~~~~~~~~~~~~~~ + +You can use the ``vectorSearch()`` method to perform many types of Atlas +Vector Search queries. Depending on your desired query, you can pass the +following optional parameters to ``vectorSearch()``: + +.. list-table:: + :header-rows: 1 + + * - Optional Parameter + - Type + - Description + - Default Value + + * - ``exact`` + - ``bool`` + - Specifies whether to run an Exact Nearest Neighbor (``true``) or + Approximate Nearest Neighbor (``false``) search + - ``false`` + + * - ``filter`` + - ``QueryInterface`` or ``array`` + - Specifies a pre-filter for documents to search on + - no filtering + + * - ``numCandidates`` + - ``int`` or ``null`` + - Specifies the number of nearest neighbors to use during the + search + - ``null`` + +To learn more about these parameters, see the :atlas:`Fields +` section of the +``$vectorSearch`` operator reference in the Atlas documentation. diff --git a/source/includes/aggregation.php b/source/includes/aggregation/aggregation.php similarity index 100% rename from source/includes/aggregation.php rename to source/includes/aggregation/aggregation.php diff --git a/source/includes/aggregation/atlas-search.php b/source/includes/aggregation/atlas-search.php new file mode 100644 index 00000000..4ecbed27 --- /dev/null +++ b/source/includes/aggregation/atlas-search.php @@ -0,0 +1,60 @@ +sample_restaurants->restaurants; + +// start-compound-search-query +$pipeline = new Pipeline( + Stage::search( + Search::compound( + must: [ + Search::text( + query: 'kitchen', + path: 'name', + ), + ], + should: [ + Search::text( + query: 'american', + path: 'cuisine', + ), + ], + filter: [ + Search::text( + query: 'Queens', + path: 'borough', + ), + ], + ), + ), +); + +$cursor = $collection->aggregate($pipeline); + +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-compound-search-query + +// start-autocomplete-search-query +$pipeline = new Pipeline( + Stage::search( + Search::autocomplete( + query: 'Lucy', + path: 'name', + ), + ), + Stage::limit(10), + Stage::project(_id: 0, title: 1), +); + +$cursor = $collection->aggregate($pipeline); + +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-autocomplete-search-query \ No newline at end of file diff --git a/source/includes/aggregation/vector-search.php b/source/includes/aggregation/vector-search.php new file mode 100644 index 00000000..ce7833ab --- /dev/null +++ b/source/includes/aggregation/vector-search.php @@ -0,0 +1,49 @@ +sample_mflix->embedded_movies; + +// start-basic-query +$pipeline = new Pipeline( + Stage::vectorSearch( + index: 'vector_index', + path: 'plot_embedding', + queryVector: [-0.0016261312, -0.028070757, -0.011342932], + numCandidates: 150, + limit: 10, + ) +); + +$cursor = $collection->aggregate($pipeline); + +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-basic-query + +// start-score-query +$pipeline = new Pipeline( + Stage::vectorSearch( + index: 'vector_index', + path: 'plot_embedding', + queryVector: [-0.0016261312, -0.028070757, -0.011342932], + numCandidates: 150, + limit: 10, + ), + Stage::project( + _id: 0, + title: 1, + score: ['$meta' => 'vectorSearchScore'], + ), +); + +$cursor = $collection->aggregate($pipeline); + +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-score-query \ No newline at end of file From 4610cf21356afd93e77314c99e83e1b179085af6 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 10:44:19 -0500 Subject: [PATCH 02/19] fix indentation --- snooty.toml | 51 +++++++++--------- source/aggregation.txt | 114 ++++++++++++++++++++--------------------- 2 files changed, 82 insertions(+), 83 deletions(-) diff --git a/snooty.toml b/snooty.toml index 3600f791..c0d688f0 100644 --- a/snooty.toml +++ b/snooty.toml @@ -2,35 +2,34 @@ name = "php-library" title = "PHP Library Manual" intersphinx = [ - "https://www.mongodb.com/docs/manual/objects.inv", - "https://www.mongodb.com/docs/drivers/objects.inv", - "https://www.mongodb.com/docs/atlas/objects.inv", + "https://www.mongodb.com/docs/manual/objects.inv", + "https://www.mongodb.com/docs/drivers/objects.inv", + "https://www.mongodb.com/docs/atlas/objects.inv", ] toc_landing_pages = [ - "/reference/class/MongoDBClient", - "/reference/class/MongoDBCollection", - "/reference/class/MongoDBDatabase", - "/reference/class/MongoDBGridFSBucket", - "/reference/class/MongoDBBulkWriteResult", - "/reference/class/MongoDBDeleteResult", - "/reference/class/MongoDBInsertManyResult", - "/reference/class/MongoDBUpdateResult", - "/reference/class/MongoDBChangeStream", - "/reference/class/MongoDBMapReduceResult", - "/reference/class/MongoDBModelCollectionInfo", - "/reference/class/MongoDBModelDatabaseInfo", - "/reference/class/MongoDBModelIndexInfo", - "/get-started", - "/connect", - "/read", - "/databases-collections", - "/write", - "/indexes", - "/security", - "/data-formats", - "/upgrade", - "/aggregation" + "/reference/class/MongoDBClient", + "/reference/class/MongoDBCollection", + "/reference/class/MongoDBDatabase", + "/reference/class/MongoDBGridFSBucket", + "/reference/class/MongoDBBulkWriteResult", + "/reference/class/MongoDBDeleteResult", + "/reference/class/MongoDBInsertManyResult", + "/reference/class/MongoDBUpdateResult", + "/reference/class/MongoDBChangeStream", + "/reference/class/MongoDBMapReduceResult", + "/reference/class/MongoDBModelCollectionInfo", + "/reference/class/MongoDBModelDatabaseInfo", + "/reference/class/MongoDBModelIndexInfo", + "/get-started", + "/connect", + "/read", + "/databases-collections", + "/write", + "/indexes", + "/security", + "/data-formats", + "/upgrade", ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/aggregation.txt b/source/aggregation.txt index 6c34ddca..98476fd5 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -5,23 +5,23 @@ Transform Your Data with Aggregation ==================================== .. facet:: - :name: genre - :values: reference + :name: genre + :values: reference .. meta:: - :keywords: code example, transform, computed, pipeline - :description: Learn how to use the PHP library to perform aggregation operations. + :keywords: code example, transform, computed, pipeline + :description: Learn how to use the PHP library to perform aggregation operations. .. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol + :local: + :backlinks: none + :depth: 2 + :class: singlecol .. toctree:: :titlesonly: :maxdepth: 1 - + Atlas Search Atlas Vector Search @@ -70,17 +70,17 @@ Limitations Consider the following limitations when performing aggregation operations: - Returned documents cannot violate the - :manual:`BSON document size limit ` - of 16 megabytes. + :manual:`BSON document size limit ` + of 16 megabytes. - Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this - limit by creating an options array that sets the ``allowDiskUse`` option to ``true`` - and passing the array to the ``MongoDB\Collection::aggregate()`` method. + limit by creating an options array that sets the ``allowDiskUse`` option to ``true`` + and passing the array to the ``MongoDB\Collection::aggregate()`` method. - .. important:: $graphLookup Exception + .. important:: $graphLookup Exception - The :manual:`$graphLookup - ` stage has a strict - memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. + The :manual:`$graphLookup + ` stage has a strict + memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. .. _php-aggregation-example: @@ -88,11 +88,11 @@ Aggregation Example ------------------- .. note:: - - The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` - database from the :atlas:`Atlas sample datasets `. To learn how to create a - free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas - ` guide. + + The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` + database from the :atlas:`Atlas sample datasets `. To learn how to create a + free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas + ` guide. To perform an aggregation, pass an array containing the pipeline stages to the ``MongoDB\Collection::aggregate()`` method. @@ -101,30 +101,30 @@ The following code example produces a count of the number of bakeries in each bo of New York. To do so, it uses an aggregation pipeline that contains the following stages: - :manual:`$match ` stage to filter for documents - in which the ``cuisine`` field contains the value ``'Bakery'`` + in which the ``cuisine`` field contains the value ``'Bakery'`` - :manual:`$group ` stage to group the matching - documents by the ``borough`` field, accumulating a count of documents for each distinct - value + documents by the ``borough`` field, accumulating a count of documents for each distinct + value .. io-code-block:: - :copyable: + :copyable: - .. input:: /includes/aggregation/aggregation.php - :start-after: start-match-group - :end-before: end-match-group - :language: php - :dedent: + .. input:: /includes/aggregation.php + :start-after: start-match-group + :end-before: end-match-group + :language: php + :dedent: - .. output:: - :visible: false + .. output:: + :visible: false - {"_id":"Brooklyn","count":173} - {"_id":"Queens","count":204} - {"_id":"Bronx","count":71} - {"_id":"Staten Island","count":20} - {"_id":"Missing","count":2} - {"_id":"Manhattan","count":221} + {"_id":"Brooklyn","count":173} + {"_id":"Queens","count":204} + {"_id":"Bronx","count":71} + {"_id":"Staten Island","count":20} + {"_id":"Missing","count":2} + {"_id":"Manhattan","count":221} Explain an Aggregation ~~~~~~~~~~~~~~~~~~~~~~ @@ -144,22 +144,22 @@ The following example instructs MongoDB to explain the aggregation operation from the preceding :ref:`php-aggregation-example`: .. io-code-block:: - :copyable: + :copyable: - .. input:: /includes/aggregation/aggregation.php - :start-after: start-explain - :end-before: end-explain - :language: php - :dedent: + .. input:: /includes/aggregation.php + :start-after: start-explain + :end-before: end-explain + :language: php + :dedent: - .. output:: - :visible: false + .. output:: + :visible: false - {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", - "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", - "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, - "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ - ... } + {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", + "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", + "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, + "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ + ... } Additional Information ---------------------- @@ -176,17 +176,17 @@ To learn more about the topics discussed in this guide, see the following pages in the {+mdb-server+} manual: - To view a full list of expression operators, see :manual:`Aggregation - Operators `. + Operators `. - To learn about assembling an aggregation pipeline and to view examples, see - :manual:`Aggregation Pipeline `. + :manual:`Aggregation Pipeline `. - To learn more about creating pipeline stages, see :manual:`Aggregation - Stages `. + Stages `. - To learn more about explaining MongoDB operations, see - :manual:`Explain Output ` and - :manual:`Query Plans `. + :manual:`Explain Output ` and + :manual:`Query Plans `. Atlas Search and Vector Search ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From ecbc949ae5bc3483436d5995e43e2ec16fa96b39 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 10:53:16 -0500 Subject: [PATCH 03/19] fix indentation --- snooty.toml | 51 ++++++++++--------- source/aggregation.txt | 112 ++++++++++++++++++++--------------------- 2 files changed, 82 insertions(+), 81 deletions(-) diff --git a/snooty.toml b/snooty.toml index c0d688f0..183e09ad 100644 --- a/snooty.toml +++ b/snooty.toml @@ -2,34 +2,35 @@ name = "php-library" title = "PHP Library Manual" intersphinx = [ - "https://www.mongodb.com/docs/manual/objects.inv", - "https://www.mongodb.com/docs/drivers/objects.inv", - "https://www.mongodb.com/docs/atlas/objects.inv", + "https://www.mongodb.com/docs/manual/objects.inv", + "https://www.mongodb.com/docs/drivers/objects.inv", + "https://www.mongodb.com/docs/atlas/objects.inv", ] toc_landing_pages = [ - "/reference/class/MongoDBClient", - "/reference/class/MongoDBCollection", - "/reference/class/MongoDBDatabase", - "/reference/class/MongoDBGridFSBucket", - "/reference/class/MongoDBBulkWriteResult", - "/reference/class/MongoDBDeleteResult", - "/reference/class/MongoDBInsertManyResult", - "/reference/class/MongoDBUpdateResult", - "/reference/class/MongoDBChangeStream", - "/reference/class/MongoDBMapReduceResult", - "/reference/class/MongoDBModelCollectionInfo", - "/reference/class/MongoDBModelDatabaseInfo", - "/reference/class/MongoDBModelIndexInfo", - "/get-started", - "/connect", - "/read", - "/databases-collections", - "/write", - "/indexes", - "/security", - "/data-formats", - "/upgrade", + "/reference/class/MongoDBClient", + "/reference/class/MongoDBCollection", + "/reference/class/MongoDBDatabase", + "/reference/class/MongoDBGridFSBucket", + "/reference/class/MongoDBBulkWriteResult", + "/reference/class/MongoDBDeleteResult", + "/reference/class/MongoDBInsertManyResult", + "/reference/class/MongoDBUpdateResult", + "/reference/class/MongoDBChangeStream", + "/reference/class/MongoDBMapReduceResult", + "/reference/class/MongoDBModelCollectionInfo", + "/reference/class/MongoDBModelDatabaseInfo", + "/reference/class/MongoDBModelIndexInfo", + "/get-started", + "/connect", + "/read", + "/databases-collections", + "/write", + "/indexes", + "/security", + "/data-formats", + "/upgrade", + "/aggregation", ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/aggregation.txt b/source/aggregation.txt index 98476fd5..d33c3e40 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -5,18 +5,18 @@ Transform Your Data with Aggregation ==================================== .. facet:: - :name: genre - :values: reference + :name: genre + :values: reference .. meta:: - :keywords: code example, transform, computed, pipeline - :description: Learn how to use the PHP library to perform aggregation operations. + :keywords: code example, transform, computed, pipeline + :description: Learn how to use the PHP library to perform aggregation operations. .. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol + :local: + :backlinks: none + :depth: 2 + :class: singlecol .. toctree:: :titlesonly: @@ -70,17 +70,17 @@ Limitations Consider the following limitations when performing aggregation operations: - Returned documents cannot violate the - :manual:`BSON document size limit ` - of 16 megabytes. + :manual:`BSON document size limit ` + of 16 megabytes. - Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this - limit by creating an options array that sets the ``allowDiskUse`` option to ``true`` - and passing the array to the ``MongoDB\Collection::aggregate()`` method. + limit by creating an options array that sets the ``allowDiskUse`` option to ``true`` + and passing the array to the ``MongoDB\Collection::aggregate()`` method. - .. important:: $graphLookup Exception + .. important:: $graphLookup Exception - The :manual:`$graphLookup - ` stage has a strict - memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. + The :manual:`$graphLookup + ` stage has a strict + memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. .. _php-aggregation-example: @@ -88,11 +88,11 @@ Aggregation Example ------------------- .. note:: - - The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` - database from the :atlas:`Atlas sample datasets `. To learn how to create a - free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas - ` guide. + + The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` + database from the :atlas:`Atlas sample datasets `. To learn how to create a + free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas + ` guide. To perform an aggregation, pass an array containing the pipeline stages to the ``MongoDB\Collection::aggregate()`` method. @@ -101,30 +101,30 @@ The following code example produces a count of the number of bakeries in each bo of New York. To do so, it uses an aggregation pipeline that contains the following stages: - :manual:`$match ` stage to filter for documents - in which the ``cuisine`` field contains the value ``'Bakery'`` + in which the ``cuisine`` field contains the value ``'Bakery'`` - :manual:`$group ` stage to group the matching - documents by the ``borough`` field, accumulating a count of documents for each distinct - value + documents by the ``borough`` field, accumulating a count of documents for each distinct + value .. io-code-block:: - :copyable: + :copyable: - .. input:: /includes/aggregation.php - :start-after: start-match-group - :end-before: end-match-group - :language: php - :dedent: + .. input:: /includes/aggregation/aggregation.php + :start-after: start-match-group + :end-before: end-match-group + :language: php + :dedent: - .. output:: - :visible: false + .. output:: + :visible: false - {"_id":"Brooklyn","count":173} - {"_id":"Queens","count":204} - {"_id":"Bronx","count":71} - {"_id":"Staten Island","count":20} - {"_id":"Missing","count":2} - {"_id":"Manhattan","count":221} + {"_id":"Brooklyn","count":173} + {"_id":"Queens","count":204} + {"_id":"Bronx","count":71} + {"_id":"Staten Island","count":20} + {"_id":"Missing","count":2} + {"_id":"Manhattan","count":221} Explain an Aggregation ~~~~~~~~~~~~~~~~~~~~~~ @@ -144,22 +144,22 @@ The following example instructs MongoDB to explain the aggregation operation from the preceding :ref:`php-aggregation-example`: .. io-code-block:: - :copyable: + :copyable: - .. input:: /includes/aggregation.php - :start-after: start-explain - :end-before: end-explain - :language: php - :dedent: + .. input:: /includes/aggregation/aggregation.php + :start-after: start-explain + :end-before: end-explain + :language: php + :dedent: - .. output:: - :visible: false + .. output:: + :visible: false - {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", - "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", - "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, - "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ - ... } + {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", + "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", + "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, + "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ + ... } Additional Information ---------------------- @@ -176,17 +176,17 @@ To learn more about the topics discussed in this guide, see the following pages in the {+mdb-server+} manual: - To view a full list of expression operators, see :manual:`Aggregation - Operators `. + Operators `. - To learn about assembling an aggregation pipeline and to view examples, see - :manual:`Aggregation Pipeline `. + :manual:`Aggregation Pipeline `. - To learn more about creating pipeline stages, see :manual:`Aggregation - Stages `. + Stages `. - To learn more about explaining MongoDB operations, see - :manual:`Explain Output ` and - :manual:`Query Plans `. + :manual:`Explain Output ` and + :manual:`Query Plans `. Atlas Search and Vector Search ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 02abea14f7859555f1b291af0ee663de4b9d9352 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 10:56:16 -0500 Subject: [PATCH 04/19] fix indentation --- snooty.toml | 51 ++++++++++++++++--------------- source/aggregation.txt | 68 +++++++++++++++++++++--------------------- 2 files changed, 59 insertions(+), 60 deletions(-) diff --git a/snooty.toml b/snooty.toml index 183e09ad..c0d688f0 100644 --- a/snooty.toml +++ b/snooty.toml @@ -2,35 +2,34 @@ name = "php-library" title = "PHP Library Manual" intersphinx = [ - "https://www.mongodb.com/docs/manual/objects.inv", - "https://www.mongodb.com/docs/drivers/objects.inv", - "https://www.mongodb.com/docs/atlas/objects.inv", + "https://www.mongodb.com/docs/manual/objects.inv", + "https://www.mongodb.com/docs/drivers/objects.inv", + "https://www.mongodb.com/docs/atlas/objects.inv", ] toc_landing_pages = [ - "/reference/class/MongoDBClient", - "/reference/class/MongoDBCollection", - "/reference/class/MongoDBDatabase", - "/reference/class/MongoDBGridFSBucket", - "/reference/class/MongoDBBulkWriteResult", - "/reference/class/MongoDBDeleteResult", - "/reference/class/MongoDBInsertManyResult", - "/reference/class/MongoDBUpdateResult", - "/reference/class/MongoDBChangeStream", - "/reference/class/MongoDBMapReduceResult", - "/reference/class/MongoDBModelCollectionInfo", - "/reference/class/MongoDBModelDatabaseInfo", - "/reference/class/MongoDBModelIndexInfo", - "/get-started", - "/connect", - "/read", - "/databases-collections", - "/write", - "/indexes", - "/security", - "/data-formats", - "/upgrade", - "/aggregation", + "/reference/class/MongoDBClient", + "/reference/class/MongoDBCollection", + "/reference/class/MongoDBDatabase", + "/reference/class/MongoDBGridFSBucket", + "/reference/class/MongoDBBulkWriteResult", + "/reference/class/MongoDBDeleteResult", + "/reference/class/MongoDBInsertManyResult", + "/reference/class/MongoDBUpdateResult", + "/reference/class/MongoDBChangeStream", + "/reference/class/MongoDBMapReduceResult", + "/reference/class/MongoDBModelCollectionInfo", + "/reference/class/MongoDBModelDatabaseInfo", + "/reference/class/MongoDBModelIndexInfo", + "/get-started", + "/connect", + "/read", + "/databases-collections", + "/write", + "/indexes", + "/security", + "/data-formats", + "/upgrade", ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/aggregation.txt b/source/aggregation.txt index d33c3e40..01519eeb 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -70,17 +70,17 @@ Limitations Consider the following limitations when performing aggregation operations: - Returned documents cannot violate the - :manual:`BSON document size limit ` - of 16 megabytes. + :manual:`BSON document size limit ` + of 16 megabytes. - Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this - limit by creating an options array that sets the ``allowDiskUse`` option to ``true`` - and passing the array to the ``MongoDB\Collection::aggregate()`` method. + limit by creating an options array that sets the ``allowDiskUse`` option to ``true`` + and passing the array to the ``MongoDB\Collection::aggregate()`` method. - .. important:: $graphLookup Exception - - The :manual:`$graphLookup - ` stage has a strict - memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. + .. important:: $graphLookup Exception + + The :manual:`$graphLookup + ` stage has a strict + memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. .. _php-aggregation-example: @@ -88,7 +88,7 @@ Aggregation Example ------------------- .. note:: - + The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` database from the :atlas:`Atlas sample datasets `. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas @@ -101,30 +101,30 @@ The following code example produces a count of the number of bakeries in each bo of New York. To do so, it uses an aggregation pipeline that contains the following stages: - :manual:`$match ` stage to filter for documents - in which the ``cuisine`` field contains the value ``'Bakery'`` + in which the ``cuisine`` field contains the value ``'Bakery'`` - :manual:`$group ` stage to group the matching - documents by the ``borough`` field, accumulating a count of documents for each distinct - value + documents by the ``borough`` field, accumulating a count of documents for each distinct + value .. io-code-block:: :copyable: .. input:: /includes/aggregation/aggregation.php - :start-after: start-match-group - :end-before: end-match-group - :language: php - :dedent: + :start-after: start-match-group + :end-before: end-match-group + :language: php + :dedent: .. output:: - :visible: false + :visible: false - {"_id":"Brooklyn","count":173} - {"_id":"Queens","count":204} - {"_id":"Bronx","count":71} - {"_id":"Staten Island","count":20} - {"_id":"Missing","count":2} - {"_id":"Manhattan","count":221} + {"_id":"Brooklyn","count":173} + {"_id":"Queens","count":204} + {"_id":"Bronx","count":71} + {"_id":"Staten Island","count":20} + {"_id":"Missing","count":2} + {"_id":"Manhattan","count":221} Explain an Aggregation ~~~~~~~~~~~~~~~~~~~~~~ @@ -147,19 +147,19 @@ from the preceding :ref:`php-aggregation-example`: :copyable: .. input:: /includes/aggregation/aggregation.php - :start-after: start-explain - :end-before: end-explain - :language: php - :dedent: + :start-after: start-explain + :end-before: end-explain + :language: php + :dedent: .. output:: - :visible: false + :visible: false - {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", - "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", - "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, - "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ - ... } + {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", + "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", + "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, + "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ + ... } Additional Information ---------------------- From 7b21d0e301d489dbfd9da9bdb4218bb085302e4b Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 10:58:56 -0500 Subject: [PATCH 05/19] fix indentation --- source/aggregation.txt | 54 +++++++++++++++++++++--------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/source/aggregation.txt b/source/aggregation.txt index 01519eeb..0b0468b2 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -78,9 +78,9 @@ Consider the following limitations when performing aggregation operations: .. important:: $graphLookup Exception - The :manual:`$graphLookup - ` stage has a strict - memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. + The :manual:`$graphLookup + ` stage has a strict + memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. .. _php-aggregation-example: @@ -111,20 +111,20 @@ of New York. To do so, it uses an aggregation pipeline that contains the followi :copyable: .. input:: /includes/aggregation/aggregation.php - :start-after: start-match-group - :end-before: end-match-group - :language: php - :dedent: + :start-after: start-match-group + :end-before: end-match-group + :language: php + :dedent: .. output:: - :visible: false + :visible: false - {"_id":"Brooklyn","count":173} - {"_id":"Queens","count":204} - {"_id":"Bronx","count":71} - {"_id":"Staten Island","count":20} - {"_id":"Missing","count":2} - {"_id":"Manhattan","count":221} + {"_id":"Brooklyn","count":173} + {"_id":"Queens","count":204} + {"_id":"Bronx","count":71} + {"_id":"Staten Island","count":20} + {"_id":"Missing","count":2} + {"_id":"Manhattan","count":221} Explain an Aggregation ~~~~~~~~~~~~~~~~~~~~~~ @@ -147,19 +147,19 @@ from the preceding :ref:`php-aggregation-example`: :copyable: .. input:: /includes/aggregation/aggregation.php - :start-after: start-explain - :end-before: end-explain - :language: php - :dedent: - - .. output:: - :visible: false - - {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", - "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", - "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, - "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ - ... } + :start-after: start-explain + :end-before: end-explain + :language: php + :dedent: + + .. output:: + :visible: false + + {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", + "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3", + "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false, + "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ + ... } Additional Information ---------------------- From 712754e2ae413e82b158b12b4ffd02d7ca9771d4 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 10:59:15 -0500 Subject: [PATCH 06/19] snooty landing page --- snooty.toml | 51 ++++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/snooty.toml b/snooty.toml index c0d688f0..3600f791 100644 --- a/snooty.toml +++ b/snooty.toml @@ -2,34 +2,35 @@ name = "php-library" title = "PHP Library Manual" intersphinx = [ - "https://www.mongodb.com/docs/manual/objects.inv", - "https://www.mongodb.com/docs/drivers/objects.inv", - "https://www.mongodb.com/docs/atlas/objects.inv", + "https://www.mongodb.com/docs/manual/objects.inv", + "https://www.mongodb.com/docs/drivers/objects.inv", + "https://www.mongodb.com/docs/atlas/objects.inv", ] toc_landing_pages = [ - "/reference/class/MongoDBClient", - "/reference/class/MongoDBCollection", - "/reference/class/MongoDBDatabase", - "/reference/class/MongoDBGridFSBucket", - "/reference/class/MongoDBBulkWriteResult", - "/reference/class/MongoDBDeleteResult", - "/reference/class/MongoDBInsertManyResult", - "/reference/class/MongoDBUpdateResult", - "/reference/class/MongoDBChangeStream", - "/reference/class/MongoDBMapReduceResult", - "/reference/class/MongoDBModelCollectionInfo", - "/reference/class/MongoDBModelDatabaseInfo", - "/reference/class/MongoDBModelIndexInfo", - "/get-started", - "/connect", - "/read", - "/databases-collections", - "/write", - "/indexes", - "/security", - "/data-formats", - "/upgrade", + "/reference/class/MongoDBClient", + "/reference/class/MongoDBCollection", + "/reference/class/MongoDBDatabase", + "/reference/class/MongoDBGridFSBucket", + "/reference/class/MongoDBBulkWriteResult", + "/reference/class/MongoDBDeleteResult", + "/reference/class/MongoDBInsertManyResult", + "/reference/class/MongoDBUpdateResult", + "/reference/class/MongoDBChangeStream", + "/reference/class/MongoDBMapReduceResult", + "/reference/class/MongoDBModelCollectionInfo", + "/reference/class/MongoDBModelDatabaseInfo", + "/reference/class/MongoDBModelIndexInfo", + "/get-started", + "/connect", + "/read", + "/databases-collections", + "/write", + "/indexes", + "/security", + "/data-formats", + "/upgrade", + "/aggregation" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" From 89457788cc42ca0d068f89ea33f32233b0671d50 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 11:01:19 -0500 Subject: [PATCH 07/19] snooty landing page --- snooty.toml | 52 ++++++++++++++++++++++++++-------------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/snooty.toml b/snooty.toml index 3600f791..f8b6d380 100644 --- a/snooty.toml +++ b/snooty.toml @@ -2,35 +2,35 @@ name = "php-library" title = "PHP Library Manual" intersphinx = [ - "https://www.mongodb.com/docs/manual/objects.inv", - "https://www.mongodb.com/docs/drivers/objects.inv", - "https://www.mongodb.com/docs/atlas/objects.inv", + "https://www.mongodb.com/docs/manual/objects.inv", + "https://www.mongodb.com/docs/drivers/objects.inv", + "https://www.mongodb.com/docs/atlas/objects.inv", ] toc_landing_pages = [ - "/reference/class/MongoDBClient", - "/reference/class/MongoDBCollection", - "/reference/class/MongoDBDatabase", - "/reference/class/MongoDBGridFSBucket", - "/reference/class/MongoDBBulkWriteResult", - "/reference/class/MongoDBDeleteResult", - "/reference/class/MongoDBInsertManyResult", - "/reference/class/MongoDBUpdateResult", - "/reference/class/MongoDBChangeStream", - "/reference/class/MongoDBMapReduceResult", - "/reference/class/MongoDBModelCollectionInfo", - "/reference/class/MongoDBModelDatabaseInfo", - "/reference/class/MongoDBModelIndexInfo", - "/get-started", - "/connect", - "/read", - "/databases-collections", - "/write", - "/indexes", - "/security", - "/data-formats", - "/upgrade", - "/aggregation" + "/reference/class/MongoDBClient", + "/reference/class/MongoDBCollection", + "/reference/class/MongoDBDatabase", + "/reference/class/MongoDBGridFSBucket", + "/reference/class/MongoDBBulkWriteResult", + "/reference/class/MongoDBDeleteResult", + "/reference/class/MongoDBInsertManyResult", + "/reference/class/MongoDBUpdateResult", + "/reference/class/MongoDBChangeStream", + "/reference/class/MongoDBMapReduceResult", + "/reference/class/MongoDBModelCollectionInfo", + "/reference/class/MongoDBModelDatabaseInfo", + "/reference/class/MongoDBModelIndexInfo", + "/get-started", + "/connect", + "/read", + "/databases-collections", + "/write", + "/indexes", + "/security", + "/data-formats", + "/upgrade", + "/aggregation" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" From 4b97a4f2badc224f977e03456e27a6b6b556ce92 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 11:08:48 -0500 Subject: [PATCH 08/19] indentation fix --- source/aggregation/atlas-search.txt | 30 +-- source/aggregation/vector-search.txt | 192 +++++++++--------- source/includes/aggregation/atlas-search.php | 64 +++--- source/includes/aggregation/vector-search.php | 28 +-- 4 files changed, 157 insertions(+), 157 deletions(-) diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt index b2768376..b377073a 100644 --- a/source/aggregation/atlas-search.txt +++ b/source/aggregation/atlas-search.txt @@ -66,7 +66,7 @@ Import the following classes into your application to perform Atlas Search queries by using the Aggregation Builder: .. code-block:: php - + use MongoDB\Builder\Pipeline; use MongoDB\Builder\Search; use MongoDB\Builder\Stage; @@ -86,12 +86,12 @@ The following code demonstrates the template for constructing basic Atlas Search queries: .. code-block:: php - + $pipeline = new Pipeline( - Stage::search( - // Atlas Search query specifications - // Search::compound(...) - ), + Stage::search( + // Atlas Search query specifications + // Search::compound(...) + ), ); Atlas Search Query Examples @@ -125,18 +125,18 @@ specifications: :copyable: true .. input:: /includes/aggregation/atlas-search.php - :language: php - :dedent: - :start-after: start-compound-search-query - :end-before: end-compound-search-query + :language: php + :dedent: + :start-after: start-compound-search-query + :end-before: end-compound-search-query .. output:: - :language: json - :visible: false + :language: json + :visible: false - {"_id": ...,"borough":"Queens","cuisine":"American","name":"Suite Kitchen",...} - {"_id": ...,"borough":"Queens","cuisine":"American","name":"Silver Kitchen",...} - // Results truncated + {"_id": ...,"borough":"Queens","cuisine":"American","name":"Suite Kitchen",...} + {"_id": ...,"borough":"Queens","cuisine":"American","name":"Silver Kitchen",...} + // Results truncated Autocomplete Query ~~~~~~~~~~~~~~~~~~ diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index fe2044f8..8812ed6d 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -5,17 +5,17 @@ Atlas Vector Search =================== .. facet:: - :name: genre - :values: reference + :name: genre + :values: reference .. meta:: - :keywords: code example, semantic, text, embeddings + :keywords: code example, semantic, text, embeddings .. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol + :local: + :backlinks: none + :depth: 2 + :class: singlecol Overview -------- @@ -28,9 +28,9 @@ perform Atlas Vector Search queries by using the :ref:`Aggregation Builder API .. note:: Deployment Compatibility - You can use the Atlas Search feature only when - you connect to MongoDB Atlas clusters. This feature is not - available for self-managed deployments. + You can use the Atlas Search feature only when + you connect to MongoDB Atlas clusters. This feature is not + available for self-managed deployments. To learn more about Atlas Vector Search, see the :atlas:`Overview ` in the @@ -43,15 +43,15 @@ Atlas documentation. .. note:: - You might not be able to use the methods described in - this guide for every type of Atlas Search query. For more complex use - cases, you can follow the standard way to create aggregation - pipelines in the {+library-short+}. To learn more, see the - :ref:`php-aggregation` guide. + You might not be able to use the methods described in + this guide for every type of Atlas Search query. For more complex use + cases, you can follow the standard way to create aggregation + pipelines in the {+library-short+}. To learn more, see the + :ref:`php-aggregation` guide. - To perform advanced full-text search on your documents, you can use the - Atlas Search API. To learn about this feature, see the - :ref:`php-atlas-search` guide. + To perform advanced full-text search on your documents, you can use the + Atlas Search API. To learn about this feature, see the + :ref:`php-atlas-search` guide. Atlas Vector Search Index ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -68,9 +68,9 @@ Search queries by using the Aggregation Builder: .. code-block:: php - use MongoDB\Builder\Pipeline; - use MongoDB\Builder\Query; - use MongoDB\Builder\Stage; + use MongoDB\Builder\Pipeline; + use MongoDB\Builder\Query; + use MongoDB\Builder\Stage; To create a ``$search`` stage in your aggregation pipeline, you must perform the following actions: @@ -78,49 +78,49 @@ perform the following actions: 1. Create a ``Pipeline`` class instance to create the pipeline #. Within the ``Pipeline`` instance, call the ``Stage::vectorSearch()`` method - to create the Atlas Vector Search stage + to create the Atlas Vector Search stage #. Within the body of the ``vectorSearch()`` method, specify the - criteria for your vector query + criteria for your vector query The following code demonstrates the template for constructing basic Atlas Search queries: .. code-block:: php - $pipeline = new Pipeline( - Stage::vectorSearch( - // Atlas Vector Search query specifications - // index: '', - // path: '', - // ... - ), - ); + $pipeline = new Pipeline( + Stage::vectorSearch( + // Atlas Vector Search query specifications + // index: '', + // path: '', + // ... + ), + ); You must pass the following parameters to the ``vectorSearch()`` method: .. list-table:: - :header-rows: 1 + :header-rows: 1 - * - Parameter - - Type - - Description + * - Parameter + - Type + - Description - * - ``index`` - - ``string`` - - Name of the vector search index + * - ``index`` + - ``string`` + - Name of the vector search index - * - ``path`` - - ``array`` or ``string`` - - Field that stores vector embeddings + * - ``path`` + - ``array`` or ``string`` + - Field that stores vector embeddings - * - ``queryVector`` - - ``array`` - - Vector representation of your query + * - ``queryVector`` + - ``array`` + - Vector representation of your query - * - ``limit`` - - ``int`` - - Number of results to return + * - ``limit`` + - ``int`` + - Number of results to return Atlas Search Query Examples --------------------------- @@ -137,22 +137,22 @@ The following code performs an Atlas Vector Search query on the ``plot_embedding`` vector field: .. io-code-block:: - :copyable: true + :copyable: true - .. input:: /includes/aggregation/vector-search.php - :language: php - :dedent: - :start-after: start-basic-query - :end-before: end-basic-query + .. input:: /includes/aggregation/vector-search.php + :language: php + :dedent: + :start-after: start-basic-query + :end-before: end-basic-query - .. output:: - :language: json - :visible: false + .. output:: + :language: json + :visible: false - {"_id": ...,"title":"About Time",...} - {"_id": ...,"title":"Tomorrowland",...} - {"_id": ...,"title":"Timecop",...} - // Results truncated + {"_id": ...,"title":"About Time",...} + {"_id": ...,"title":"Tomorrowland",...} + {"_id": ...,"title":"Timecop",...} + // Results truncated Vector Search Score ~~~~~~~~~~~~~~~~~~~ @@ -162,22 +162,22 @@ but outputs only the ``title`` field and ``vectorSearchScore`` meta field, which describes how well the document matches the query vector: .. io-code-block:: - :copyable: true + :copyable: true - .. input:: /includes/aggregation/vector-search.php - :language: php - :dedent: - :start-after: start-score-query - :end-before: end-score-query + .. input:: /includes/aggregation/vector-search.php + :language: php + :dedent: + :start-after: start-score-query + :end-before: end-score-query - .. output:: - :language: json - :visible: false + .. output:: + :language: json + :visible: false - {"title":"About Time","score":0.7843604683876038} - {"title":"Timecop","score":0.7771612405776978} - {"title":"Tomorrowland","score":0.7669923901557922} - // Results truncated + {"title":"About Time","score":0.7843604683876038} + {"title":"Timecop","score":0.7771612405776978} + {"title":"Tomorrowland","score":0.7669923901557922} + // Results truncated Vector Search Options ~~~~~~~~~~~~~~~~~~~~~ @@ -187,29 +187,29 @@ Vector Search queries. Depending on your desired query, you can pass the following optional parameters to ``vectorSearch()``: .. list-table:: - :header-rows: 1 - - * - Optional Parameter - - Type - - Description - - Default Value - - * - ``exact`` - - ``bool`` - - Specifies whether to run an Exact Nearest Neighbor (``true``) or - Approximate Nearest Neighbor (``false``) search - - ``false`` - - * - ``filter`` - - ``QueryInterface`` or ``array`` - - Specifies a pre-filter for documents to search on - - no filtering - - * - ``numCandidates`` - - ``int`` or ``null`` - - Specifies the number of nearest neighbors to use during the - search - - ``null`` + :header-rows: 1 + + * - Optional Parameter + - Type + - Description + - Default Value + + * - ``exact`` + - ``bool`` + - Specifies whether to run an Exact Nearest Neighbor (``true``) or + Approximate Nearest Neighbor (``false``) search + - ``false`` + + * - ``filter`` + - ``QueryInterface`` or ``array`` + - Specifies a pre-filter for documents to search on + - no filtering + + * - ``numCandidates`` + - ``int`` or ``null`` + - Specifies the number of nearest neighbors to use during the + search + - ``null`` To learn more about these parameters, see the :atlas:`Fields ` section of the diff --git a/source/includes/aggregation/atlas-search.php b/source/includes/aggregation/atlas-search.php index 4ecbed27..2bbebb07 100644 --- a/source/includes/aggregation/atlas-search.php +++ b/source/includes/aggregation/atlas-search.php @@ -9,52 +9,52 @@ // start-compound-search-query $pipeline = new Pipeline( - Stage::search( - Search::compound( - must: [ - Search::text( - query: 'kitchen', - path: 'name', - ), - ], - should: [ - Search::text( - query: 'american', - path: 'cuisine', - ), - ], - filter: [ - Search::text( - query: 'Queens', - path: 'borough', - ), - ], - ), - ), + Stage::search( + Search::compound( + must: [ + Search::text( + query: 'kitchen', + path: 'name', + ), + ], + should: [ + Search::text( + query: 'american', + path: 'cuisine', + ), + ], + filter: [ + Search::text( + query: 'Queens', + path: 'borough', + ), + ], + ), + ), ); $cursor = $collection->aggregate($pipeline); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc), PHP_EOL; } // end-compound-search-query // start-autocomplete-search-query $pipeline = new Pipeline( - Stage::search( - Search::autocomplete( - query: 'Lucy', - path: 'name', - ), - ), - Stage::limit(10), - Stage::project(_id: 0, title: 1), + Stage::search( + Search::autocomplete( + query: 'Lucy', + path: 'name', + ), + ), + Stage::limit(10), + Stage::project(_id: 0, title: 1), ); $cursor = $collection->aggregate($pipeline); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc), PHP_EOL; } // end-autocomplete-search-query \ No newline at end of file diff --git a/source/includes/aggregation/vector-search.php b/source/includes/aggregation/vector-search.php index ce7833ab..fa9f90c8 100644 --- a/source/includes/aggregation/vector-search.php +++ b/source/includes/aggregation/vector-search.php @@ -21,29 +21,29 @@ $cursor = $collection->aggregate($pipeline); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc), PHP_EOL; } // end-basic-query // start-score-query $pipeline = new Pipeline( - Stage::vectorSearch( - index: 'vector_index', - path: 'plot_embedding', - queryVector: [-0.0016261312, -0.028070757, -0.011342932], - numCandidates: 150, - limit: 10, - ), - Stage::project( - _id: 0, - title: 1, - score: ['$meta' => 'vectorSearchScore'], - ), + Stage::vectorSearch( + index: 'vector_index', + path: 'plot_embedding', + queryVector: [-0.0016261312, -0.028070757, -0.011342932], + numCandidates: 150, + limit: 10, + ), + Stage::project( + _id: 0, + title: 1, + score: ['$meta' => 'vectorSearchScore'], + ), ); $cursor = $collection->aggregate($pipeline); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc), PHP_EOL; } // end-score-query \ No newline at end of file From bc8154597165d98ee833e12b5166ae321860e975 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 11:11:05 -0500 Subject: [PATCH 09/19] netlify trigger From a967927dfee9a8911782d0bd93bc6d5aecf5e3dd Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 11:26:13 -0500 Subject: [PATCH 10/19] whats new --- source/aggregation/atlas-search.txt | 4 ++-- source/aggregation/vector-search.txt | 8 ++++---- source/whats-new.txt | 5 +++++ 3 files changed, 11 insertions(+), 6 deletions(-) diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt index b377073a..f74d857d 100644 --- a/source/aggregation/atlas-search.txt +++ b/source/aggregation/atlas-search.txt @@ -89,8 +89,8 @@ queries: $pipeline = new Pipeline( Stage::search( - // Atlas Search query specifications - // Search::compound(...) + # Atlas Search query specifications + # Search::compound(...) ), ); diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index 8812ed6d..aa0e0a2f 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -90,10 +90,10 @@ queries: $pipeline = new Pipeline( Stage::vectorSearch( - // Atlas Vector Search query specifications - // index: '', - // path: '', - // ... + # Atlas Vector Search query specifications + # index: '', + # path: '', + # ... ), ); diff --git a/source/whats-new.txt b/source/whats-new.txt index af355a54..9aa5d97b 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -49,6 +49,11 @@ improvements, and fixes: replaced by these new methods in a future driver release, so consider changing the usages in your application. +- Adds named arguments for the ``SearchStage`` builder. This change + allows you to write Atlas Search and Atlas Vector Search queries in a + more type-safe and organized way. To learn more, see the + :ref:`php-atlas-search` and :ref:`php-vector-search` guides. + .. _php-lib-version-1.20: What's New in 1.20 From 3a15fbd77e7e04af33e9a7481b03aee625abca70 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 16:10:12 -0500 Subject: [PATCH 11/19] RM PR fixes 1 --- source/aggregation/atlas-search.txt | 14 ++++++-------- source/aggregation/vector-search.txt | 14 ++++++-------- 2 files changed, 12 insertions(+), 16 deletions(-) diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt index f74d857d..8213cb66 100644 --- a/source/aggregation/atlas-search.txt +++ b/source/aggregation/atlas-search.txt @@ -23,8 +23,7 @@ Overview In this guide, you can learn how to perform searches on your documents by using the Atlas Search feature. The {+library-short+} allows you to perform Atlas Search queries by using the :ref:`Aggregation Builder API -`. This guide provides examples of how to use the -{+library-short+} to perform searches. +`. .. note:: Deployment Compatibility @@ -42,10 +41,9 @@ the Atlas documentation. .. note:: - You might not be able to use the methods described in - this guide for every type of Atlas Search query. For more complex use - cases, you can follow the standard way to create aggregation - pipelines in the {+library-short+}. To learn more, see the + You might not be able to use the methods described in this guide for + every type of Atlas Search query. For more complex use cases, you can + create standard aggregation pipelines. To learn more, see the :ref:`php-aggregation` guide. To perform searches on vector embeddings in MongoDB, you can use the @@ -71,8 +69,8 @@ Search queries by using the Aggregation Builder: use MongoDB\Builder\Search; use MongoDB\Builder\Stage; -To create a ``$search`` stage in your aggregation pipeline, you must -perform the following actions: +To create a ``$search`` stage in your aggregation pipeline, perform the +following actions: 1. Create a ``Pipeline`` class instance to create the pipeline diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index aa0e0a2f..01d65ff5 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -23,8 +23,7 @@ Overview In this guide, you can learn how to perform searches on your documents by using the Atlas Vector Search feature. The {+library-short+} allows you to perform Atlas Vector Search queries by using the :ref:`Aggregation Builder API -`. This guide provides examples of how to use the -{+library-short+} to perform Atlas Vector Search queries. +`. .. note:: Deployment Compatibility @@ -43,10 +42,9 @@ Atlas documentation. .. note:: - You might not be able to use the methods described in - this guide for every type of Atlas Search query. For more complex use - cases, you can follow the standard way to create aggregation - pipelines in the {+library-short+}. To learn more, see the + You might not be able to use the methods described in this guide for + every type of Atlas Vector Search query. For more complex use cases, you can + create standard aggregation pipelines. To learn more, see the :ref:`php-aggregation` guide. To perform advanced full-text search on your documents, you can use the @@ -72,8 +70,8 @@ Search queries by using the Aggregation Builder: use MongoDB\Builder\Query; use MongoDB\Builder\Stage; -To create a ``$search`` stage in your aggregation pipeline, you must -perform the following actions: +To create a ``$vectorSearch`` stage in your aggregation pipeline, perform the +following actions: 1. Create a ``Pipeline`` class instance to create the pipeline From df431416fbd094133ebdabadaeafdace5c3043c2 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 16:12:52 -0500 Subject: [PATCH 12/19] comments --- source/aggregation/atlas-search.txt | 4 ++-- source/aggregation/vector-search.txt | 7 +++---- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt index 8213cb66..a05f0bee 100644 --- a/source/aggregation/atlas-search.txt +++ b/source/aggregation/atlas-search.txt @@ -87,8 +87,8 @@ queries: $pipeline = new Pipeline( Stage::search( - # Atlas Search query specifications - # Search::compound(...) + /* Atlas Search query specifications + Search::compound(...) */ ), ); diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index 01d65ff5..24a4962a 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -88,10 +88,9 @@ queries: $pipeline = new Pipeline( Stage::vectorSearch( - # Atlas Vector Search query specifications - # index: '', - # path: '', - # ... + /* Atlas Vector Search query specifications + index: '', + path: '', ...*/ ), ); From d9123975ac72779004752b3fead5fed16097de07 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 16:17:51 -0500 Subject: [PATCH 13/19] small fix --- source/whats-new.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index 9aa5d97b..846e573b 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -49,7 +49,8 @@ improvements, and fixes: replaced by these new methods in a future driver release, so consider changing the usages in your application. -- Adds named arguments for the ``SearchStage`` builder. This change +- Adds named arguments for the ``SearchStage``, ``VectorSearchStage``, + and ``SearchMetaStage`` builder classes. This change allows you to write Atlas Search and Atlas Vector Search queries in a more type-safe and organized way. To learn more, see the :ref:`php-atlas-search` and :ref:`php-vector-search` guides. From 9d4aae25c942deb2445cb44b436e336c7d3796f4 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 16:42:58 -0500 Subject: [PATCH 14/19] JT tech review 1 --- source/aggregation.txt | 2 +- source/aggregation/atlas-search.txt | 28 ++-- source/aggregation/vector-search.txt | 131 ++++++++------- source/includes/aggregation/atlas-search.php | 156 ++++++++++++++---- source/includes/aggregation/vector-search.php | 72 +++++++- 5 files changed, 266 insertions(+), 123 deletions(-) diff --git a/source/aggregation.txt b/source/aggregation.txt index 0b0468b2..527a9626 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -77,7 +77,7 @@ Consider the following limitations when performing aggregation operations: and passing the array to the ``MongoDB\Collection::aggregate()`` method. .. important:: $graphLookup Exception - + The :manual:`$graphLookup ` stage has a strict memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt index a05f0bee..8549014d 100644 --- a/source/aggregation/atlas-search.txt +++ b/source/aggregation/atlas-search.txt @@ -39,12 +39,7 @@ to perform queries. To learn more about this operator, see the :atlas:`$search ` reference in the Atlas documentation. -.. note:: - - You might not be able to use the methods described in this guide for - every type of Atlas Search query. For more complex use cases, you can - create standard aggregation pipelines. To learn more, see the - :ref:`php-aggregation` guide. +.. note:: Atlas Vector Search To perform searches on vector embeddings in MongoDB, you can use the Atlas Vector Search API. To learn about this feature, see @@ -63,11 +58,11 @@ Search Aggregation Stage Import the following classes into your application to perform Atlas Search queries by using the Aggregation Builder: -.. code-block:: php - - use MongoDB\Builder\Pipeline; - use MongoDB\Builder\Search; - use MongoDB\Builder\Stage; +.. literalinclude:: /includes/aggregation/atlas-search.php + :language: php + :dedent: + :start-after: start-imports + :end-before: end-imports To create a ``$search`` stage in your aggregation pipeline, perform the following actions: @@ -84,7 +79,7 @@ The following code demonstrates the template for constructing basic Atlas Search queries: .. code-block:: php - + $pipeline = new Pipeline( Stage::search( /* Atlas Search query specifications @@ -132,8 +127,9 @@ specifications: :language: json :visible: false - {"_id": ...,"borough":"Queens","cuisine":"American","name":"Suite Kitchen",...} - {"_id": ...,"borough":"Queens","cuisine":"American","name":"Silver Kitchen",...} + {"_id":...,"borough":"Queens","cuisine":"American","name":"Kitchen Door"} + {"_id":...,"borough":"Queens","cuisine":"American","name":"Cc Kitchen"} + {"_id":...,"borough":"Queens","cuisine":"American","name":"Suite Kitchen"} // Results truncated Autocomplete Query @@ -169,9 +165,9 @@ string ``"Lucy"`` on the ``name`` field: :language: json :visible: false - {"name":"Lucy'S Asian Kitchen"} - {"name":"Lucy'S Cantina Royale"} + {"name":"Juicy Lucy"} {"name":"Lucy'S Vietnamese Kitchen"} + {"name":"Lucy'S Cantina Royale"} // Results Truncated You can also pass the following optional parameters to the ``autocomplete()`` diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index 24a4962a..4469efba 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -27,9 +27,9 @@ perform Atlas Vector Search queries by using the :ref:`Aggregation Builder API .. note:: Deployment Compatibility - You can use the Atlas Search feature only when - you connect to MongoDB Atlas clusters. This feature is not - available for self-managed deployments. + You can use the Atlas Search feature only when + you connect to MongoDB Atlas clusters. This feature is not + available for self-managed deployments. To learn more about Atlas Vector Search, see the :atlas:`Overview ` in the @@ -40,12 +40,7 @@ to perform queries. To learn more about this operator, see the ` reference in the Atlas documentation. -.. note:: - - You might not be able to use the methods described in this guide for - every type of Atlas Vector Search query. For more complex use cases, you can - create standard aggregation pipelines. To learn more, see the - :ref:`php-aggregation` guide. +.. note:: Atlas Search To perform advanced full-text search on your documents, you can use the Atlas Search API. To learn about this feature, see the @@ -64,11 +59,11 @@ Vector Search Aggregation Stage Import the following classes into your application to perform Atlas Search queries by using the Aggregation Builder: -.. code-block:: php - - use MongoDB\Builder\Pipeline; - use MongoDB\Builder\Query; - use MongoDB\Builder\Stage; +.. literalinclude:: /includes/aggregation/vector-search.php + :language: php + :dedent: + :start-after: start-imports + :end-before: end-imports To create a ``$vectorSearch`` stage in your aggregation pipeline, perform the following actions: @@ -87,11 +82,11 @@ queries: .. code-block:: php $pipeline = new Pipeline( - Stage::vectorSearch( - /* Atlas Vector Search query specifications - index: '', - path: '', ...*/ - ), + Stage::vectorSearch( + /* Atlas Vector Search query specifications + index: '', + path: '', ...*/ + ), ); You must pass the following parameters to the ``vectorSearch()`` method: @@ -100,24 +95,24 @@ You must pass the following parameters to the ``vectorSearch()`` method: :header-rows: 1 * - Parameter - - Type - - Description + - Type + - Description * - ``index`` - - ``string`` - - Name of the vector search index + - ``string`` + - Name of the vector search index * - ``path`` - - ``array`` or ``string`` - - Field that stores vector embeddings + - ``array`` or ``string`` + - Field that stores vector embeddings * - ``queryVector`` - - ``array`` - - Vector representation of your query + - ``array`` + - Vector representation of your query * - ``limit`` - - ``int`` - - Number of results to return + - ``int`` + - Number of results to return Atlas Search Query Examples --------------------------- @@ -127,6 +122,16 @@ Search queries by using the Aggregation Builder. The examples in this section use sample data from the ``sample_mflix.embedded_movies`` collection. +.. note:: Query Vector Length + + For demonstrative purposes, the examples in this section use + sample query vectors that contain very few elements, compared to + the query vector you might use in a runnable application. To view an + example that contains the full-length query vector, see the + :ref:`Atlas Vector Search Quick Start ` + and select :guilabel:`PHP` from the :guilabel:`Select your language` dropdown in the upper-right + corner of the page. + Basic Vector Search Query ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -137,19 +142,19 @@ The following code performs an Atlas Vector Search query on the :copyable: true .. input:: /includes/aggregation/vector-search.php - :language: php - :dedent: - :start-after: start-basic-query - :end-before: end-basic-query + :language: php + :dedent: + :start-after: start-basic-query + :end-before: end-basic-query .. output:: - :language: json - :visible: false + :language: json + :visible: false - {"_id": ...,"title":"About Time",...} - {"_id": ...,"title":"Tomorrowland",...} - {"_id": ...,"title":"Timecop",...} - // Results truncated + {"title":"Thrill Seekers"} + {"title":"About Time"} + {"title":"Timecop"} + // Results truncated Vector Search Score ~~~~~~~~~~~~~~~~~~~ @@ -162,19 +167,19 @@ field, which describes how well the document matches the query vector: :copyable: true .. input:: /includes/aggregation/vector-search.php - :language: php - :dedent: - :start-after: start-score-query - :end-before: end-score-query + :language: php + :dedent: + :start-after: start-score-query + :end-before: end-score-query .. output:: - :language: json - :visible: false + :language: json + :visible: false - {"title":"About Time","score":0.7843604683876038} - {"title":"Timecop","score":0.7771612405776978} - {"title":"Tomorrowland","score":0.7669923901557922} - // Results truncated + {"title":"Thrill Seekers","score":0.927734375} + {"title":"About Time","score":0.925750732421875} + {"title":"Timecop","score":0.9241180419921875} + // Results truncated Vector Search Options ~~~~~~~~~~~~~~~~~~~~~ @@ -187,26 +192,26 @@ following optional parameters to ``vectorSearch()``: :header-rows: 1 * - Optional Parameter - - Type - - Description - - Default Value + - Type + - Description + - Default Value * - ``exact`` - - ``bool`` - - Specifies whether to run an Exact Nearest Neighbor (``true``) or - Approximate Nearest Neighbor (``false``) search - - ``false`` + - ``bool`` + - Specifies whether to run an Exact Nearest Neighbor (``true``) or + Approximate Nearest Neighbor (``false``) search + - ``false`` * - ``filter`` - - ``QueryInterface`` or ``array`` - - Specifies a pre-filter for documents to search on - - no filtering + - ``QueryInterface`` or ``array`` + - Specifies a pre-filter for documents to search on + - no filtering * - ``numCandidates`` - - ``int`` or ``null`` - - Specifies the number of nearest neighbors to use during the - search - - ``null`` + - ``int`` or ``null`` + - Specifies the number of nearest neighbors to use during the + search + - ``null`` To learn more about these parameters, see the :atlas:`Fields ` section of the diff --git a/source/includes/aggregation/atlas-search.php b/source/includes/aggregation/atlas-search.php index 2bbebb07..dab5e161 100644 --- a/source/includes/aggregation/atlas-search.php +++ b/source/includes/aggregation/atlas-search.php @@ -1,5 +1,11 @@ sample_restaurants->restaurants; +define('WAIT_TIMEOUT_SEC', 300); + +echo "\nCreating the Atlas Search index.\n"; +$collection->createSearchIndex( + ['mappings' => ['dynamic' => true]], +); + +// Waits for the index to be queryable +wait(function () use ($collection) { + echo '.'; + foreach ($collection->listSearchIndexes() as $index) { + if ($index->name === 'default') { + return $index->queryable; + } + } + + return false; +}); + +echo "\n"; + // start-compound-search-query $pipeline = new Pipeline( - Stage::search( - Search::compound( - must: [ - Search::text( - query: 'kitchen', - path: 'name', - ), - ], - should: [ - Search::text( - query: 'american', - path: 'cuisine', - ), - ], - filter: [ - Search::text( - query: 'Queens', - path: 'borough', - ), - ], - ), - ), + Stage::search( + Search::compound( + must: [ + Search::text( + query: 'kitchen', + path: 'name', + ), + ], + should: [ + Search::text( + query: 'american', + path: 'cuisine', + ), + ], + filter: [ + Search::text( + query: 'Queens', + path: 'borough', + ), + ], + ), + ), + Stage::project( + borough: 1, + cuisine: 1, + name: 1 + ), + Stage::limit(3) ); -$cursor = $collection->aggregate($pipeline); +$cursor = $collection->aggregate(iterator_to_array($pipeline)); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc), PHP_EOL; } // end-compound-search-query +echo "\nUpdating the Atlas Search index for autocomplete.\n"; +$collection->updateSearchIndex( + 'default', + ['mappings' => [ + "dynamic" => false, + "fields" => [ + "name" => [ + ["type" => "stringFacet"], + ["type" => "string"], + [ + "foldDiacritics" => false, + "maxGrams" => 7, + "minGrams" => 3, + "tokenization" => "edgeGram", + "type" => "autocomplete" + ], + ] + ] + ]] +); + +// Waits for the index to be updated. +wait(function () use ($collection) { + echo '.'; + foreach ($collection->listSearchIndexes() as $index) { + if ($index->name === 'default') { + return $index->latestDefinition->mappings->fields->name[2]['type'] === 'autocomplete' + && $index->status === 'READY'; + } + } + + return false; +}); + +echo "\n"; + // start-autocomplete-search-query $pipeline = new Pipeline( - Stage::search( - Search::autocomplete( - query: 'Lucy', - path: 'name', - ), - ), - Stage::limit(10), - Stage::project(_id: 0, title: 1), + Stage::search( + Search::autocomplete( + query: 'Lucy', + path: 'name', + ), + ), + Stage::limit(3), + Stage::project(_id: 0, name: 1), ); -$cursor = $collection->aggregate($pipeline); +$cursor = $collection->aggregate(iterator_to_array($pipeline)); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc), PHP_EOL; +} +// end-autocomplete-search-query + +/** + * This function waits until the callback returns true or the timeout is reached. + */ +function wait(Closure $callback): void +{ + $timeout = hrtime()[0] + WAIT_TIMEOUT_SEC; + while (hrtime()[0] < $timeout) { + if ($callback()) { + return; + } + + sleep(5); + } + + throw new RuntimeException('Time out'); } -// end-autocomplete-search-query \ No newline at end of file diff --git a/source/includes/aggregation/vector-search.php b/source/includes/aggregation/vector-search.php index fa9f90c8..ece84979 100644 --- a/source/includes/aggregation/vector-search.php +++ b/source/includes/aggregation/vector-search.php @@ -1,5 +1,10 @@ sample_mflix->embedded_movies; +define('WAIT_TIMEOUT_SEC', 300); + +echo "\nCreating the Atlas Vector Search index.\n"; +$collection->createSearchIndex( + [ + 'fields' => [[ + 'type' => 'vector', + 'path' => 'plot_embedding', + 'numDimensions' => 1536, + 'similarity' => 'dotProduct', + 'quantization' => 'scalar' + ]] + ], + ['name' => 'vector', 'type' => 'vectorSearch'], +); + +// Wait for the index to be queryable. +wait(function () use ($collection) { + echo '.'; + foreach ($collection->listSearchIndexes() as $index) { + if ($index->name === 'vector') { + return $index->queryable; + } + } + + return false; +}); + +echo "\n"; + // start-basic-query $pipeline = new Pipeline( Stage::vectorSearch( - index: 'vector_index', + index: 'vector', path: 'plot_embedding', queryVector: [-0.0016261312, -0.028070757, -0.011342932], numCandidates: 150, - limit: 10, - ) + limit: 5, + ), + Stage::project( + _id: 0, + title: 1, + ), ); -$cursor = $collection->aggregate($pipeline); +$cursor = $collection->aggregate(iterator_to_array($pipeline)); foreach ($cursor as $doc) { echo json_encode($doc), PHP_EOL; @@ -28,11 +67,11 @@ // start-score-query $pipeline = new Pipeline( Stage::vectorSearch( - index: 'vector_index', + index: 'vector', path: 'plot_embedding', queryVector: [-0.0016261312, -0.028070757, -0.011342932], numCandidates: 150, - limit: 10, + limit: 5, ), Stage::project( _id: 0, @@ -41,9 +80,26 @@ ), ); -$cursor = $collection->aggregate($pipeline); +$cursor = $collection->aggregate(iterator_to_array($pipeline)); foreach ($cursor as $doc) { echo json_encode($doc), PHP_EOL; } -// end-score-query \ No newline at end of file +// end-score-query + +/** + * This function waits until the callback returns true or the timeout is reached. + */ +function wait(Closure $callback): void +{ + $timeout = hrtime()[0] + WAIT_TIMEOUT_SEC; + while (hrtime()[0] < $timeout) { + if ($callback()) { + return; + } + + sleep(5); + } + + throw new RuntimeException('Time out'); +} From 491f26ad47f0e12062efa5061eb5e5a67d4bb0a1 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 16:44:24 -0500 Subject: [PATCH 15/19] indentation fix --- source/aggregation/vector-search.txt | 106 ++++++------ source/includes/aggregation/atlas-search.php | 162 +++++++++---------- 2 files changed, 134 insertions(+), 134 deletions(-) diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index 4469efba..1f7c14d7 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -27,9 +27,9 @@ perform Atlas Vector Search queries by using the :ref:`Aggregation Builder API .. note:: Deployment Compatibility - You can use the Atlas Search feature only when - you connect to MongoDB Atlas clusters. This feature is not - available for self-managed deployments. + You can use the Atlas Search feature only when + you connect to MongoDB Atlas clusters. This feature is not + available for self-managed deployments. To learn more about Atlas Vector Search, see the :atlas:`Overview ` in the @@ -82,11 +82,11 @@ queries: .. code-block:: php $pipeline = new Pipeline( - Stage::vectorSearch( - /* Atlas Vector Search query specifications - index: '', - path: '', ...*/ - ), + Stage::vectorSearch( + /* Atlas Vector Search query specifications + index: '', + path: '', ...*/ + ), ); You must pass the following parameters to the ``vectorSearch()`` method: @@ -95,24 +95,24 @@ You must pass the following parameters to the ``vectorSearch()`` method: :header-rows: 1 * - Parameter - - Type - - Description + - Type + - Description * - ``index`` - - ``string`` - - Name of the vector search index + - ``string`` + - Name of the vector search index * - ``path`` - - ``array`` or ``string`` - - Field that stores vector embeddings + - ``array`` or ``string`` + - Field that stores vector embeddings * - ``queryVector`` - - ``array`` - - Vector representation of your query + - ``array`` + - Vector representation of your query * - ``limit`` - - ``int`` - - Number of results to return + - ``int`` + - Number of results to return Atlas Search Query Examples --------------------------- @@ -123,7 +123,7 @@ section use sample data from the ``sample_mflix.embedded_movies`` collection. .. note:: Query Vector Length - + For demonstrative purposes, the examples in this section use sample query vectors that contain very few elements, compared to the query vector you might use in a runnable application. To view an @@ -142,19 +142,19 @@ The following code performs an Atlas Vector Search query on the :copyable: true .. input:: /includes/aggregation/vector-search.php - :language: php - :dedent: - :start-after: start-basic-query - :end-before: end-basic-query + :language: php + :dedent: + :start-after: start-basic-query + :end-before: end-basic-query .. output:: - :language: json - :visible: false + :language: json + :visible: false - {"title":"Thrill Seekers"} - {"title":"About Time"} - {"title":"Timecop"} - // Results truncated + {"title":"Thrill Seekers"} + {"title":"About Time"} + {"title":"Timecop"} + // Results truncated Vector Search Score ~~~~~~~~~~~~~~~~~~~ @@ -167,19 +167,19 @@ field, which describes how well the document matches the query vector: :copyable: true .. input:: /includes/aggregation/vector-search.php - :language: php - :dedent: - :start-after: start-score-query - :end-before: end-score-query + :language: php + :dedent: + :start-after: start-score-query + :end-before: end-score-query .. output:: - :language: json - :visible: false + :language: json + :visible: false - {"title":"Thrill Seekers","score":0.927734375} - {"title":"About Time","score":0.925750732421875} - {"title":"Timecop","score":0.9241180419921875} - // Results truncated + {"title":"Thrill Seekers","score":0.927734375} + {"title":"About Time","score":0.925750732421875} + {"title":"Timecop","score":0.9241180419921875} + // Results truncated Vector Search Options ~~~~~~~~~~~~~~~~~~~~~ @@ -192,26 +192,26 @@ following optional parameters to ``vectorSearch()``: :header-rows: 1 * - Optional Parameter - - Type - - Description - - Default Value + - Type + - Description + - Default Value * - ``exact`` - - ``bool`` - - Specifies whether to run an Exact Nearest Neighbor (``true``) or - Approximate Nearest Neighbor (``false``) search - - ``false`` + - ``bool`` + - Specifies whether to run an Exact Nearest Neighbor (``true``) or + Approximate Nearest Neighbor (``false``) search + - ``false`` * - ``filter`` - - ``QueryInterface`` or ``array`` - - Specifies a pre-filter for documents to search on - - no filtering + - ``QueryInterface`` or ``array`` + - Specifies a pre-filter for documents to search on + - no filtering * - ``numCandidates`` - - ``int`` or ``null`` - - Specifies the number of nearest neighbors to use during the - search - - ``null`` + - ``int`` or ``null`` + - Specifies the number of nearest neighbors to use during the + search + - ``null`` To learn more about these parameters, see the :atlas:`Fields ` section of the diff --git a/source/includes/aggregation/atlas-search.php b/source/includes/aggregation/atlas-search.php index dab5e161..37c2ea1c 100644 --- a/source/includes/aggregation/atlas-search.php +++ b/source/includes/aggregation/atlas-search.php @@ -17,114 +17,114 @@ echo "\nCreating the Atlas Search index.\n"; $collection->createSearchIndex( - ['mappings' => ['dynamic' => true]], + ['mappings' => ['dynamic' => true]], ); // Waits for the index to be queryable wait(function () use ($collection) { - echo '.'; - foreach ($collection->listSearchIndexes() as $index) { - if ($index->name === 'default') { - return $index->queryable; - } - } - - return false; + echo '.'; + foreach ($collection->listSearchIndexes() as $index) { + if ($index->name === 'default') { + return $index->queryable; + } + } + + return false; }); echo "\n"; // start-compound-search-query $pipeline = new Pipeline( - Stage::search( - Search::compound( - must: [ - Search::text( - query: 'kitchen', - path: 'name', - ), - ], - should: [ - Search::text( - query: 'american', - path: 'cuisine', - ), - ], - filter: [ - Search::text( - query: 'Queens', - path: 'borough', - ), - ], - ), - ), - Stage::project( - borough: 1, - cuisine: 1, - name: 1 - ), - Stage::limit(3) + Stage::search( + Search::compound( + must: [ + Search::text( + query: 'kitchen', + path: 'name', + ), + ], + should: [ + Search::text( + query: 'american', + path: 'cuisine', + ), + ], + filter: [ + Search::text( + query: 'Queens', + path: 'borough', + ), + ], + ), + ), + Stage::project( + borough: 1, + cuisine: 1, + name: 1 + ), + Stage::limit(3) ); $cursor = $collection->aggregate(iterator_to_array($pipeline)); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc), PHP_EOL; } // end-compound-search-query echo "\nUpdating the Atlas Search index for autocomplete.\n"; $collection->updateSearchIndex( - 'default', - ['mappings' => [ - "dynamic" => false, - "fields" => [ - "name" => [ - ["type" => "stringFacet"], - ["type" => "string"], - [ - "foldDiacritics" => false, - "maxGrams" => 7, - "minGrams" => 3, - "tokenization" => "edgeGram", - "type" => "autocomplete" - ], - ] - ] - ]] + 'default', + ['mappings' => [ + "dynamic" => false, + "fields" => [ + "name" => [ + ["type" => "stringFacet"], + ["type" => "string"], + [ + "foldDiacritics" => false, + "maxGrams" => 7, + "minGrams" => 3, + "tokenization" => "edgeGram", + "type" => "autocomplete" + ], + ] + ] + ]] ); // Waits for the index to be updated. wait(function () use ($collection) { - echo '.'; - foreach ($collection->listSearchIndexes() as $index) { - if ($index->name === 'default') { - return $index->latestDefinition->mappings->fields->name[2]['type'] === 'autocomplete' - && $index->status === 'READY'; - } - } - - return false; + echo '.'; + foreach ($collection->listSearchIndexes() as $index) { + if ($index->name === 'default') { + return $index->latestDefinition->mappings->fields->name[2]['type'] === 'autocomplete' + && $index->status === 'READY'; + } + } + + return false; }); echo "\n"; // start-autocomplete-search-query $pipeline = new Pipeline( - Stage::search( - Search::autocomplete( - query: 'Lucy', - path: 'name', - ), - ), - Stage::limit(3), - Stage::project(_id: 0, name: 1), + Stage::search( + Search::autocomplete( + query: 'Lucy', + path: 'name', + ), + ), + Stage::limit(3), + Stage::project(_id: 0, name: 1), ); $cursor = $collection->aggregate(iterator_to_array($pipeline)); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc), PHP_EOL; } // end-autocomplete-search-query @@ -133,14 +133,14 @@ */ function wait(Closure $callback): void { - $timeout = hrtime()[0] + WAIT_TIMEOUT_SEC; - while (hrtime()[0] < $timeout) { - if ($callback()) { - return; - } + $timeout = hrtime()[0] + WAIT_TIMEOUT_SEC; + while (hrtime()[0] < $timeout) { + if ($callback()) { + return; + } - sleep(5); - } + sleep(5); + } - throw new RuntimeException('Time out'); + throw new RuntimeException('Time out'); } From b8fc265484f9140e74f63e9ec4ee2411ab8e90b0 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 16:50:10 -0500 Subject: [PATCH 16/19] fix --- source/aggregation/vector-search.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index 1f7c14d7..5ee4b833 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -128,7 +128,7 @@ collection. sample query vectors that contain very few elements, compared to the query vector you might use in a runnable application. To view an example that contains the full-length query vector, see the - :ref:`Atlas Vector Search Quick Start ` + :atlas:`Atlas Vector Search Quick Start ` and select :guilabel:`PHP` from the :guilabel:`Select your language` dropdown in the upper-right corner of the page. From a6d8d988c31a98bad2525fc4a4114369c8c1b14d Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 16:51:54 -0500 Subject: [PATCH 17/19] small fixes --- source/aggregation/atlas-search.txt | 2 +- source/aggregation/vector-search.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt index 8549014d..f07f0674 100644 --- a/source/aggregation/atlas-search.txt +++ b/source/aggregation/atlas-search.txt @@ -193,7 +193,7 @@ To learn more about these parameters, see the :atlas:`Options ``autocomplete`` operator reference in the Atlas documentation. Search Options -~~~~~~~~~~~~~~ +-------------- You can use the ``search()`` method to perform many types of Atlas Search queries. Depending on your desired query, you can pass the diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index 5ee4b833..0a56023f 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -182,7 +182,7 @@ field, which describes how well the document matches the query vector: // Results truncated Vector Search Options -~~~~~~~~~~~~~~~~~~~~~ +--------------------- You can use the ``vectorSearch()`` method to perform many types of Atlas Vector Search queries. Depending on your desired query, you can pass the From dab011fa59249d586fcc101eb22eacc265fc9d79 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 16:55:17 -0500 Subject: [PATCH 18/19] small fixes --- source/aggregation/atlas-search.txt | 7 +++---- source/aggregation/vector-search.txt | 11 +++++------ 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt index f07f0674..603d6a6d 100644 --- a/source/aggregation/atlas-search.txt +++ b/source/aggregation/atlas-search.txt @@ -31,10 +31,9 @@ perform Atlas Search queries by using the :ref:`Aggregation Builder API you connect to MongoDB Atlas clusters. This feature is not available for self-managed deployments. -To learn more about Atlas Search, see the :atlas:`Overview -` in the -Atlas documentation. The Atlas Search implementation for the -{+library-short+} internally uses the ``$search`` aggregation operator +To learn more about Atlas Search, see the :atlas:`Atlas Search Overview +`. The Atlas Search implementation +for the {+library-short+} internally uses the ``$search`` aggregation operator to perform queries. To learn more about this operator, see the :atlas:`$search ` reference in the Atlas documentation. diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index 0a56023f..da97aeef 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -31,12 +31,11 @@ perform Atlas Vector Search queries by using the :ref:`Aggregation Builder API you connect to MongoDB Atlas clusters. This feature is not available for self-managed deployments. -To learn more about Atlas Vector Search, see the :atlas:`Overview -` in the -Atlas documentation. The Atlas Vector Search implementation for the -{+library-short+} internally uses the ``$vectorSearch`` aggregation operator -to perform queries. To learn more about this operator, see the -:atlas:`$vectorSearch +To learn more about Atlas Vector Search, see the :atlas:`Atlas Vector +Search Overview `. The +Atlas Vector Search implementation for the {+library-short+} internally +uses the ``$vectorSearch`` aggregation operator to perform queries. To +learn more about this operator, see the :atlas:`$vectorSearch ` reference in the Atlas documentation. From 88b50a8cb83305dd357dc4db69105fd12853a39d Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 10 Feb 2025 15:51:52 -0500 Subject: [PATCH 19/19] remov Pipeline type --- source/aggregation/atlas-search.txt | 9 ++++----- source/aggregation/vector-search.txt | 10 +++++----- source/includes/aggregation/atlas-search.php | 13 ++++++------- source/includes/aggregation/vector-search.php | 13 ++++++------- 4 files changed, 21 insertions(+), 24 deletions(-) diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt index 603d6a6d..d47ac750 100644 --- a/source/aggregation/atlas-search.txt +++ b/source/aggregation/atlas-search.txt @@ -66,10 +66,9 @@ Search queries by using the Aggregation Builder: To create a ``$search`` stage in your aggregation pipeline, perform the following actions: -1. Create a ``Pipeline`` class instance to create the pipeline +1. Create an array to store the pipeline stages -#. Within the ``Pipeline`` instance, call the ``Stage::search()`` method - to create the Atlas Search stage +#. Call the ``Stage::search()`` method to create the Atlas Search stage #. Within the body of the ``search()`` method, use methods from the ``Search`` builder class to construct your Search query criteria @@ -79,12 +78,12 @@ queries: .. code-block:: php - $pipeline = new Pipeline( + $pipeline = [ Stage::search( /* Atlas Search query specifications Search::compound(...) */ ), - ); + ]; Atlas Search Query Examples --------------------------- diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index da97aeef..b9ca56dc 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -67,10 +67,10 @@ Search queries by using the Aggregation Builder: To create a ``$vectorSearch`` stage in your aggregation pipeline, perform the following actions: -1. Create a ``Pipeline`` class instance to create the pipeline +1. Create an array to store the pipeline stages -#. Within the ``Pipeline`` instance, call the ``Stage::vectorSearch()`` method - to create the Atlas Vector Search stage +#. Call the ``Stage::vectorSearch()`` method to create the Atlas Vector + Search stage #. Within the body of the ``vectorSearch()`` method, specify the criteria for your vector query @@ -80,13 +80,13 @@ queries: .. code-block:: php - $pipeline = new Pipeline( + $pipeline = [ Stage::vectorSearch( /* Atlas Vector Search query specifications index: '', path: '', ...*/ ), - ); + ]; You must pass the following parameters to the ``vectorSearch()`` method: diff --git a/source/includes/aggregation/atlas-search.php b/source/includes/aggregation/atlas-search.php index 37c2ea1c..80f165f2 100644 --- a/source/includes/aggregation/atlas-search.php +++ b/source/includes/aggregation/atlas-search.php @@ -1,7 +1,6 @@ aggregate(iterator_to_array($pipeline)); +$cursor = $collection->aggregate($pipeline); foreach ($cursor as $doc) { echo json_encode($doc), PHP_EOL; @@ -110,7 +109,7 @@ echo "\n"; // start-autocomplete-search-query -$pipeline = new Pipeline( +$pipeline = [ Stage::search( Search::autocomplete( query: 'Lucy', @@ -119,9 +118,9 @@ ), Stage::limit(3), Stage::project(_id: 0, name: 1), -); +]; -$cursor = $collection->aggregate(iterator_to_array($pipeline)); +$cursor = $collection->aggregate($pipeline); foreach ($cursor as $doc) { echo json_encode($doc), PHP_EOL; diff --git a/source/includes/aggregation/vector-search.php b/source/includes/aggregation/vector-search.php index ece84979..c8e0c924 100644 --- a/source/includes/aggregation/vector-search.php +++ b/source/includes/aggregation/vector-search.php @@ -1,7 +1,6 @@ aggregate(iterator_to_array($pipeline)); +$cursor = $collection->aggregate($pipeline); foreach ($cursor as $doc) { echo json_encode($doc), PHP_EOL; @@ -65,7 +64,7 @@ // end-basic-query // start-score-query -$pipeline = new Pipeline( +$pipeline = [ Stage::vectorSearch( index: 'vector', path: 'plot_embedding', @@ -78,9 +77,9 @@ title: 1, score: ['$meta' => 'vectorSearchScore'], ), -); +]; -$cursor = $collection->aggregate(iterator_to_array($pipeline)); +$cursor = $collection->aggregate($pipeline); foreach ($cursor as $doc) { echo json_encode($doc), PHP_EOL;