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..550763494 --- /dev/null +++ b/source/fundamentals/builders/vector-search.txt @@ -0,0 +1,106 @@ +.. _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, but not necessarily +identical, 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 Example +~~~~~~~~~~~~~~~~~~~~~ + +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: + +.. 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: + +.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java + :start-after: // begin vectorSearch-output + :end-before: // end vectorSearch-output + :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 +----------------- + +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)>`__ + +- `BinaryVector <{+api+}/apidocs/bson/org/bson/BinaryVector.html>`__ 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..fcd294cae 100644 --- a/source/includes/fundamentals/code-snippets/builders/AggBuilders.java +++ b/source/includes/fundamentals/code-snippets/builders/AggBuilders.java @@ -314,12 +314,24 @@ 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; - VectorSearchOptions options = exactVectorSearchOptions().filter(gte("year", 2016)); + // 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