From afa8a800836823668ecedff8cfa69a822b0c1528 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 9 Jan 2025 10:44:53 -0500 Subject: [PATCH 1/5] DOCSP-45096: binaryvector type for avs --- snooty.toml | 1 + source/fundamentals/builders.txt | 2 - source/fundamentals/builders/aggregates.txt | 51 +--------- .../fundamentals/builders/vector-search.txt | 93 +++++++++++++++++++ source/fundamentals/indexes.txt | 2 +- .../code-snippets/builders/AggBuilders.java | 13 ++- source/whats-new.txt | 2 +- 7 files changed, 112 insertions(+), 52 deletions(-) create mode 100644 source/fundamentals/builders/vector-search.txt diff --git a/snooty.toml b/snooty.toml index 04531be85..d4aee235c 100644 --- a/snooty.toml +++ b/snooty.toml @@ -12,6 +12,7 @@ toc_landing_pages = [ "/fundamentals/builders", "/fundamentals/aggregation", "/usage-examples", + "/fundamentals/builders/aggregates", ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index ee1e92425..66709ed64 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -4,8 +4,6 @@ Builders ======== -.. default-domain:: mongodb - .. toctree:: Aggregation diff --git a/source/fundamentals/builders/aggregates.txt b/source/fundamentals/builders/aggregates.txt index c26983249..f6e465f85 100644 --- a/source/fundamentals/builders/aggregates.txt +++ b/source/fundamentals/builders/aggregates.txt @@ -15,6 +15,10 @@ Aggregates Builders :depth: 2 :class: singlecol +.. toctree:: + + Atlas Vector Search + .. _aggregates-builders: Overview @@ -182,7 +186,6 @@ value of the ``title`` field: :language: java :dedent: - Skip ---- @@ -980,49 +983,3 @@ aggregation stage: Learn more about this helper from the `searchMeta() API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchCollector)>`__. - -.. _java-atlas-vector-search: - -Atlas Vector Search -------------------- - -.. important:: - - To learn what versions of MongoDB Atlas support this feature, see - :atlas:`Limitations ` - in the MongoDB Atlas documentation. - -Use the ``vectorSearch()`` method to create a :atlas:`$vectorSearch -` -pipeline stage that specifies a **semantic search**. A semantic search is -a type of search which locates information that is similar in meaning. - -To use this feature, you must set up a vector search index and index your -vector embeddings. To learn about how to programmatically create a -vector search index, see the :ref:`java-search-indexes` section in the Indexes guide. To -learn more about vector embeddings, see -:atlas:`How to Index Vector Embeddings for Vector Search -`. - -The following example shows how to build an aggregation pipeline that uses the -``vectorSearch()`` and ``project()`` methods to compute a vector search score: - -.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java - :start-after: // begin vectorSearch - :end-before: // end vectorSearch - :language: java - :dedent: - -The following example shows how you can print the score from the result of the -preceding aggregation pipeline: - -.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java - :start-after: // begin vectorSearch-output - :end-before: // end vectorSearch-output - :language: java - :dedent: - -Learn more about this helper in the -`vectorSearch() -<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#vectorSearch(com.mongodb.client.model.search.FieldSearchPath,java.lang.Iterable,java.lang.String,long,com.mongodb.client.model.search.VectorSearchOptions)>`__ -API documentation. diff --git a/source/fundamentals/builders/vector-search.txt b/source/fundamentals/builders/vector-search.txt new file mode 100644 index 000000000..43af78641 --- /dev/null +++ b/source/fundamentals/builders/vector-search.txt @@ -0,0 +1,93 @@ +.. _java-atlas-vector-search: + +=================== +Atlas Vector Search +=================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, semantic, nearest + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the :atlas:`Atlas Vector Search +` feature +in the {+driver-short+}. The ``Aggregates`` builders class provides the +the ``vectorSearch()`` helper method that you can use to +create a :atlas:`$vectorSearch ` +pipeline stage. This pipeline stage allows you to perform a **semantic +search** on your documents. A semantic search is a type of search which +locates information that is similar in meaning to your provided search +term or phrase. + +.. important:: Feature Compatibility + + To learn what versions of MongoDB Atlas support this feature, see + :atlas:`Limitations ` + in the MongoDB Atlas documentation. + +Perform a Vector Search +----------------------- + +To use this feature, you must create a vector search index and index your +vector embeddings. To learn about how to programmatically create a +vector search index, see the :ref:`java-search-indexes` section in the +Indexes guide. To learn more about vector embeddings, see +:atlas:`How to Index Vector Embeddings for Vector Search +` in the Atlas documentation. + +After you create a vector search index on your vector embeddings, you +can reference this index in your pipeline stage, as shown in the +following section. + +Vector Search Examples +~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to build an aggregation pipeline that uses the +``vectorSearch()`` and ``project()`` methods to compute a vector search score: + +.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java + :start-after: // begin vectorSearch + :end-before: // end vectorSearch + :language: java + :dedent: + +The following example shows how you can run the aggregation and print +the vector search meta-score from the result of the preceding +aggregation pipeline: + +.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java + :start-after: // begin vectorSearch-output + :end-before: // end vectorSearch-output + :language: java + :dedent: + +API Documentation +----------------- + +To learn more about the methods and types mentioned in this +guide, see the following API documentation: + +- `Aggregates.vectorSearch() + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#vectorSearch(com.mongodb.client.model.search.FieldSearchPath,java.lang.Iterable,java.lang.String,long,com.mongodb.client.model.search.VectorSearchOptions)>`__ + +- `FieldSearchPath + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/FieldSearchPath.html>`__ + +- `VectorSearchOptions + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/VectorSearchOptions.html>`__ + +- `Projections.metaVectorSearchScore() + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Projections.html#metaVectorSearchScore(java.lang.String)>`__ + +.. TODO add BinaryVector API link diff --git a/source/fundamentals/indexes.txt b/source/fundamentals/indexes.txt index 300b20fb3..e38d9d7b0 100644 --- a/source/fundamentals/indexes.txt +++ b/source/fundamentals/indexes.txt @@ -220,7 +220,7 @@ Search, see the :atlas:`Atlas Search Indexes Atlas Vector Search enables you to perform semantic searches on vector embeddings stored in MongoDB Atlas. To learn more about Atlas Vector Search, see the -:ref:`java-atlas-vector-search` section in the Aggregates Builder guide. +:ref:`java-atlas-vector-search` guide. You can call the following methods on a collection to manage your Atlas Search and Vector Search indexes: diff --git a/source/includes/fundamentals/code-snippets/builders/AggBuilders.java b/source/includes/fundamentals/code-snippets/builders/AggBuilders.java index 9eef15a05..abd664177 100644 --- a/source/includes/fundamentals/code-snippets/builders/AggBuilders.java +++ b/source/includes/fundamentals/code-snippets/builders/AggBuilders.java @@ -314,12 +314,23 @@ private void matchStage() { private void vectorSearchPipeline() { // begin vectorSearch - List queryVector = (asList(-0.0072121937, -0.030757688, -0.012945653)); + // Create an instance of the BinaryVector class as the query vector + BinaryVector queryVector = BinaryVector.floatVector( + new float[]{0.0001f, 1.12345f, 2.23456f, 3.34567f, 4.45678f}); + + // Specify the index name for the vector embedding index String indexName = "mflix_movies_embedding_index"; + + // Specify the path of the field to search on FieldSearchPath fieldSearchPath = fieldPath("plot_embedding"); + + // Limit the number of matches to 1 int limit = 1; + + // Create a pre-filter to only search within a subset of documents VectorSearchOptions options = exactVectorSearchOptions().filter(gte("year", 2016)); + // Create the vectorSearch pipeline stage List pipeline = asList( vectorSearch( fieldSearchPath, diff --git a/source/whats-new.txt b/source/whats-new.txt index 0ededd787..e5c95c0c3 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -43,7 +43,7 @@ and features: .. replacement:: vector-type-example-link To learn about how to use this type when using the Atlas - Vector Search feature, see the TODO add link :ref:`` guide. + Vector Search feature, see the :ref:`java-atlas-vector-search` guide. - Adds a client bulk write API that allows you to perform write operations on multiple databases and collections at once. To learn more about this feature, see the From 23608bc31a1d9356293f783de2680dea33fd2002 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 9 Jan 2025 10:52:11 -0500 Subject: [PATCH 2/5] wip --- source/fundamentals/builders/vector-search.txt | 11 +++++++++-- .../code-snippets/builders/AggBuilders.java | 3 ++- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/builders/vector-search.txt b/source/fundamentals/builders/vector-search.txt index 43af78641..d3ac009cd 100644 --- a/source/fundamentals/builders/vector-search.txt +++ b/source/fundamentals/builders/vector-search.txt @@ -50,8 +50,8 @@ After you create a vector search index on your vector embeddings, you can reference this index in your pipeline stage, as shown in the following section. -Vector Search Examples -~~~~~~~~~~~~~~~~~~~~~~ +Vector Search Example +~~~~~~~~~~~~~~~~~~~~~ The following example shows how to build an aggregation pipeline that uses the ``vectorSearch()`` and ``project()`` methods to compute a vector search score: @@ -62,6 +62,13 @@ The following example shows how to build an aggregation pipeline that uses the :language: java :dedent: +.. tip:: Query Vector Type + + The preceding example creates an instance of ``BinaryVector`` to + serve as the query vector, but you can also create a ``List`` of + ``Double`` instances. However, we recommend that you use the + ``BinaryVector`` type to improve storage efficiency. + The following example shows how you can run the aggregation and print the vector search meta-score from the result of the preceding aggregation pipeline: diff --git a/source/includes/fundamentals/code-snippets/builders/AggBuilders.java b/source/includes/fundamentals/code-snippets/builders/AggBuilders.java index abd664177..fcd294cae 100644 --- a/source/includes/fundamentals/code-snippets/builders/AggBuilders.java +++ b/source/includes/fundamentals/code-snippets/builders/AggBuilders.java @@ -328,7 +328,8 @@ private void vectorSearchPipeline() { int limit = 1; // Create a pre-filter to only search within a subset of documents - VectorSearchOptions options = exactVectorSearchOptions().filter(gte("year", 2016)); + VectorSearchOptions options = exactVectorSearchOptions() + .filter(gte("year", 2016)); // Create the vectorSearch pipeline stage List pipeline = asList( From 191e5705c7f67247150486918ff0bdfda355d2b8 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 9 Jan 2025 10:56:07 -0500 Subject: [PATCH 3/5] cross link --- source/fundamentals/builders/vector-search.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/fundamentals/builders/vector-search.txt b/source/fundamentals/builders/vector-search.txt index d3ac009cd..509b72680 100644 --- a/source/fundamentals/builders/vector-search.txt +++ b/source/fundamentals/builders/vector-search.txt @@ -79,6 +79,12 @@ aggregation pipeline: :language: java :dedent: +.. tip:: Java Driver Vector Search Examples + + Visit the :atlas:`Atlas documentation ` + to find more tutorials on using the {+driver-short+} to perform Atlas + Vector Searches. + API Documentation ----------------- From c54ae42e6189e16eeb6f249f0e6dcc3f55181825 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 9 Jan 2025 11:57:29 -0500 Subject: [PATCH 4/5] RM PR fixes 1 --- source/fundamentals/builders/vector-search.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/builders/vector-search.txt b/source/fundamentals/builders/vector-search.txt index 509b72680..438f2de1c 100644 --- a/source/fundamentals/builders/vector-search.txt +++ b/source/fundamentals/builders/vector-search.txt @@ -27,8 +27,8 @@ the ``vectorSearch()`` helper method that you can use to create a :atlas:`$vectorSearch ` pipeline stage. This pipeline stage allows you to perform a **semantic search** on your documents. A semantic search is a type of search which -locates information that is similar in meaning to your provided search -term or phrase. +locates information that is similar in meaning, but not necessarily +identical, to your provided search term or phrase. .. important:: Feature Compatibility From 12e44f8321aeaf3fbe93f318d8ee0771246a080d Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 13 Jan 2025 11:09:15 -0500 Subject: [PATCH 5/5] add api links --- source/fundamentals/builders/vector-search.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/builders/vector-search.txt b/source/fundamentals/builders/vector-search.txt index 438f2de1c..550763494 100644 --- a/source/fundamentals/builders/vector-search.txt +++ b/source/fundamentals/builders/vector-search.txt @@ -103,4 +103,4 @@ guide, see the following API documentation: - `Projections.metaVectorSearchScore() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Projections.html#metaVectorSearchScore(java.lang.String)>`__ -.. TODO add BinaryVector API link +- `BinaryVector <{+api+}/apidocs/bson/org/bson/BinaryVector.html>`__