MongoDB Vector Search Quick Start Tutorial

1
#include <bson/bson.h>
2
#include <mongoc/mongoc.h>
3
#include <stdio.h>
4
5
int main(void) {
6
  mongoc_client_t *client;
7
  mongoc_collection_t *collection;
8
  bson_error_t error;
9
  char database_name[] = "sample_mflix";
10
  char collection_name[] = "embedded_movies";
11
  char index_name[] = "vector_index";
12
13
  mongoc_init();
14
15
  // Replace the placeholder with your connection string
16
  client =  mongoc_client_new("<connection-string>");
17
18
  // Connect to your cluster
19
  collection = mongoc_client_get_collection (client, database_name, collection_name);
20
21
  bson_t cmd;
22
  // Create search index command.
23
  {
24
    char *cmd_str = bson_strdup_printf (
25
        BSON_STR ({
26
                    "createSearchIndexes" : "%s",
27
                    "indexes" : [{
28
                      "definition": {
29
                        "fields": [{
30
                          "type": "vector",
31
                          "path": "plot_embedding_voyage_3_large",
32
                          "numDimensions": 2048,
33
                          "similarity": "dotProduct",
34
                          "quantization": "scalar"
35
                        }]
36
                      },
37
                      "name": "%s",
38
                      "type": "vectorSearch"
39
                    }]
40
                  }),
41
        collection_name, index_name);
42
    if (!bson_init_from_json(&cmd, cmd_str, -1, &error)) {
43
      printf("Failed to initialize BSON: %s\n", error.message);
44
      bson_free(cmd_str);
45
      return 1;
46
    }
47
    bson_free (cmd_str);
48
  }
49
  if (!mongoc_collection_command_simple (collection, &cmd, NULL /* read_prefs */, NULL /* reply */, &error)) {
50
    bson_destroy (&cmd);
51
    printf ("Failed to run createSearchIndexes: %s", error.message);
52
    return 1;
53
  } else {
54
    printf ("New search index named %s is building.\n", index_name);
55
    bson_destroy (&cmd);
56
  }
57
58
  // Polling for index status
59
  printf("Polling to check if the index is ready. This may take up to a minute.\n");
60
  int queryable = 0;
61
  while (!queryable) {
62
    const char *pipeline_str = "{\"pipeline\": [{\"$listSearchIndexes\": {}}]}";
63
    bson_t pipeline;
64
    if (!bson_init_from_json(&pipeline, pipeline_str, -1, &error)) {
65
      printf("Failed to initialize pipeline BSON: %s\n", error.message);
66
      break; // Exit the loop on error
67
    }
68
    mongoc_cursor_t *cursor = mongoc_collection_aggregate(collection, MONGOC_QUERY_NONE, &pipeline, NULL, NULL);
69
    const bson_t *got;
70
    // Check if the cursor returns any documents
71
    int found_index = 0;
72
    while (mongoc_cursor_next(cursor, &got)) {
73
      bson_iter_t iter;
74
      if (bson_iter_init(&iter, got) && bson_iter_find(&iter, "name")) {
75
        const char *name = bson_iter_utf8(&iter, NULL);
76
        if (strcmp(name, index_name) == 0) {
77
          found_index = 1; // Index found
78
          bson_iter_find(&iter, "queryable");
79
          queryable = bson_iter_bool(&iter);
80
          break; // Exit the loop since we found the index
81
        }
82
      }
83
    }
84
    if (mongoc_cursor_error(cursor, &error)) {
85
      printf("Failed to run $listSearchIndexes: %s\n", error.message);
86
      break; // Exit the loop on error
87
    }
88
    if (!found_index) {
89
      printf("Index %s not found yet. Retrying...\n", index_name);
90
    }
91
    bson_destroy(&pipeline);
92
    mongoc_cursor_destroy(cursor);
93
    sleep(5); // Sleep for 5 seconds before checking again
94
  }
95
  if (queryable) {
96
    printf("%s is ready for querying.\n", index_name);
97
  } else {
98
    printf("Error occurred or index not found.\n");
99
  }
100
101
  // Cleanup
102
  mongoc_collection_destroy(collection);
103
  mongoc_client_destroy(client);
104
  mongoc_cleanup();
105
106
  return 0;
107
}

1
#include <bsoncxx/builder/basic/document.hpp>
2
#include <iostream>
3
#include <mongocxx/client.hpp>
4
#include <mongocxx/instance.hpp>
5
#include <mongocxx/search_index_view.hpp>
6
#include <mongocxx/uri.hpp>
7
#include <thread>
8
9
using bsoncxx::builder::basic::kvp;
10
using bsoncxx::builder::basic::make_array;
11
using bsoncxx::builder::basic::make_document;
12
13
int main() {
14
  try {
15
    mongocxx::instance inst{};
16
17
    // Replace the placeholder with your connection string
18
    const auto uri = mongocxx::uri{"<connection-string>"};
19
20
    // Connect to your cluster
21
    mongocxx::client conn{uri};
22
    auto db = conn["sample_mflix"];
23
    auto collection = db["embedded_movies"];
24
25
    auto siv = collection.search_indexes();
26
    std::string name = "vector_index";
27
    auto type = "vectorSearch";
28
    auto definition = make_document(
29
        kvp("fields",
30
            make_array(make_document(
31
                kvp("type", "vector"), kvp("path", "plot_embedding_voyage_3_large"),
32
                kvp("numDimensions", 2048), kvp("similarity", "dotProduct"), 
33
                kvp("quantization", "scalar")))));
34
    auto model =
35
        mongocxx::search_index_model(name, definition.view()).type(type);
36
    siv.create_one(model);
37
    std::cout << "New search index named " << name << " is building."
38
              << std::endl;
39
40
    // Polling for index status
41
    std::cout << "Polling to check if the index is ready. This may take up to "
42
                 "a minute."
43
              << std::endl;
44
    bool queryable = false;
45
    while (!queryable) {
46
      auto indexes = siv.list();
47
      for (const auto& index : indexes) {
48
        if (index["name"].get_value() == name) {
49
          queryable = index["queryable"].get_bool();
50
        }
51
      }
52
      if (!queryable) {
53
        std::this_thread::sleep_for(std::chrono::seconds(5));
54
      }
55
    }
56
    std::cout << name << " is ready for querying." << std::endl;
57
  } catch (const std::exception& e) {
58
    std::cout << "Exception: " << e.what() << std::endl;
59
  }
60
  return 0;
61
}

1
namespace query_quick_start;
2
3
using MongoDB.Bson;
4
using MongoDB.Driver;
5
using System;
6
using System.Threading;
7
8
public class IndexService
9
{
10
    // Replace the placeholder with your connection string
11
    private const string MongoConnectionString = "<connectionString>";
12
    public void CreateVectorIndex()
13
    {
14
        try
15
        {
16
            // Connect to your cluster
17
            var client = new MongoClient(MongoConnectionString);
18
            var database = client.GetDatabase("sample_mflix");
19
            var collection = database.GetCollection<BsonDocument>("embedded_movies");
20
21
            var searchIndexView = collection.SearchIndexes;
22
            var name = "vector_index";
23
24
            var model = new CreateVectorSearchIndexModel<Movie>(
25
                m => m.PlotEmbedding,
26
                name,
27
                VectorSimilarity.DotProduct,
28
                2048)
29
            {
30
                Quantization = VectorQuantization.Scalar
31
            };
32
33
            searchIndexView.CreateOne(model);
34
            Console.WriteLine($"New search index named {name} is building.");
35
36
            // Polling for index status
37
            Console.WriteLine("Polling to check if the index is ready. This may take up to a minute.");
38
            bool queryable = false;
39
            while (!queryable)
40
            {
41
                var indexes = searchIndexView.List();
42
                foreach (var index in indexes.ToEnumerable())
43
                {
44
                    if (index["name"] == name)
45
                    {
46
                        queryable = index["queryable"].AsBoolean;
47
                    }
48
                }
49
                if (!queryable)
50
                {
51
                    Thread.Sleep(5000);
52
                }
53
            }
54
            Console.WriteLine($"{name} is ready for querying.");
55
        }
56
        catch (Exception e)
57
        {
58
            Console.WriteLine($"Exception: {e.Message}");
59
        }
60
    }
61
}

using query_quick_start;
var indexService = new IndexService();
indexService.CreateVectorIndex();

1
import com.mongodb.client.MongoClient;
2
import com.mongodb.client.MongoClients;
3
import com.mongodb.client.MongoCollection;
4
import com.mongodb.client.MongoDatabase;
5
import com.mongodb.client.model.SearchIndexModel;
6
import com.mongodb.client.model.SearchIndexType;
7
import org.bson.Document;
8
import org.bson.conversions.Bson;
9
10
import java.util.Collections;
11
import java.util.List;
12
13
public class VectorIndex {
14
15
    public static void main(String[] args) {
16
17
        // Replace the placeholder with your connection string
18
        String uri = "<connectionString>";
19
20
        // Connect to your cluster
21
        try (MongoClient mongoClient = MongoClients.create(uri)) {
22
23
            // Set the namespace
24
            MongoDatabase database = mongoClient.getDatabase("sample_mflix");
25
            MongoCollection<Document> collection = database.getCollection("embedded_movies");
26
27
            // Define the index details
28
            String indexName = "vector_index";
29
            Bson definition = new Document(
30
                "fields",
31
                Collections.singletonList(
32
                    new Document("type", "vector")
33
                        .append("path", "plot_embedding_voyage_3_large")
34
                        .append("numDimensions", 2048)
35
                        .append("similarity", "dotProduct")
36
                        .append("quantization", "scalar")));
37
38
            // Define the index model
39
            SearchIndexModel indexModel = new SearchIndexModel(
40
                indexName,
41
                definition,
42
                SearchIndexType.vectorSearch());
43
44
            // Create the index using the defined model
45
            List<String> result = collection.createSearchIndexes(Collections.singletonList(indexModel));
46
            System.out.println("Successfully created vector index named: " + result.get(0));
47
            System.out.println("It may take up to a minute for the index to leave the BUILDING status and become queryable.");
48
49
            // Wait for index to build and become queryable
50
            System.out.println("Polling to confirm the index has left the BUILDING status.");
51
            // No special handling in case of a timeout. Custom handling can be implemented.    
52
            waitForIndex(collection, indexName);
53
        }
54
    }
55
56
    /**
57
     * Polls the collection to check whether the specified index is ready to query.
58
     */
59
    public static <T> boolean waitForIndex(final MongoCollection<T> collection, final String indexName) {
60
        long startTime = System.nanoTime();
61
        long timeoutNanos = TimeUnit.SECONDS.toNanos(60);
62
        while (System.nanoTime() - startTime < timeoutNanos) {
63
            Document indexRecord = StreamSupport.stream(collection.listSearchIndexes().spliterator(), false)
64
                    .filter(index -> indexName.equals(index.getString("name")))
65
                    .findAny().orElse(null);
66
            if (indexRecord != null) {
67
                if ("FAILED".equals(indexRecord.getString("status"))) {
68
                    throw new RuntimeException("Search index has FAILED status.");
69
                }
70
                if (indexRecord.getBoolean("queryable")) {
71
                    System.out.println(indexName + " index is ready to query");
72
                    return true;
73
                }
74
            }
75
            try {
76
                Thread.sleep(100); // busy-wait, avoid in production
77
            } catch (InterruptedException e) {
78
                Thread.currentThread().interrupt();
79
                throw new RuntimeException(e);
80
            }
81
        }
82
        return false;
83
    }
84
}

1
import com.mongodb.MongoException
2
import com.mongodb.client.model.SearchIndexModel
3
import com.mongodb.client.model.SearchIndexType
4
import com.mongodb.kotlin.client.coroutine.MongoClient
5
import kotlinx.coroutines.delay
6
import kotlinx.coroutines.flow.toList
7
import org.bson.Document
8
import kotlinx.coroutines.runBlocking
9
10
fun main() {
11
    // Replace the placeholder with your MongoDB deployment's connection string
12
    val uri = "<connection-string>"
13
    val mongoClient = MongoClient.create(uri)
14
    val database = mongoClient.getDatabase("sample_mflix")
15
    val collection = database.getCollection<Document>("embedded_movies")
16
    val indexName = "vector_index"
17
    val searchIndexModel = SearchIndexModel(
18
        indexName,
19
        Document(
20
            "fields",
21
            listOf(
22
                Document("type", "vector")
23
                    .append("path", "plot_embedding_voyage_3_large")
24
                    .append("numDimensions", 2048)
25
                    .append("similarity", "dotProduct")
26
                    .append("quantization", "scalar")
27
            )
28
        ),
29
        SearchIndexType.vectorSearch()
30
    )
31
32
    runBlocking {
33
        try {
34
            collection.createSearchIndexes(listOf(searchIndexModel))
35
                .collect { result ->
36
                    println("New search index named $result is building.")
37
                }
38
39
            // Polling to check if the index is queryable
40
            println("Polling to check if the index is ready. This may take up to a minute.")
41
            var isQueryable = false
42
            while (!isQueryable) {
43
                delay(5000L) // Poll every 5 seconds
44
45
                val indexes = collection.listSearchIndexes().toList()
46
                isQueryable = indexes.any { index ->
47
                    index.getString("name") == indexName && index.getBoolean("queryable")
48
                }
49
                if (isQueryable) {
50
                    println("$indexName is ready for querying.")
51
                }
52
            }
53
        } catch (me: MongoException) {
54
            System.err.println("An error occurred: $me")
55
        }
56
    }
57
    mongoClient.close()
58
}

1
const { MongoClient } = require("mongodb");
2
3
// connect to your deployment
4
const uri =  "<connectionString>";
5
6
const client = new MongoClient(uri);
7
8
async function run() {
9
   try {
10
     const database = client.db("sample_mflix");
11
     const collection = database.collection("embedded_movies");
12
    
13
     // define your MongoDB Vector Search index
14
     const index = {
15
         name: "vector_index",
16
         type: "vectorSearch",
17
         definition: {
18
           "fields": [
19
             {
20
               "type": "vector",
21
               "numDimensions": 2048,
22
               "path": "plot_embedding_voyage_3_large",
23
               "similarity": "dotProduct",
24
               "quantization": "scalar"
25
             }
26
           ]
27
         }
28
     }
29
30
     // run the helper method
31
     const result = await collection.createSearchIndex(index);
32
     console.log(`New search index named ${result} is building.`);
33
34
     // wait for the index to be ready to query
35
     console.log("Polling to check if the index is ready. This may take up to a minute.")
36
     let isQueryable = false;
37
     while (!isQueryable) {
38
       const cursor = collection.listSearchIndexes();
39
       for await (const index of cursor) {
40
         if (index.name === result) {
41
           if (index.queryable) {
42
             console.log(`${result} is ready for querying.`);
43
             isQueryable = true;
44
           } else {
45
             await new Promise(resolve => setTimeout(resolve, 5000));
46
           }
47
         }
48
       }
49
     }
50
   } finally {
51
     await client.close();
52
   }
53
}
54
run().catch(console.dir);

1
<?php
2
3
require 'vendor/autoload.php';
4
5
// Replace the placeholder with your connection string
6
$uri = "<connectionString>";
7
$client = new MongoDB\Client($uri);
8
$collection = $client->sample_mflix->embedded_movies;
9
$indexName = "vector_index";
10
try {
11
    $result = $collection->createSearchIndexes(
12
        [[
13
            'name' => $indexName,
14
            'type' => 'vectorSearch',
15
            'definition' => [
16
                'fields' => [[
17
                    'type' => 'vector',
18
                    'path' => 'plot_embedding_voyage_3_large',
19
                    'numDimensions' => 2048,
20
                    'similarity' => 'dotProduct',
21
                    'quantization' => 'scalar'
22
                ]]
23
            ],
24
        ]]
25
    );
26
    echo "New search index named $result[0] is building." .PHP_EOL;
27
28
    // Polling for the index to become queryable
29
    echo "Polling to check if the index is ready. This may take up to a minute." .PHP_EOL;
30
    $isIndexQueryable = false;
31
    while (!$isIndexQueryable) {
32
        // List the search indexes
33
        $searchIndexes = $collection->listSearchIndexes();
34
        // Check if the index is present and queryable
35
        foreach ($searchIndexes as $index) {
36
            if ($index->name === $indexName) {
37
                $isIndexQueryable = $index->queryable;
38
            }
39
        }
40
        if (!$isIndexQueryable) {
41
            sleep(5); // Wait for 5 seconds before polling again
42
        }
43
    }
44
    echo "$indexName is ready for querying." .PHP_EOL;
45
}
46
catch (MongoDB\Driver\Exception\Exception $e) {
47
    print 'Error creating the index: ' .$e->getMessage() .PHP_EOL;
48
}

1
from pymongo.mongo_client import MongoClient
2
from pymongo.operations import SearchIndexModel
3
import time
4
5
# Connect to your deployment
6
uri = "<connectionString>"
7
client = MongoClient(uri)
8
9
# Access your database and collection
10
database = client["sample_mflix"]
11
collection = database["embedded_movies"]
12
13
# Create your index model, then create the search index
14
search_index_model = SearchIndexModel(
15
  definition={
16
    "fields": [
17
      {
18
        "type": "vector",
19
        "path": "plot_embedding_voyage_3_large",
20
        "numDimensions": 2048,
21
        "similarity": "dotProduct",
22
        "quantization": "scalar"
23
      }
24
    ]
25
  },
26
  name="vector_index",
27
  type="vectorSearch"
28
)
29
30
result = collection.create_search_index(model=search_index_model)
31
print("New search index named " + result + " is building.")
32
33
# Wait for initial sync to complete
34
print("Polling to check if the index is ready. This may take up to a minute.")
35
predicate=None
36
if predicate is None:
37
  predicate = lambda index: index.get("queryable") is True
38
39
while True:
40
  indices = list(collection.list_search_indexes(result))
41
  if len(indices) and predicate(indices[0]):
42
    break
43
  time.sleep(5)
44
print(result + " is ready for querying.")
45
46
client.close()

1
require 'mongo'  
2
require 'json'  
3
  
4
uri = "<connection-string>"  
5
  
6
begin  
7
  # Connect to the MongoDB client  
8
  client = Mongo::Client.new(uri, database: 'sample_mflix')  
9
  
10
  # Set the namespace  
11
  db = client.database  
12
  collection = db[:embedded_movies]  
13
  
14
  # Define the Vector Search index definition
15
  index_definition = {
16
    fields: [
17
      {
18
        type: "vector",
19
        path: "plot_embedding_voyage_3_large",
20
        numDimensions: 2048,
21
        similarity: "dotProduct"
22
      }
23
    ]
24
  }
25
26
  # Create the index using `create_one`
27
  index_name = collection.search_indexes.create_one(
28
    index_definition,
29
    name: 'vector_index',
30
    type: 'vectorSearch'
31
  )
32
  
33
  puts "Vector search index created successfully: #{index_name}"  
34
  
35
rescue Mongo::Error::NoServerAvailable => e  
36
  # Handle MongoDB server connection issues  
37
  puts "Failed to connect to MongoDB: #{e.message}"  
38
  
39
rescue Mongo::Error::OperationFailure => e  
40
  # Handle MongoDB operation failure issues  
41
  puts "Failed to perform operation: #{e.message}"  
42
  
43
rescue Mongo::Error => e  
44
  # Handle general MongoDB-related errors  
45
  puts "A MongoDB error occurred: #{e.message}"  
46
  
47
rescue StandardError => e  
48
  # Handle any other kinds of errors  
49
  puts "A general error occurred: #{e.message}"  
50
  
51
ensure  
52
  # Ensure the client is closed  
53
  client&.close  
54
  puts "MongoDB client closed."  
55
end