diff --git a/snooty.toml b/snooty.toml index 785497cd..1073a6bb 100644 --- a/snooty.toml +++ b/snooty.toml @@ -8,7 +8,8 @@ toc_landing_pages = [ "/fundamentals/crud/write-operations/update-many", "/fundamentals/authentication", "/upgrade", - "/fundamentals/database-collection" + "/fundamentals/database-collection", + "/fundamentals/indexes", ] name = "csharp" title = "C#/.NET Driver" diff --git a/source/fundamentals/indexes.txt b/source/fundamentals/indexes.txt index a2542b3c..2bab9b68 100644 --- a/source/fundamentals/indexes.txt +++ b/source/fundamentals/indexes.txt @@ -17,6 +17,10 @@ Indexes :depth: 2 :class: singlecol +.. toctree:: + + Atlas Search & Vector Search Indexes + Overview -------- @@ -198,57 +202,6 @@ To learn more, see :manual:`Clustered Indexes ` and :manual:`Clustered Collections ` in the Server manual. -.. _search-indexes: - -Atlas Search Indexes -~~~~~~~~~~~~~~~~~~~~ - -The Atlas Search feature enables you to perform full-text searches on collections hosted -on MongoDB Atlas. The indexes specify the behavior of the search and which fields to -index. - -To learn more about MongoDB Atlas Search, see the :atlas:`Atlas Search Indexes ` -documentation. - -.. note:: - - The Atlas Search Index management methods run asynchronously. The - driver methods can return before confirming that they ran - successfully. To determine the current status of the indexes, call the - `IMongoSearchIndexManager.List() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Search.IMongoSearchIndexManager.List.html>`__ method. - -The following sections contain links to tutorials that demonstrate how to create and -interact with Atlas Search indexes. - -Create a Search Index -+++++++++++++++++++++ - -Before you can perform a search on an Atlas collection, you must first -create an Atlas Search index on the collection. To learn how to create an Atlas Search -index using the {+driver-short+}, see :atlas:`Create an Atlas Search Index ` -in the Atlas manual and select :guilabel:`C#` from the language dropdown. - -List Search Indexes -+++++++++++++++++++ - -To learn how to view a list of your Atlas Search indexes using the {+driver-short+}, see -:atlas:`View an Atlas Search Index ` in the Atlas manual -and select :guilabel:`C#` from the language dropdown. - -Update a Search Index -+++++++++++++++++++++ - -To learn how to modify an existing Atlas Search index using the {+driver-short+}, see -:atlas:`Edit an Atlas Search Index ` in the Atlas manual -and select :guilabel:`C#` from the language dropdown. - -Drop a Search Index -+++++++++++++++++++ - -To learn how to delete an Atlas Search index using the {+driver-short+}, see -:atlas:`Delete an Atlas Search Index ` in the Atlas manual -and select :guilabel:`C#` from the language dropdown. - Text Indexes ~~~~~~~~~~~~ diff --git a/source/fundamentals/indexes/search-indexes.txt b/source/fundamentals/indexes/search-indexes.txt new file mode 100644 index 00000000..1d68349b --- /dev/null +++ b/source/fundamentals/indexes/search-indexes.txt @@ -0,0 +1,326 @@ +.. _csharp-atlas-search-indexes: +.. _search-indexes: + +====================================== +Atlas Search and Vector Search Indexes +====================================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, full text, atlas deployment, text search, embeddings + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to create and manage **Atlas Search and +Vector Search indexes**. These indexes allow you to use the following +features: + +- :ref:`Atlas Search `: Perform fast, full-text + searches + +- :ref:`Atlas Vector Search `: Perform + semantic (similarity) searches on vector embeddings + +Atlas Search and Vector Search indexes specify which fields to index, +specify how these fields are indexed, and set other optional +configurations. + +.. note:: + + Atlas Search index-management methods run asynchronously. The + driver methods can return a result before the desired action + completes on the server. + +This guide explains how to perform the following actions to manage your +Atlas Search and Vector Search indexes: + +- :ref:`csharp-create-model` +- :ref:`csharp-create-search-index` +- :ref:`csharp-create-search-indexes` +- :ref:`csharp-list-search-index` +- :ref:`csharp-update-search-index` +- :ref:`csharp-drop-search-index` + +.. note:: Sample Data + + The examples in this guide use the ``embedded_movies`` collection + in the ``sample_mflix`` database, which is one of the Atlas sample + datasets. For instructions on importing the Atlas sample data, see + :atlas:`Load Sample Data ` in the Atlas documentation. + +.. _csharp-create-model: + +Create a Search Index Model +--------------------------- + +To create an Atlas Search or Vector Search index, you must first build a +``CreateSearchIndexModel`` instance that sets your index specifications. + +The ``CreateSearchIndexModel`` has the following properties: + +.. list-table:: + :header-rows: 1 + :widths: 25 25 50 + + * - Property + - Type + - Description + + * - ``definition`` + - ``BsonDocument`` + - Specifies the index definition. If you omit this setting, the + driver creates an Atlas Search index with dynamic mappings. + + * - ``name`` + - ``string`` + - Sets the index name. If you omit this setting, the + driver sets the name to ``default``. + + * - ``type`` + - ``SearchIndexType`` + - Sets the index type. If you omit this setting, the + driver creates an Atlas Search index by default. + +To learn more about Atlas Search field mappings, see :atlas:`Define Field Mappings +` in the Atlas documentation. + +To learn more about defining Atlas Vector Search indexes, see +:atlas:`How to Index Fields for Vector Search +` in the Atlas documentation. + +Example Models +~~~~~~~~~~~~~~ + +The following example creates a ``CreateSearchIndexModel`` instance to provide +specifications for an index named ``search_idx``. The code specifies static +mappings of the ``title`` and ``released`` fields: + +.. literalinclude:: /includes/fundamentals/code-examples/SearchIndexes.cs + :start-after: begin-as-model + :end-before: end-as-model + :language: csharp + :dedent: + +The following example creates a ``CreateSearchIndexModel`` instance to provide +specifications for an index named ``vs_idx``. The code specifies the +embedding path as ``plot_embedding``, indexes ``1536`` dimensions, and +uses the ``"euclidean"`` vector similarity function: + +.. literalinclude:: /includes/fundamentals/code-examples/SearchIndexes.cs + :start-after: begin-avs-model + :end-before: end-avs-model + :language: csharp + :dedent: + +.. _csharp-create-search-index: + +Create a Search Index +--------------------- + +You can create an Atlas Search or Vector Search index on a collection by +calling the ``SearchIndexes.CreateOne()`` method on an ``IMongoCollection`` +instance. This method accepts an index model as a parameter, specified +in a ``CreateSearchIndexModel`` instance. + +Example +~~~~~~~ + +The following example creates an Atlas Search index on the +``embedded_movies`` collection. The code creates a ``CreateSearchIndexModel`` +that sets the index name and enables dynamic mapping. Then, the code +passes the ``CreateSearchIndexModel`` instance to the ``SearchIndexes.CreateOne()`` +method to create the Atlas Search index: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-examples/SearchIndexes.cs + :start-after: begin-atlas-create-one + :end-before: end-atlas-create-one + :language: csharp + :emphasize-lines: 11 + :dedent: + + .. output:: + :language: console + :visible: false + + Created Atlas Search index: + "example_index" + +.. _csharp-create-search-indexes: + +Create Multiple Search Indexes +------------------------------ + +You can create multiple Atlas Search and Vector Search indexes +by calling the ``SearchIndexes.CreateMany()`` method on an ``IMongoCollection`` +instance. This method accepts an ``IEnumerable`` of +``CreateSearchIndexModel`` instances as a parameter. + +Example +~~~~~~~ + +This example performs the following actions: + +1. Creates a ``CreateSearchIndexModel`` instance that specifies an Atlas + Search index named ``as_idx`` + +#. Creates a ``CreateSearchIndexModel`` instance that specifies an Atlas + Vector Search index named ``vs_idx`` + +#. Passes a ``List`` of both ``CreateSearchIndexModel`` instances to + the ``SearchIndexes.CreateMany()`` method + +#. Creates the Atlas Search and Vector Search indexes on the + ``embedded_movies`` collection + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-examples/SearchIndexes.cs + :start-after: begin-atlas-create-many + :end-before: end-atlas-create-many + :language: csharp + :emphasize-lines: 31 + :dedent: + + .. output:: + :language: console + :visible: false + + Created Search indexes: + as_idx vs_idx + +.. _csharp-list-search-index: + +List Search Indexes +------------------- + +You can access information about a collection's existing Atlas Search +and Vector Search indexes by calling the ``SearchIndexes.List()`` +method on the collection. + +Example +~~~~~~~ + +The following example accesses information about the Atlas Search and +Vector Search indexes created in the :ref:`csharp-create-search-indexes` +section of this page. The code calls the ``SearchIndexes.List()`` +method and prints a list of the Atlas Search and Vector Search indexes +on the collection: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-examples/SearchIndexes.cs + :start-after: begin-atlas-list + :end-before: end-atlas-list + :language: csharp + :dedent: + + .. output:: + :language: console + :visible: false + + { "id": "...", "name": "as_idx", "status": "READY", "queryable": + true, "latestDefinitionVersion": {...}, "latestDefinition": { + "mappings": { "dynamic": true } }, "statusDetail": [...] } + + { "id": "...", "name": "vs_idx", "type": "vectorSearch", "status": + "READY", "queryable": true, ..., "latestDefinition": { "fields": [{ + "type": "vector", "path": "plot_embedding", "numDimensions": 1536, + "similarity": "euclidean" }] }, "statusDetail": [...] } + +.. _csharp-update-search-index: + +Update a Search Index +--------------------- + +You can update an Atlas Search or Vector Search index by calling the +``SearchIndexes.Update()`` method on an ``IMongoCollection`` instance. This +method accepts the following parameters: + +- Name of the index to update +- Modified index definition document + +Example +~~~~~~~ + +The following example updates the Vector Search index named ``vs_index`` +created in the :ref:`csharp-create-search-indexes` section of this page. The code +creates a new index definition document that instructs the index to use +``"dotProduct"`` as the vector similarity function. Then, the code calls +the ``SearchIndexes.Update()`` method to update the index: + +.. literalinclude:: /includes/fundamentals/code-examples/SearchIndexes.cs + :start-after: begin-atlas-update + :end-before: end-atlas-update + :language: csharp + :emphasize-lines: 16 + :dedent: + +.. _csharp-drop-search-index: + +Delete a Search Index +--------------------- + +You can delete an Atlas Search or Vector Search index by calling the +``SearchIndexes.DropOne()`` method on an ``IMongoCollection`` instance. This +method accepts the name of the index to delete as a parameter. + +Example +~~~~~~~ + +The following example deletes the Atlas Search index named ``example_index`` +created in the :ref:`csharp-create-search-index` section of this page. The code +passes the index name to the ``SearchIndexes.DropOne()`` method to delete the index: + +.. literalinclude:: /includes/fundamentals/code-examples/SearchIndexes.cs + :start-after: begin-atlas-drop + :end-before: end-atlas-drop + :language: csharp + :dedent: + +Additional Information +---------------------- + +To learn about other indexes you can create by using the {+driver-short+}, see the +:ref:`csharp-indexes` guide. + +To learn more about Atlas Search, see the following Atlas documentation: + +- :atlas:`Atlas Search Best Practices ` +- :atlas:`Tune Atlas Search Performance ` +- :atlas:`Atlas Search M0, M2, and M5 Limitations ` +- :atlas:`FAQ: Atlas Search ` + +To learn more about Atlas Vector Search, see the following Atlas documentation: + +- :atlas:`Improve Vector Search Performance ` +- :atlas:`Atlas Vector Search Quick Start ` +- :atlas:`How to Measure the Accuracy of Your Query Results ` + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the methods and types mentioned in this +guide, see the following API documentation: + +- `CreateSearchIndexModel <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CreateSearchIndexModel.html>`__ +- `SearchIndexType <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SearchIndexType.html>`__ +- `CreateOne() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Search.IMongoSearchIndexManager.CreateOne.html>`__ +- `CreateMany() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Search.IMongoSearchIndexManager.CreateMany.html>`__ +- `List() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Search.IMongoSearchIndexManager.List.html>`__ +- `Update() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Search.IMongoSearchIndexManager.Update.html>`__ +- `DropOne() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Search.IMongoSearchIndexManager.DropOne.html>`__ diff --git a/source/includes/fundamentals/code-examples/SearchIndexes.cs b/source/includes/fundamentals/code-examples/SearchIndexes.cs new file mode 100644 index 00000000..d0d0499d --- /dev/null +++ b/source/includes/fundamentals/code-examples/SearchIndexes.cs @@ -0,0 +1,138 @@ +using MongoDB.Bson; +using MongoDB.Driver; + +public class SearchIndexes +{ + + public static void Main(string[] args) + { + // Replace with your connection string + const string uri = ""; + + var mongoClient = new MongoClient(uri); + var database = mongoClient.GetDatabase("sample_mflix"); + var movieCollection = database.GetCollection("embedded_movies"); + + // begin-as-model + var def = new BsonDocument { + { "mappings", new BsonDocument { + { "dynamic", false }, + { "fields", new BsonDocument { + { "title", new BsonDocument { {"type", "string" } } }, + { "released", new BsonDocument { { "type", "date" } } } } } + } } + }; + + var indexModel = new CreateSearchIndexModel( + "search_idx", + SearchIndexType.Search, + def + ); + // end-as-model + + // begin-avs-model + var def = new BsonDocument + { + { "fields", new BsonArray + { + new BsonDocument + { + { "type", "vector" }, + { "path", "plot_embedding" }, + { "numDimensions", 1536 }, + { "similarity", "euclidean" } + } + } + } + }; + + + var indexModel = new CreateSearchIndexModel( + "vs_idx", + SearchIndexType.VectorSearch, + def + ); + // end-avs-model + + // begin-atlas-create-one + var indexModel = new CreateSearchIndexModel( + "example_index", + SearchIndexType.Search, + new BsonDocument { + { "mappings", new BsonDocument { + { "dynamic", true }, + } } + } + ); + + var result = movieCollection.SearchIndexes.CreateOne(indexModel); + Console.WriteLine("Created Atlas Search index:\n{0}", result); + // end-atlas-create-one + + // begin-atlas-create-many + var searchModel = new CreateSearchIndexModel( + "as_idx", + SearchIndexType.Search, + new BsonDocument { + { "mappings", new BsonDocument { + { "dynamic", true }, + } } + } + ); + + var vectorModel = new CreateSearchIndexModel( + "vs_idx", + SearchIndexType.VectorSearch, + new BsonDocument + { + { "fields", new BsonArray + { + new BsonDocument + { + { "type", "vector" }, + { "path", "plot_embedding" }, + { "numDimensions", 1536 }, + { "similarity", "euclidean" } + } + } + } + } + ); + + var models = new List { searchModel, vectorModel }; + var indexes = movieCollection.SearchIndexes.CreateMany(models); + Console.WriteLine("Created Search indexes:\n{0} {1}", indexes.ToArray()); + // end-atlas-create-many + + // begin-atlas-list + var indexesList = movieCollection.SearchIndexes.List().ToList(); + foreach (var i in indexesList) + { + Console.WriteLine(i); + } + // end-atlas-list + + // begin-atlas-update + var updatedDef = new BsonDocument + { + { "fields", new BsonArray + { + new BsonDocument + { + { "type", "vector" }, + { "path", "plot_embedding" }, + { "numDimensions", 1536 }, + { "similarity", "dotProduct" } + } + } + } + }; + + movieCollection.SearchIndexes.Update("vs_index", updatedDef); + // end-atlas-update + + // begin-atlas-drop + movieCollection.SearchIndexes.DropOne("example_index"); + // end-atlas-drop + } +} diff --git a/source/whats-new.txt b/source/whats-new.txt index 4ac55477..813b29c4 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -134,6 +134,10 @@ The 3.1 driver release includes the following new features: namespace. The driver can now serialize ``ImmutableArray`` objects, and serialization for other immutable collections is more memory efficient. +- Adds the ``SearchIndexType`` type to support creation of Atlas Vector + Search indexes programmatically. To learn more, see the + :ref:`csharp-atlas-search-indexes` guide. + - Adds support for the token field type and array field expressions with Atlas Search builders for the ``equals`` operator. To learn more about using Atlas Search with the {+driver-short+}, see :ref:`csharp-atlas-search`.