From 916355504f9b0692c4e7e8dfdeeea3a6f73e3b24 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 28 Jan 2025 16:15:38 -0500 Subject: [PATCH 01/20] DOCSP-46269: as & avs --- docs/fundamentals.txt | 2 + docs/fundamentals/as-avs.txt | 186 ++++++++++++++++++ .../fundamentals/as-avs/AtlasSearchTest.php | 66 +++++++ docs/includes/fundamentals/as-avs/Movie.php | 12 ++ 4 files changed, 266 insertions(+) create mode 100644 docs/fundamentals/as-avs.txt create mode 100644 docs/includes/fundamentals/as-avs/AtlasSearchTest.php create mode 100644 docs/includes/fundamentals/as-avs/Movie.php diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index db482b2b8..a008c300e 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -20,6 +20,7 @@ Fundamentals Read Operations Write Operations Aggregation Builder + Atlas Search & Vector Search Learn more about the following concepts related to {+odm-long+}: @@ -28,3 +29,4 @@ Learn more about the following concepts related to {+odm-long+}: - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-aggregation-builder` +- :ref:`laravel-atlas-search-avs` diff --git a/docs/fundamentals/as-avs.txt b/docs/fundamentals/as-avs.txt new file mode 100644 index 000000000..4d6c70b17 --- /dev/null +++ b/docs/fundamentals/as-avs.txt @@ -0,0 +1,186 @@ +.. _laravel-atlas-search-avs: + +============================ +Atlas Search & Vector Search +============================ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, semantic, 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 Search and Vector Search features. {+odm-long+} +provides an API to use these features directly with your models. + +To learn more about these features, see the following pages in the Atlas +documentation: + +- :atlas:`Atlas Search Overview ` +- :atlas:`Atlas Vector Search Overview ` + +.. note:: Deployment Compatibility + + You can use the Atlas Search and Vector Search features only when + connecting to MongoDB Atlas clusters. These features are not available for + self-managed deployments. + +This page describes how to create the appropriate indexes for each type +of search and provides examples of how to use the {+odm-short+} to +perform searches. + +Atlas Search +------------ + +In this section, you can learn how to create Atlas Search indexes +and perform searches in the {+odm-short+}. The Atlas Search API +internally uses the ``$search`` aggregation operator to perform queries. +To learn more about this operator, see the :atlas:`$search +` reference in the Atlas documentation. + +.. _laravel-as-index: + +Create an Atlas Search Index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. TODO in DOCSP-46230 + +Perform Queries +~~~~~~~~~~~~~~~ + +In this section, you can learn how to use the Atlas Search API in the +{+odm-short+}. + +General Queries +``````````````` + +The {+odm-short+} provides the ``search()`` method as a query +builder method and as an Eloquent model method. You can use the +``search()`` method to run Atlas Search queries on documents in your +collections. + +You must pass an ``operator`` parameter to the ``search()`` method that +is an instance of ``SearchOperatorInterface`` or an array. You can +create an instance of ``SearchOperatorInterface`` by calling the +``Search::text()`` method and passing the field you are +querying and your search term or phrase. + +You must include the following import statement in your application to +create a ``SearchOperatorInterface`` instance: + +.. code-block:: php + + use MongoDB\Builder\Search; + +The following code uses the index created in the preceding +:ref:`laravel-as-index` section to perform an Atlas Search query on the +``movies`` collection: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php + :language: php + :dedent: + :start-after: start-search-query + :end-before: end-search-query + + .. output:: + :language: json + :visible: false + + [ + { "title": "Dreaming of Jakarta", + "year": 1990 + }, + { "title": "See You in My Dreams", + "year": 1996 + } + ] + +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()``: + +- ``index``: ``string`` +- ``highlight``: ``array`` +- ``concurrent``: ``bool`` +- ``count``: ``string`` +- ``searchAfter``: ``string`` +- ``searchBefore`: ``string``` +- ``scoreDetails``: ``bool`` +- ``sort``: ``array`` +- ``returnStoredSource``: ``bool`` +- ``tracking``: ``array`` + +To learn more about these parameters, see the :atlas:`Fields +` section of the +``$search`` operator reference in the Atlas documentation. + +Autocomplete Queries +```````````````````` + +The {+odm-short+} provides the ``autocomplete()`` method as a query +builder method and as an Eloquent model method. You can use the +``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:: + + You must create an Atlas Search index with an autocomplete configuration + on your collection before you can perform autocomplete searches. See the + :ref:`laravel-as-index` section of this guide to learn more about + creating Search indexes. + +The following code performs an Atlas Search autocomplete query on the +``movies`` collection: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php + :language: php + :dedent: + :start-after: start-auto-query + :end-before: end-auto-query + + .. output:: + :language: json + :visible: false + + [ + { "title": "Dreaming of Jakarta", + "year": 1990 + }, + { "title": "Jakob the Liar", + "year": 1999 + }, + { "title": "Emily Calling Jake", + "year": 2001 + } + ] + +You can also pass the following parameters to the ``autocomplete()`` +method to customize the query: + +- ``fuzzy``: ``bool`` or ``array`` (default: ``false``) +- ``tokenOrder``: ``string`` (default: ``'any'``) + +To learn more about these parameters, see the :atlas:`Options +` section of the +``autocomplete`` operator reference in the Atlas documentation. diff --git a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php new file mode 100644 index 000000000..0de63f30e --- /dev/null +++ b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php @@ -0,0 +1,66 @@ +getCollection('movies'); + $moviesCollection->drop(); + $moviesCollection->createSearchIndex([ + 'mappings' => ['dynamic' => true], + ], ['name' => 'simple_search']); + + Movie::insert([ + ['title' => 'Dreaming of Jakarta', 'year' => 1990], + ['title' => 'See You in My Dreams', 'year' => 1996], + ['title' => 'On the Run', 'year' => 2004], + ['title' => 'Jakob the Liar', 'year' => 1999], + ['title' => 'Emily Calling Jake', 'year' => 2001], + ]); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testSimpleSearch(): void + { + // start-search-query + $movies = Movie::search( + sort: ['title' => 1], + operator: Search::text('title', 'dream'), + )->get(); + // end-search-query + + $this->assertNotNull($movies); + $this->assertCount(2, $movies); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function autocompleteSearchTest(): void + { + // start-auto-query + $movies = Movie::autocomplete('title', 'jak') + ->get(); + // end-auto-query + + $this->assertNotNull($movies); + $this->assertCount(3, $movies); + } +} diff --git a/docs/includes/fundamentals/as-avs/Movie.php b/docs/includes/fundamentals/as-avs/Movie.php new file mode 100644 index 000000000..2098db9ec --- /dev/null +++ b/docs/includes/fundamentals/as-avs/Movie.php @@ -0,0 +1,12 @@ + Date: Wed, 29 Jan 2025 09:54:31 -0500 Subject: [PATCH 02/20] wip --- docs/fundamentals/as-avs.txt | 78 ++++++++++++++++++- .../fundamentals/as-avs/AtlasSearchTest.php | 60 +++++++++++++- 2 files changed, 136 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/as-avs.txt b/docs/fundamentals/as-avs.txt index 4d6c70b17..35196d016 100644 --- a/docs/fundamentals/as-avs.txt +++ b/docs/fundamentals/as-avs.txt @@ -118,7 +118,7 @@ following optional parameters to ``search()``: - ``concurrent``: ``bool`` - ``count``: ``string`` - ``searchAfter``: ``string`` -- ``searchBefore`: ``string``` +- ``searchBefore`` ``string`` - ``scoreDetails``: ``bool`` - ``sort``: ``array`` - ``returnStoredSource``: ``bool`` @@ -184,3 +184,79 @@ method to customize the query: To learn more about these parameters, see the :atlas:`Options ` section of the ``autocomplete`` operator reference in the Atlas documentation. + +Atlas Vector Search +------------------- + +In this section, you can learn how to create Atlas Vector Search indexes +and perform searches in the {+odm-short+}. The Atlas Vector Search API +internally uses the ``$vectorSearch`` aggregation operator to perform queries. +To learn more about this operator, see the :atlas:`$vectorSearch +` +reference in the Atlas documentation. + +.. _laravel-avs-index: + +Create an Atlas Vector Search Index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. TODO in DOCSP-46230 + +Perform Queries +~~~~~~~~~~~~~~~ + +In this section, you can learn how to use the Atlas Vector Search API in +the {+odm-short+}. The {+odm-short+} provides the ``vectorSearch()`` +method as a query builder method and as an Eloquent model method. You +can use the ``vectorSearch()`` method to run Atlas Vector Search queries +on documents in your collections. + +You must pass the following parameters to the ``search()`` method: + +- ``index``: Name of the vector search index (type: ``string``) +- ``path``: Field that stores vector embeddings (type: ``array`` or ``string``) +- ``queryVector``: Vector representation of your query (type: ``array``) +- ``limit``: Number of results to return (type: ``int``) + +The following code uses the index created in the preceding +:ref:`laravel-avs-index` section to perform an Atlas Vector Search query on the +``movies`` collection: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php + :language: php + :dedent: + :start-after: start-vs-query + :end-before: end-vs-query + + .. output:: + :language: json + :visible: false + + [ + { "title": "Sunrising", + "plot": "A shy teenager discovers confidence and new friendships during a transformative summer camp experience." + }, + { "title": "Last Semester", + "plot": "High school friends navigate love, identity, and unexpected challenges before graduating together." + } + ] + +You can use the ``vector()`` method to perform many types of Atlas +Search queries. Depending on your desired query, you can pass the +following optional parameters to ``search()``: + +- ``exact``: ``bool`` (default: ``false``) +- ``filter``: ``QueryInterface`` or ``array`` +- ``numCandidates``: ``int`` or ``null`` (default: ``null``) + +.. tip:: + + To construct a ``QueryInterface`` instance, you must import the + ``MongoDB\Builder\Query`` class into your application. + +To learn more about these parameters, see the :atlas:`Fields +` section of the +``$vectorSearch`` operator reference in the Atlas documentation. diff --git a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php index 0de63f30e..46a582512 100644 --- a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php +++ b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php @@ -6,11 +6,20 @@ use App\Models\Movie; use Illuminate\Support\Facades\DB; -use MongoDB\Laravel\Tests\TestCase; +use MongoDB\Builder\Query; use MongoDB\Builder\Search; +use MongoDB\Laravel\Tests\TestCase; + +use function array_map; +use function mt_getrandmax; +use function rand; +use function range; +use function srand; class AtlasSearchTest extends TestCase { + private array $vectors; + protected function setUp(): void { require_once __DIR__ . '/Movie.php'; @@ -30,6 +39,13 @@ protected function setUp(): void ['title' => 'Jakob the Liar', 'year' => 1999], ['title' => 'Emily Calling Jake', 'year' => 2001], ]); + + Movie::insert($this->addVector([ + ['title' => 'A', 'plot' => 'A shy teenager discovers confidence and new friendships during a transformative summer camp experience.'], + ['title' => 'B', 'plot' => 'A detective teams up with a hacker to unravel a global conspiracy threatening personal freedoms.'], + ['title' => 'C', 'plot' => 'High school friends navigate love, identity, and unexpected challenges before graduating together.'], + ['title' => 'D', 'plot' => 'Stranded on a distant planet, astronauts must repair their ship before supplies run out.'], + ])); } /** @@ -63,4 +79,46 @@ public function autocompleteSearchTest(): void $this->assertNotNull($movies); $this->assertCount(3, $movies); } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function vectorSearchTest(): void + { + // start-vs-query + $movies = Book::vectorSearch( + index: 'vector', + path: 'vector_embeddings', + // Vector representation of the query "coming of age" + queryVector: [-0.0016261312, -0.028070757, ...], + limit: 3, + ); + // end-vs-query + + $results = Book::vectorSearch( + index: 'vector', + path: 'vector4', + queryVector: $this->vectors[0], + limit: 5, + numCandidates: 15, + filter: Query::query( + title: Query::ne('A'), + ), + ); + + $this->assertNotNull($results); + $this->assertSame('C', $results->first()->title); + } + + /** Generate random vectors using fixed seed to make tests deterministic */ + private function addVector(array $items): array + { + srand(1); + foreach ($items as &$item) { + $this->vectors[] = $item['vector4'] = array_map(fn () => rand() / mt_getrandmax(), range(0, 3)); + } + + return $items; + } } From fe84cee3271c6798bd9b13f22f91838a237a0bda Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 09:58:59 -0500 Subject: [PATCH 03/20] wip --- docs/fundamentals/as-avs.txt | 13 +++++++++---- .../fundamentals/as-avs/AtlasSearchTest.php | 14 ++------------ 2 files changed, 11 insertions(+), 16 deletions(-) diff --git a/docs/fundamentals/as-avs.txt b/docs/fundamentals/as-avs.txt index 35196d016..3c44c15f6 100644 --- a/docs/fundamentals/as-avs.txt +++ b/docs/fundamentals/as-avs.txt @@ -225,11 +225,16 @@ The following code uses the index created in the preceding .. io-code-block:: :copyable: true - .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php + .. input:: :language: php - :dedent: - :start-after: start-vs-query - :end-before: end-vs-query + + $movies = Book::vectorSearch( + index: 'vector', + path: 'vector_embeddings', + // Vector representation of the query "coming of age" + queryVector: [-0.0016261312, -0.028070757, ...], + limit: 3, + ); .. output:: :language: json diff --git a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php index 46a582512..a538739db 100644 --- a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php +++ b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php @@ -86,22 +86,12 @@ public function autocompleteSearchTest(): void */ public function vectorSearchTest(): void { - // start-vs-query - $movies = Book::vectorSearch( - index: 'vector', - path: 'vector_embeddings', - // Vector representation of the query "coming of age" - queryVector: [-0.0016261312, -0.028070757, ...], - limit: 3, - ); - // end-vs-query - $results = Book::vectorSearch( index: 'vector', path: 'vector4', queryVector: $this->vectors[0], - limit: 5, - numCandidates: 15, + limit: 3, + numCandidates: 10, filter: Query::query( title: Query::ne('A'), ), From 0c528347f941afcc108c7571fd33d266b37d1bbe Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 10:25:30 -0500 Subject: [PATCH 04/20] wip --- .../fundamentals/as-avs/AtlasSearchTest.php | 50 +++++++++++++++++-- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php index a538739db..b4c49e7cf 100644 --- a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php +++ b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php @@ -8,6 +8,8 @@ use Illuminate\Support\Facades\DB; use MongoDB\Builder\Query; use MongoDB\Builder\Search; +use MongoDB\Driver\Exception\ServerException; +use MongoDB\Laravel\Schema\Builder; use MongoDB\Laravel\Tests\TestCase; use function array_map; @@ -15,6 +17,7 @@ use function rand; use function range; use function srand; +use function usleep; class AtlasSearchTest extends TestCase { @@ -28,9 +31,6 @@ protected function setUp(): void $moviesCollection = DB::connection('mongodb')->getCollection('movies'); $moviesCollection->drop(); - $moviesCollection->createSearchIndex([ - 'mappings' => ['dynamic' => true], - ], ['name' => 'simple_search']); Movie::insert([ ['title' => 'Dreaming of Jakarta', 'year' => 1990], @@ -46,6 +46,50 @@ protected function setUp(): void ['title' => 'C', 'plot' => 'High school friends navigate love, identity, and unexpected challenges before graduating together.'], ['title' => 'D', 'plot' => 'Stranded on a distant planet, astronauts must repair their ship before supplies run out.'], ])); + + $moviesCollection = DB::connection('mongodb')->getCollection('movies'); + + try { + $moviesCollection->createSearchIndex([ + 'mappings' => [ + 'fields' => [ + 'title' => [ + ['type' => 'string', 'analyzer' => 'lucene.english'], + ['type' => 'autocomplete', 'analyzer' => 'lucene.english'], + ['type' => 'token'], + ], + ], + ], + ]); + + $moviesCollection->createSearchIndex([ + 'mappings' => ['dynamic' => true], + ], ['name' => 'dynamic_search']); + + $moviesCollection->createSearchIndex([ + 'fields' => [ + ['type' => 'vector', 'numDimensions' => 4, 'path' => 'vector4', 'similarity' => 'cosine'], + ['type' => 'filter', 'path' => 'title'], + ], + ], ['name' => 'vector', 'type' => 'vectorSearch']); + } catch (ServerException $e) { + if (Builder::isAtlasSearchNotSupportedException($e)) { + self::markTestSkipped('Atlas Search not supported. ' . $e->getMessage()); + } + + throw $e; + } + + // Wait for the index to be ready + do { + $ready = true; + usleep(10_000); + foreach ($collection->listSearchIndexes() as $index) { + if ($index['status'] !== 'READY') { + $ready = false; + } + } + } while (! $ready); } /** From 0492b0191b87607d99282f906f72d2a1861ae2f0 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 10:27:45 -0500 Subject: [PATCH 05/20] JT small fix --- docs/fundamentals/as-avs.txt | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/fundamentals/as-avs.txt b/docs/fundamentals/as-avs.txt index 3c44c15f6..919b10510 100644 --- a/docs/fundamentals/as-avs.txt +++ b/docs/fundamentals/as-avs.txt @@ -164,15 +164,9 @@ The following code performs an Atlas Search autocomplete query on the :visible: false [ - { "title": "Dreaming of Jakarta", - "year": 1990 - }, - { "title": "Jakob the Liar", - "year": 1999 - }, - { "title": "Emily Calling Jake", - "year": 2001 - } + "Dreaming of Jakarta", + "Jakob the Liar", + "title": "Emily Calling Jake" ] You can also pass the following parameters to the ``autocomplete()`` From 00ded052c5ea89f3d6a2afebb031a0b5ec52dfc5 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 10:31:38 -0500 Subject: [PATCH 06/20] wip --- docs/fundamentals/as-avs.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/fundamentals/as-avs.txt b/docs/fundamentals/as-avs.txt index 919b10510..d2a51b490 100644 --- a/docs/fundamentals/as-avs.txt +++ b/docs/fundamentals/as-avs.txt @@ -134,7 +134,8 @@ Autocomplete Queries The {+odm-short+} provides the ``autocomplete()`` method as a query builder method and as an Eloquent model method. You can use the ``autocomplete()`` method to run autocomplete searches on documents in your -collections. +collections. This method returns only the values of the field you +specify as the query path. To learn more about this type of Atlas Search query, see the :atlas:`autocomplete ` reference in the @@ -147,8 +148,8 @@ Atlas documentation. :ref:`laravel-as-index` section of this guide to learn more about creating Search indexes. -The following code performs an Atlas Search autocomplete query on the -``movies`` collection: +The following code performs an Atlas Search autocomplete query for the +string ``"jak"`` on the ``title`` field: .. io-code-block:: :copyable: true @@ -166,7 +167,7 @@ The following code performs an Atlas Search autocomplete query on the [ "Dreaming of Jakarta", "Jakob the Liar", - "title": "Emily Calling Jake" + "Emily Calling Jake" ] You can also pass the following parameters to the ``autocomplete()`` @@ -248,7 +249,7 @@ Search queries. Depending on your desired query, you can pass the following optional parameters to ``search()``: - ``exact``: ``bool`` (default: ``false``) -- ``filter``: ``QueryInterface`` or ``array`` +- ``filter``: ``QueryInterface`` or ``array`` (default: no filtering) - ``numCandidates``: ``int`` or ``null`` (default: ``null``) .. tip:: From 930cec8f5668eaccf6b9bcfded747e7425ba14c3 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 10:36:41 -0500 Subject: [PATCH 07/20] wip --- docs/fundamentals/as-avs.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/as-avs.txt b/docs/fundamentals/as-avs.txt index d2a51b490..b416dc10d 100644 --- a/docs/fundamentals/as-avs.txt +++ b/docs/fundamentals/as-avs.txt @@ -206,7 +206,7 @@ method as a query builder method and as an Eloquent model method. You can use the ``vectorSearch()`` method to run Atlas Vector Search queries on documents in your collections. -You must pass the following parameters to the ``search()`` method: +You must pass the following parameters to the ``vectorSearch()`` method: - ``index``: Name of the vector search index (type: ``string``) - ``path``: Field that stores vector embeddings (type: ``array`` or ``string``) @@ -226,7 +226,7 @@ The following code uses the index created in the preceding $movies = Book::vectorSearch( index: 'vector', path: 'vector_embeddings', - // Vector representation of the query "coming of age" + // Vector representation of the query `coming of age` queryVector: [-0.0016261312, -0.028070757, ...], limit: 3, ); From cef5bb9d048bf42f9ef935b2f4ab4bc42bc48403 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 10:39:05 -0500 Subject: [PATCH 08/20] link fix --- docs/fundamentals/as-avs.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/as-avs.txt b/docs/fundamentals/as-avs.txt index b416dc10d..8356cc69b 100644 --- a/docs/fundamentals/as-avs.txt +++ b/docs/fundamentals/as-avs.txt @@ -28,7 +28,7 @@ To learn more about these features, see the following pages in the Atlas documentation: - :atlas:`Atlas Search Overview ` -- :atlas:`Atlas Vector Search Overview ` +- :atlas:`Atlas Vector Search Overview ` .. note:: Deployment Compatibility From 39ba92217af53b122cc135009be0864a6c3f3d88 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 11:29:15 -0500 Subject: [PATCH 09/20] merge upstream and make some changes from last PR --- docs/sessions.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/sessions.txt b/docs/sessions.txt index ea33b0d66..e8ed10e7a 100644 --- a/docs/sessions.txt +++ b/docs/sessions.txt @@ -69,10 +69,10 @@ following ways: The following list describes other driver options that you can set in the ``options`` array: -- ``id_field``: Field name for storing the session ID (default: ``_id``) -- ``data_field``: Field name for storing the session data (default: ``data``) -- ``time_field``: Field name for storing the timestamp (default: ``time``) -- ``expiry_field``: Field name for storing the expiry-timestamp (default: ``expires_at``) +- ``id_field``: Custom field name for storing the session ID (default: ``_id``) +- ``data_field``: Custom field name for storing the session data (default: ``data``) +- ``time_field``: Custom field name for storing the timestamp (default: ``time``) +- ``expiry_field``: Custom field name for storing the expiry timestamp (default: ``expires_at``) - ``ttl``: Time to live in seconds We recommend that you create an index on the ``expiry_field`` field for @@ -86,12 +86,12 @@ the following code: .. code-block:: php Schema::create('sessions', function (Blueprint $collection) { - $collection->expire('expiry_field', 0); + $collection->expire('expires_at', 0); }); -Setting the time value to ``0`` in the index -definition instructs MongoDB to expire documents at the clock time -specified in the ``expiry_field`` field. +Setting the time value to ``0`` in the index definition instructs +MongoDB to expire documents at the clock time specified in the +``expires_at`` field. To learn more about using the ``Schema`` builder to create indexes, see the :ref:`laravel-schema-builder-special-idx` section of the Schema From 11b3c9e9cd27bf49e9f9bf9586ed16899ad98ba6 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 14:58:24 -0500 Subject: [PATCH 10/20] revert changes to sessions page - will separate into another PR --- docs/sessions.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/sessions.txt b/docs/sessions.txt index e8ed10e7a..ea33b0d66 100644 --- a/docs/sessions.txt +++ b/docs/sessions.txt @@ -69,10 +69,10 @@ following ways: The following list describes other driver options that you can set in the ``options`` array: -- ``id_field``: Custom field name for storing the session ID (default: ``_id``) -- ``data_field``: Custom field name for storing the session data (default: ``data``) -- ``time_field``: Custom field name for storing the timestamp (default: ``time``) -- ``expiry_field``: Custom field name for storing the expiry timestamp (default: ``expires_at``) +- ``id_field``: Field name for storing the session ID (default: ``_id``) +- ``data_field``: Field name for storing the session data (default: ``data``) +- ``time_field``: Field name for storing the timestamp (default: ``time``) +- ``expiry_field``: Field name for storing the expiry-timestamp (default: ``expires_at``) - ``ttl``: Time to live in seconds We recommend that you create an index on the ``expiry_field`` field for @@ -86,12 +86,12 @@ the following code: .. code-block:: php Schema::create('sessions', function (Blueprint $collection) { - $collection->expire('expires_at', 0); + $collection->expire('expiry_field', 0); }); -Setting the time value to ``0`` in the index definition instructs -MongoDB to expire documents at the clock time specified in the -``expires_at`` field. +Setting the time value to ``0`` in the index +definition instructs MongoDB to expire documents at the clock time +specified in the ``expiry_field`` field. To learn more about using the ``Schema`` builder to create indexes, see the :ref:`laravel-schema-builder-special-idx` section of the Schema From 8570f09584af9216eb27bc7dba28e4dfc54848a7 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 15:19:33 -0500 Subject: [PATCH 11/20] LM PR fixes 1 --- docs/fundamentals/as-avs.txt | 129 ++++++++++++++---- .../fundamentals/as-avs/AtlasSearchTest.php | 5 +- 2 files changed, 103 insertions(+), 31 deletions(-) diff --git a/docs/fundamentals/as-avs.txt b/docs/fundamentals/as-avs.txt index 8356cc69b..e51635927 100644 --- a/docs/fundamentals/as-avs.txt +++ b/docs/fundamentals/as-avs.txt @@ -9,7 +9,7 @@ Atlas Search & Vector Search :values: reference .. meta:: - :keywords: code example, semantic, embeddings + :keywords: code example, semantic, embeddings, text .. contents:: On this page :local: @@ -33,8 +33,8 @@ documentation: .. note:: Deployment Compatibility You can use the Atlas Search and Vector Search features only when - connecting to MongoDB Atlas clusters. These features are not available for - self-managed deployments. + you connect to MongoDB Atlas clusters. These features are not + available for self-managed deployments. This page describes how to create the appropriate indexes for each type of search and provides examples of how to use the {+odm-short+} to @@ -71,7 +71,8 @@ builder method and as an Eloquent model method. You can use the collections. You must pass an ``operator`` parameter to the ``search()`` method that -is an instance of ``SearchOperatorInterface`` or an array. You can +is an instance of ``SearchOperatorInterface`` or an array that contains +the operator type, field name, and query value. You can create an instance of ``SearchOperatorInterface`` by calling the ``Search::text()`` method and passing the field you are querying and your search term or phrase. @@ -83,8 +84,8 @@ create a ``SearchOperatorInterface`` instance: use MongoDB\Builder\Search; -The following code uses the index created in the preceding -:ref:`laravel-as-index` section to perform an Atlas Search query on the +The following code performs an Atlas Search query that searches for the +term ``'dream'`` in the ``title`` field values of documents in the ``movies`` collection: .. io-code-block:: @@ -113,16 +114,41 @@ 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()``: -- ``index``: ``string`` -- ``highlight``: ``array`` -- ``concurrent``: ``bool`` -- ``count``: ``string`` -- ``searchAfter``: ``string`` -- ``searchBefore`` ``string`` -- ``scoreDetails``: ``bool`` -- ``sort``: ``array`` -- ``returnStoredSource``: ``bool`` -- ``tracking``: ``array`` +.. list-table:: + :header-rows: 1 + + * - Parameter + - Type + + * - ``index`` + - ``string`` + + * - ``highlight`` + - ``array`` + + * - ``concurrent`` + - ``bool`` + + * - ``count`` + - ``string`` + + * - ``searchAfter`` + - ``string`` + + * - ``searchBefore`` + - ``string`` + + * - ``scoreDetails`` + - ``bool`` + + * - ``sort`` + - ``array`` + + * - ``returnStoredSource`` + - ``bool`` + + * - ``tracking`` + - ``array`` To learn more about these parameters, see the :atlas:`Fields ` section of the @@ -170,11 +196,23 @@ string ``"jak"`` on the ``title`` field: "Emily Calling Jake" ] -You can also pass the following parameters to the ``autocomplete()`` +You can also pass the following optional parameters to the ``autocomplete()`` method to customize the query: -- ``fuzzy``: ``bool`` or ``array`` (default: ``false``) -- ``tokenOrder``: ``string`` (default: ``'any'``) +.. list-table:: + :header-rows: 1 + + * - Parameter + - Type + - Default Value + + * - ``fuzzy`` + - ``bool`` or ``array`` + - ``false`` + + * - ``tokenOrder`` + - ``string`` + - ``'any'`` To learn more about these parameters, see the :atlas:`Options ` section of the @@ -208,12 +246,30 @@ on documents in your collections. You must pass the following parameters to the ``vectorSearch()`` method: -- ``index``: Name of the vector search index (type: ``string``) -- ``path``: Field that stores vector embeddings (type: ``array`` or ``string``) -- ``queryVector``: Vector representation of your query (type: ``array``) -- ``limit``: Number of results to return (type: ``int``) - -The following code uses the index created in the preceding +.. 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 + +The following code uses the ``vector`` index created in the preceding :ref:`laravel-avs-index` section to perform an Atlas Vector Search query on the ``movies`` collection: @@ -248,11 +304,26 @@ You can use the ``vector()`` method to perform many types of Atlas Search queries. Depending on your desired query, you can pass the following optional parameters to ``search()``: -- ``exact``: ``bool`` (default: ``false``) -- ``filter``: ``QueryInterface`` or ``array`` (default: no filtering) -- ``numCandidates``: ``int`` or ``null`` (default: ``null``) +.. list-table:: + :header-rows: 1 + + * - Parameter + - Type + - Default Value -.. tip:: + * - ``exact`` + - ``bool`` + - ``false`` + + * - ``filter`` + - ``QueryInterface`` or ``array`` + - no filtering + + * - ``numCandidates`` + - ``int`` or ``null`` + - ``null`` + +.. note:: To construct a ``QueryInterface`` instance, you must import the ``MongoDB\Builder\Query`` class into your application. diff --git a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php index b4c49e7cf..161e273b3 100644 --- a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php +++ b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php @@ -80,7 +80,7 @@ protected function setUp(): void throw $e; } - // Wait for the index to be ready + // Waits for the index to be ready do { $ready = true; usleep(10_000); @@ -145,7 +145,8 @@ public function vectorSearchTest(): void $this->assertSame('C', $results->first()->title); } - /** Generate random vectors using fixed seed to make tests deterministic */ + /** Generates random vectors using fixed seed to make tests + * deterministic */ private function addVector(array $items): array { srand(1); From e61fbb4934613be60fd05c5393b4cc5e859ddf42 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 15:35:46 -0500 Subject: [PATCH 12/20] small note --- docs/fundamentals/as-avs.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/fundamentals/as-avs.txt b/docs/fundamentals/as-avs.txt index e51635927..eadd1bcbc 100644 --- a/docs/fundamentals/as-avs.txt +++ b/docs/fundamentals/as-avs.txt @@ -40,6 +40,13 @@ This page describes how to create the appropriate indexes for each type of search and provides examples of how to use the {+odm-short+} to perform searches. +.. note:: Aggregation Builder + + You might not be able to use the methods described in + this guide for every type of Atlas Search or Vector Search query. + For more complex use cases, create an aggregation pipeline by using + the :ref:`laravel-aggregation-builder`. + Atlas Search ------------ From c83d1565c012e83fa7029f2cf4dff322bfc33c64 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 29 Jan 2025 15:41:43 -0500 Subject: [PATCH 13/20] filename change --- docs/fundamentals.txt | 2 +- .../fundamentals/{as-avs.txt => atlas-search-vector-search.txt} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/fundamentals/{as-avs.txt => atlas-search-vector-search.txt} (100%) diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index a008c300e..0959791c5 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -20,7 +20,7 @@ Fundamentals Read Operations Write Operations Aggregation Builder - Atlas Search & Vector Search + Atlas Search & Vector Search Learn more about the following concepts related to {+odm-long+}: diff --git a/docs/fundamentals/as-avs.txt b/docs/fundamentals/atlas-search-vector-search.txt similarity index 100% rename from docs/fundamentals/as-avs.txt rename to docs/fundamentals/atlas-search-vector-search.txt From 57844aa72f37eb8cf2275c9327ee2d5152b3a550 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 30 Jan 2025 16:16:07 -0500 Subject: [PATCH 14/20] LM PR fixes 2 --- docs/fundamentals.txt | 4 +- .../atlas-search-vector-search.txt | 340 ------------------ docs/fundamentals/atlas-search.txt | 245 +++++++++++++ docs/fundamentals/vector-search.txt | 172 +++++++++ 4 files changed, 420 insertions(+), 341 deletions(-) delete mode 100644 docs/fundamentals/atlas-search-vector-search.txt create mode 100644 docs/fundamentals/atlas-search.txt create mode 100644 docs/fundamentals/vector-search.txt diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index 0959791c5..bfe25a668 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -20,7 +20,8 @@ Fundamentals Read Operations Write Operations Aggregation Builder - Atlas Search & Vector Search + Atlas Search + Atlas Vector Search Learn more about the following concepts related to {+odm-long+}: @@ -30,3 +31,4 @@ Learn more about the following concepts related to {+odm-long+}: - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-aggregation-builder` - :ref:`laravel-atlas-search-avs` +- :ref:`laravel-vector-search` diff --git a/docs/fundamentals/atlas-search-vector-search.txt b/docs/fundamentals/atlas-search-vector-search.txt deleted file mode 100644 index eadd1bcbc..000000000 --- a/docs/fundamentals/atlas-search-vector-search.txt +++ /dev/null @@ -1,340 +0,0 @@ -.. _laravel-atlas-search-avs: - -============================ -Atlas Search & Vector Search -============================ - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, semantic, embeddings, 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 and Vector Search features. {+odm-long+} -provides an API to use these features directly with your models. - -To learn more about these features, see the following pages in the Atlas -documentation: - -- :atlas:`Atlas Search Overview ` -- :atlas:`Atlas Vector Search Overview ` - -.. note:: Deployment Compatibility - - You can use the Atlas Search and Vector Search features only when - you connect to MongoDB Atlas clusters. These features are not - available for self-managed deployments. - -This page describes how to create the appropriate indexes for each type -of search and provides examples of how to use the {+odm-short+} to -perform searches. - -.. note:: Aggregation Builder - - You might not be able to use the methods described in - this guide for every type of Atlas Search or Vector Search query. - For more complex use cases, create an aggregation pipeline by using - the :ref:`laravel-aggregation-builder`. - -Atlas Search ------------- - -In this section, you can learn how to create Atlas Search indexes -and perform searches in the {+odm-short+}. The Atlas Search API -internally uses the ``$search`` aggregation operator to perform queries. -To learn more about this operator, see the :atlas:`$search -` reference in the Atlas documentation. - -.. _laravel-as-index: - -Create an Atlas Search Index -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. TODO in DOCSP-46230 - -Perform Queries -~~~~~~~~~~~~~~~ - -In this section, you can learn how to use the Atlas Search API in the -{+odm-short+}. - -General Queries -``````````````` - -The {+odm-short+} provides the ``search()`` method as a query -builder method and as an Eloquent model method. You can use the -``search()`` method to run Atlas Search queries on documents in your -collections. - -You must pass an ``operator`` parameter to the ``search()`` method that -is an instance of ``SearchOperatorInterface`` or an array that contains -the operator type, field name, and query value. You can -create an instance of ``SearchOperatorInterface`` by calling the -``Search::text()`` method and passing the field you are -querying and your search term or phrase. - -You must include the following import statement in your application to -create a ``SearchOperatorInterface`` instance: - -.. code-block:: php - - use MongoDB\Builder\Search; - -The following code performs an Atlas Search query that searches for the -term ``'dream'`` in the ``title`` field values of documents in the -``movies`` collection: - -.. io-code-block:: - :copyable: true - - .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php - :language: php - :dedent: - :start-after: start-search-query - :end-before: end-search-query - - .. output:: - :language: json - :visible: false - - [ - { "title": "Dreaming of Jakarta", - "year": 1990 - }, - { "title": "See You in My Dreams", - "year": 1996 - } - ] - -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 - - * - Parameter - - Type - - * - ``index`` - - ``string`` - - * - ``highlight`` - - ``array`` - - * - ``concurrent`` - - ``bool`` - - * - ``count`` - - ``string`` - - * - ``searchAfter`` - - ``string`` - - * - ``searchBefore`` - - ``string`` - - * - ``scoreDetails`` - - ``bool`` - - * - ``sort`` - - ``array`` - - * - ``returnStoredSource`` - - ``bool`` - - * - ``tracking`` - - ``array`` - -To learn more about these parameters, see the :atlas:`Fields -` section of the -``$search`` operator reference in the Atlas documentation. - -Autocomplete Queries -```````````````````` - -The {+odm-short+} provides the ``autocomplete()`` method as a query -builder method and as an Eloquent model method. You can use the -``autocomplete()`` method to run autocomplete searches on documents in your -collections. This method returns only the values of the field you -specify as the query path. - -To learn more about this type of Atlas Search query, see the -:atlas:`autocomplete ` reference in the -Atlas documentation. - -.. note:: - - You must create an Atlas Search index with an autocomplete configuration - on your collection before you can perform autocomplete searches. See the - :ref:`laravel-as-index` section of this guide to learn more about - creating Search indexes. - -The following code performs an Atlas Search autocomplete query for the -string ``"jak"`` on the ``title`` field: - -.. io-code-block:: - :copyable: true - - .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php - :language: php - :dedent: - :start-after: start-auto-query - :end-before: end-auto-query - - .. output:: - :language: json - :visible: false - - [ - "Dreaming of Jakarta", - "Jakob the Liar", - "Emily Calling Jake" - ] - -You can also pass the following optional parameters to the ``autocomplete()`` -method to customize the query: - -.. list-table:: - :header-rows: 1 - - * - Parameter - - Type - - Default Value - - * - ``fuzzy`` - - ``bool`` or ``array`` - - ``false`` - - * - ``tokenOrder`` - - ``string`` - - ``'any'`` - -To learn more about these parameters, see the :atlas:`Options -` section of the -``autocomplete`` operator reference in the Atlas documentation. - -Atlas Vector Search -------------------- - -In this section, you can learn how to create Atlas Vector Search indexes -and perform searches in the {+odm-short+}. The Atlas Vector Search API -internally uses the ``$vectorSearch`` aggregation operator to perform queries. -To learn more about this operator, see the :atlas:`$vectorSearch -` -reference in the Atlas documentation. - -.. _laravel-avs-index: - -Create an Atlas Vector Search Index -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. TODO in DOCSP-46230 - -Perform Queries -~~~~~~~~~~~~~~~ - -In this section, you can learn how to use the Atlas Vector Search API in -the {+odm-short+}. The {+odm-short+} provides the ``vectorSearch()`` -method as a query builder method and as an Eloquent model method. You -can use the ``vectorSearch()`` method to run Atlas Vector Search queries -on documents in your collections. - -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 - -The following code uses the ``vector`` index created in the preceding -:ref:`laravel-avs-index` section to perform an Atlas Vector Search query on the -``movies`` collection: - -.. io-code-block:: - :copyable: true - - .. input:: - :language: php - - $movies = Book::vectorSearch( - index: 'vector', - path: 'vector_embeddings', - // Vector representation of the query `coming of age` - queryVector: [-0.0016261312, -0.028070757, ...], - limit: 3, - ); - - .. output:: - :language: json - :visible: false - - [ - { "title": "Sunrising", - "plot": "A shy teenager discovers confidence and new friendships during a transformative summer camp experience." - }, - { "title": "Last Semester", - "plot": "High school friends navigate love, identity, and unexpected challenges before graduating together." - } - ] - -You can use the ``vector()`` 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 - - * - Parameter - - Type - - Default Value - - * - ``exact`` - - ``bool`` - - ``false`` - - * - ``filter`` - - ``QueryInterface`` or ``array`` - - no filtering - - * - ``numCandidates`` - - ``int`` or ``null`` - - ``null`` - -.. note:: - - To construct a ``QueryInterface`` instance, you must import the - ``MongoDB\Builder\Query`` class into your application. - -To learn more about these parameters, see the :atlas:`Fields -` section of the -``$vectorSearch`` operator reference in the Atlas documentation. diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt new file mode 100644 index 000000000..c6f17c72e --- /dev/null +++ b/docs/fundamentals/atlas-search.txt @@ -0,0 +1,245 @@ +.. _laravel-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. {+odm-long+} provides an API to +perform Atlas Search queries directly with your models. + +To learn more about Atlas Search, see the :atlas:`Overview +` in the +Atlas documentation. + +.. 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. + +This page describes how to create Atlas Search indexes and provides +examples of how to use the {+odm-short+} to perform searches. + +.. note:: Aggregation Builder + + 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, create an aggregation pipeline by using + the :ref:`laravel-aggregation-builder`. + +The Atlas Search API internally uses the ``$search`` aggregation +operator to perform queries. To learn more about this operator, see the +:atlas:`$search ` reference in +the Atlas documentation. + +.. tip:: Atlas Vector Search + + To perform searches on vector embeddings in MongoDB, you can use the + {+odm-long+} Atlas Vector Search API. To learn about this feature, see + the :ref:`laravel-vector-search` guide. + +.. _laravel-as-index: + +Create an Atlas Search Index +---------------------------- + +.. TODO in DOCSP-46230 + +Perform Queries +--------------- + +In this section, you can learn how to use the Atlas Search API in the +{+odm-short+}. + +General Queries +~~~~~~~~~~~~~~~ + +The {+odm-short+} provides the ``search()`` method as a query +builder method and as an Eloquent model method. You can use the +``search()`` method to run Atlas Search queries on documents in your +collections. + +You must pass an ``operator`` parameter to the ``search()`` method that +is an instance of ``SearchOperatorInterface`` or an array that contains +the operator type, field name, and query value. You can +create an instance of ``SearchOperatorInterface`` by calling the +``Search::text()`` method and passing the field you are +querying and your search term or phrase. + +You must include the following import statement in your application to +create a ``SearchOperatorInterface`` instance: + +.. code-block:: php + + use MongoDB\Builder\Search; + +The following code performs an Atlas Search query on the ``Movie`` +model's ``title`` field for the term ``'dream'``: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php + :language: php + :dedent: + :start-after: start-search-query + :end-before: end-search-query + + .. output:: + :language: json + :visible: false + + [ + { "title": "Dreaming of Jakarta", + "year": 1990 + }, + { "title": "See You in My Dreams", + "year": 1996 + } + ] + +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. + +Autocomplete Queries +~~~~~~~~~~~~~~~~~~~~ + +The {+odm-short+} provides the ``autocomplete()`` method as a query +builder method and as an Eloquent model method. You can use the +``autocomplete()`` method to run autocomplete searches on documents in your +collections. This method returns only the values of the field you +specify as the query path. + +To learn more about this type of Atlas Search query, see the +:atlas:`autocomplete ` reference in the +Atlas documentation. + +.. note:: + + You must create an Atlas Search index with an autocomplete configuration + on your collection before you can perform autocomplete searches. See the + :ref:`laravel-as-index` section of this guide to learn more about + creating Search indexes. + +The following code performs an Atlas Search autocomplete query for the +string ``"jak"`` on the ``title`` field: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php + :language: php + :dedent: + :start-after: start-auto-query + :end-before: end-auto-query + + .. output:: + :language: json + :visible: false + + [ + "Dreaming of Jakarta", + "Jakob the Liar", + "Emily Calling Jake" + ] + +You can also pass the following optional parameters to the ``autocomplete()`` +method to customize the query: + +.. list-table:: + :header-rows: 1 + + * - Optional Parameter + - Type + - Description + - Default Value + + * - ``fuzzy`` + - ``bool`` or ``array`` + - Enables fuzzy search and fuzzy search options + - ``false`` + + * - ``tokenOrder`` + - ``string`` + - 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. diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt new file mode 100644 index 000000000..fbc848a0d --- /dev/null +++ b/docs/fundamentals/vector-search.txt @@ -0,0 +1,172 @@ +.. _laravel-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. {+odm-long+} provides an API to +perform Atlas Vector Search queries directly with your models. + +To learn more about Atlas Vector Search, see the :atlas:`Overview +` in the +Atlas documentation. + +.. note:: Deployment Compatibility + + You can use the Atlas Vector Search feature only when + you connect to MongoDB Atlas clusters. This feature is not + available for self-managed deployments. + +This page describes how to create Atlas Vector Search indexes and provides +examples of how to use the {+odm-short+} to perform searches. + +.. note:: Aggregation Builder + + 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, create an aggregation pipeline by using + the :ref:`laravel-aggregation-builder`. + +The Atlas Vector Search API internally uses the ``$search`` aggregation +operator to perform queries. To learn more about this operator, see the +:atlas:`$search ` reference in +the Atlas documentation. + +.. tip:: Atlas Search + + To perform advanced text on your documents, you can use the + {+odm-long+} Atlas Search API. To learn about this feature, see + the :ref:`laravel-atlas-search` guide. + +The Atlas Vector Search API internally uses the ``$vectorSearch`` +aggregation operator to perform queries. To learn more about this +operator, see the :atlas:`$vectorSearch +` +reference in the Atlas documentation. + +.. _laravel-avs-index: + +Create an Atlas Vector Search Index +----------------------------------- + +.. TODO in DOCSP-46230 + +Perform Queries +--------------- + +In this section, you can learn how to use the Atlas Vector Search API in +the {+odm-short+}. The {+odm-short+} provides the ``vectorSearch()`` +method as a query builder method and as an Eloquent model method. You +can use the ``vectorSearch()`` method to run Atlas Vector Search queries +on documents in your collections. + +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 + +The following code uses the ``vector`` index created in the preceding +:ref:`laravel-avs-index` section to perform an Atlas Vector Search query on the +``movies`` collection: + +.. io-code-block:: + :copyable: true + + .. input:: + :language: php + + $movies = Book::vectorSearch( + index: 'vector', + path: 'vector_embeddings', + // Vector representation of the query `coming of age` + queryVector: [-0.0016261312, -0.028070757, ...], + limit: 3, + ); + + .. output:: + :language: json + :visible: false + + [ + { "title": "Sunrising", + "plot": "A shy teenager discovers confidence and new friendships during a transformative summer camp experience." + }, + { "title": "Last Semester", + "plot": "High school friends navigate love, identity, and unexpected challenges before graduating together." + } + ] + +You can use the ``vector()`` 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 + - Default Value + + * - ``exact`` + - ``bool`` + - Specifies whether to run :term:`ENN` (``true``) or :term:`ANN` + (``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`` + +.. note:: + + To construct a ``QueryInterface`` instance, you must import the + ``MongoDB\Builder\Query`` class into your application. + +To learn more about these parameters, see the :atlas:`Fields +` section of the +``$vectorSearch`` operator reference in the Atlas documentation. \ No newline at end of file From 68bc0b634b3b352d06f8e90a7e99d8b2350b2da8 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 30 Jan 2025 16:23:40 -0500 Subject: [PATCH 15/20] wip --- docs/fundamentals/atlas-search.txt | 26 ++++++++++------------- docs/fundamentals/vector-search.txt | 32 ++++++++++------------------- 2 files changed, 22 insertions(+), 36 deletions(-) diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt index c6f17c72e..9aaa9156b 100644 --- a/docs/fundamentals/atlas-search.txt +++ b/docs/fundamentals/atlas-search.txt @@ -22,11 +22,9 @@ Overview In this guide, you can learn how to perform searches on your documents by using the Atlas Search feature. {+odm-long+} provides an API to -perform Atlas Search queries directly with your models. - -To learn more about Atlas Search, see the :atlas:`Overview -` in the -Atlas documentation. +perform Atlas Search queries directly with your models. This guide +describes how to create Atlas Search indexes and provides examples of +how to use the {+odm-short+} to perform searches. .. note:: Deployment Compatibility @@ -34,22 +32,20 @@ Atlas documentation. you connect to MongoDB Atlas clusters. This feature is not available for self-managed deployments. -This page describes how to create Atlas Search indexes and provides -examples of how to use the {+odm-short+} to perform searches. +To learn more about Atlas Search, see the :atlas:`Overview +` in the +Atlas documentation. The Atlas Search API 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:: Aggregation Builder +.. 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, create an aggregation pipeline by using the :ref:`laravel-aggregation-builder`. - -The Atlas Search API internally uses the ``$search`` aggregation -operator to perform queries. To learn more about this operator, see the -:atlas:`$search ` reference in -the Atlas documentation. - -.. tip:: Atlas Vector Search To perform searches on vector embeddings in MongoDB, you can use the {+odm-long+} Atlas Vector Search API. To learn about this feature, see diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index fbc848a0d..92e8c4f1f 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -22,11 +22,9 @@ Overview In this guide, you can learn how to perform searches on your documents by using the Atlas Vector Search feature. {+odm-long+} provides an API to -perform Atlas Vector Search queries directly with your models. - -To learn more about Atlas Vector Search, see the :atlas:`Overview -` in the -Atlas documentation. +perform Atlas Vector Search queries directly with your models. This guide +describes how to create Atlas Vector Search indexes and provides +examples of how to use the {+odm-short+} to perform searches. .. note:: Deployment Compatibility @@ -34,33 +32,25 @@ Atlas documentation. you connect to MongoDB Atlas clusters. This feature is not available for self-managed deployments. -This page describes how to create Atlas Vector Search indexes and provides -examples of how to use the {+odm-short+} to perform searches. +To learn more about Atlas Vector Search, see the :atlas:`Overview +` in the +Atlas documentation. The Atlas Vector Search API 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:: Aggregation Builder +.. 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, create an aggregation pipeline by using the :ref:`laravel-aggregation-builder`. - -The Atlas Vector Search API internally uses the ``$search`` aggregation -operator to perform queries. To learn more about this operator, see the -:atlas:`$search ` reference in -the Atlas documentation. - -.. tip:: Atlas Search To perform advanced text on your documents, you can use the {+odm-long+} Atlas Search API. To learn about this feature, see the :ref:`laravel-atlas-search` guide. -The Atlas Vector Search API internally uses the ``$vectorSearch`` -aggregation operator to perform queries. To learn more about this -operator, see the :atlas:`$vectorSearch -` -reference in the Atlas documentation. - .. _laravel-avs-index: Create an Atlas Vector Search Index From 146cfae6748e13314bf995ea0830423a1d7cfac2 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 30 Jan 2025 16:24:58 -0500 Subject: [PATCH 16/20] wip --- docs/fundamentals.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index bfe25a668..dafc427c3 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -30,5 +30,5 @@ Learn more about the following concepts related to {+odm-long+}: - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-aggregation-builder` -- :ref:`laravel-atlas-search-avs` +- :ref:`laravel-atlas-search` - :ref:`laravel-vector-search` From e1c2f9ae0658636174aa87de71b766cced4425c3 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 31 Jan 2025 15:40:58 -0500 Subject: [PATCH 17/20] fix term links --- docs/fundamentals/vector-search.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index 92e8c4f1f..d5efc7417 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -137,8 +137,8 @@ following optional parameters to ``search()``: * - ``exact`` - ``bool`` - - Specifies whether to run :term:`ENN` (``true``) or :term:`ANN` - (``false``) search + - Specifies whether to run an Exact Nearest Neighbor (``true``) or + Approximate Nearest Neighbor (``false``) search - ``false`` * - ``filter`` From a9193d8c67641acf3aba07daad19d35c328b73ed Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 14:56:23 -0500 Subject: [PATCH 18/20] fixes --- docs/fundamentals/vector-search.txt | 102 ++++++++++++++-------------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index d5efc7417..e4318387c 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -35,9 +35,9 @@ examples of how to use the {+odm-short+} to perform searches. To learn more about Atlas Vector Search, see the :atlas:`Overview ` in the Atlas documentation. The Atlas Vector Search API internally uses the -``$search`` aggregation operator to perform queries. To learn more about -this operator, see the :atlas:`$search -` reference in the Atlas +``$vectorSearch`` aggregation operator to perform queries. To learn more about +this operator, see the :atlas:`$vectorSearch +` reference in the Atlas documentation. .. note:: @@ -47,7 +47,7 @@ documentation. For more complex use cases, create an aggregation pipeline by using the :ref:`laravel-aggregation-builder`. - To perform advanced text on your documents, you can use the + To perform advanced full-text searches on your documents, you can use the {+odm-long+} Atlas Search API. To learn about this feature, see the :ref:`laravel-atlas-search` guide. @@ -73,24 +73,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 The following code uses the ``vector`` index created in the preceding :ref:`laravel-avs-index` section to perform an Atlas Vector Search query on the @@ -100,57 +100,57 @@ The following code uses the ``vector`` index created in the preceding :copyable: true .. input:: - :language: php + :language: php - $movies = Book::vectorSearch( - index: 'vector', - path: 'vector_embeddings', - // Vector representation of the query `coming of age` - queryVector: [-0.0016261312, -0.028070757, ...], - limit: 3, - ); + $movies = Book::vectorSearch( + index: 'vector', + path: 'vector_embeddings', + // Vector representation of the query `coming of age` + queryVector: [-0.0016261312, -0.028070757, ...], + limit: 3, + ); .. output:: - :language: json - :visible: false - - [ - { "title": "Sunrising", - "plot": "A shy teenager discovers confidence and new friendships during a transformative summer camp experience." - }, - { "title": "Last Semester", - "plot": "High school friends navigate love, identity, and unexpected challenges before graduating together." - } - ] - -You can use the ``vector()`` method to perform many types of Atlas + :language: json + :visible: false + + [ + { "title": "Sunrising", + "plot": "A shy teenager discovers confidence and new friendships during a transformative summer camp experience." + }, + { "title": "Last Semester", + "plot": "High school friends navigate love, identity, and unexpected challenges before graduating together." + } + ] + +You can use the ``vectorSearch()`` method to perform many types of Atlas Search queries. Depending on your desired query, you can pass the -following optional parameters to ``search()``: +following optional parameters to ``vectorSearch()``: .. list-table:: :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`` .. note:: @@ -159,4 +159,4 @@ following optional parameters to ``search()``: To learn more about these parameters, see the :atlas:`Fields ` section of the -``$vectorSearch`` operator reference in the Atlas documentation. \ No newline at end of file +``$vectorSearch`` operator reference in the Atlas documentation. From 0d226c0e6adfa54a0d65ecd806d6a7021f02976c Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 15:07:22 -0500 Subject: [PATCH 19/20] JT small fixes --- docs/fundamentals/vector-search.txt | 2 +- docs/includes/fundamentals/as-avs/AtlasSearchTest.php | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index e4318387c..40bd22ae7 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -81,7 +81,7 @@ You must pass the following parameters to the ``vectorSearch()`` method: - Name of the vector search index * - ``path`` - - ``array`` or ``string`` + - ``string`` - Field that stores vector embeddings * - ``queryVector`` diff --git a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php index 161e273b3..1d9336f76 100644 --- a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php +++ b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php @@ -116,8 +116,7 @@ public function testSimpleSearch(): void public function autocompleteSearchTest(): void { // start-auto-query - $movies = Movie::autocomplete('title', 'jak') - ->get(); + $movies = Movie::autocomplete('title', 'jak')->get(); // end-auto-query $this->assertNotNull($movies); @@ -145,8 +144,7 @@ public function vectorSearchTest(): void $this->assertSame('C', $results->first()->title); } - /** Generates random vectors using fixed seed to make tests - * deterministic */ + /** Generates random vectors using fixed seed to make tests deterministic */ private function addVector(array $items): array { srand(1); From ef2f583d7c612ffc6231bad3f598ec35eb975712 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 15:12:08 -0500 Subject: [PATCH 20/20] indentation fix --- docs/fundamentals/vector-search.txt | 86 ++++++++++++++--------------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index 40bd22ae7..116cb75a0 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -73,24 +73,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`` - - ``string`` - - Field that stores vector embeddings + - ``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 The following code uses the ``vector`` index created in the preceding :ref:`laravel-avs-index` section to perform an Atlas Vector Search query on the @@ -100,28 +100,28 @@ The following code uses the ``vector`` index created in the preceding :copyable: true .. input:: - :language: php + :language: php - $movies = Book::vectorSearch( - index: 'vector', - path: 'vector_embeddings', - // Vector representation of the query `coming of age` - queryVector: [-0.0016261312, -0.028070757, ...], - limit: 3, - ); + $movies = Book::vectorSearch( + index: 'vector', + path: 'vector_embeddings', + // Vector representation of the query `coming of age` + queryVector: [-0.0016261312, -0.028070757, ...], + limit: 3, + ); .. output:: - :language: json - :visible: false - - [ - { "title": "Sunrising", - "plot": "A shy teenager discovers confidence and new friendships during a transformative summer camp experience." - }, - { "title": "Last Semester", - "plot": "High school friends navigate love, identity, and unexpected challenges before graduating together." - } - ] + :language: json + :visible: false + + [ + { "title": "Sunrising", + "plot": "A shy teenager discovers confidence and new friendships during a transformative summer camp experience." + }, + { "title": "Last Semester", + "plot": "High school friends navigate love, identity, and unexpected challenges before graduating together." + } + ] You can use the ``vectorSearch()`` method to perform many types of Atlas Search queries. Depending on your desired query, you can pass the @@ -131,26 +131,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`` .. note::