For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Create an OpenSearch vector database, connect from a trusted source, create a k-NN index, add sample vectors, and run a similarity search in about 15 minutes.

Before you begin, you need:

• An OpenSearch vector database. Provisioning can take several minutes.
• A trusted source added to the cluster, such as your current IP address.
• The cluster’s host, port, username, and password from the cluster’s connection details.
• A terminal on the trusted source with curl and jq installed.
• Enough cluster RAM for the HNSW graph if you plan to use OpenSearch for production vector workloads. OpenSearch stores the HNSW graph in memory.

For additional configuration guidance, see Create an OpenSearch Vector Database Cluster.

Export Connection Details on a Trusted Source

After you create your OpenSearch vector database and secure the cluster, export the connection details as environment variables:

1. From your vector database’s Network Access tab, choose a trusted source to open a terminal session. For example, if you added your current IP address as a trusted source, open the terminal from the same computer and network using that IP address.

2. In the terminal, export the connection details as environment variables:

   export OPENSEARCH_HOST="<your-cluster-host>"
   export OPENSEARCH_PORT="<your-cluster-port>"
   export OPENSEARCH_USER="<your-cluster-username>"
   export OPENSEARCH_PASSWORD="<your-cluster-password>"
   export OS="https://$OPENSEARCH_USER:$OPENSEARCH_PASSWORD@$OPENSEARCH_HOST:$OPENSEARCH_PORT"

   Replace <your-cluster-host>, <your-cluster-port>, <your-cluster-username>, and <your-cluster-password> with the values you saved from the cluster’s connection details.

3. Verify the connection:

   curl -sS "$OS/" | jq '.version.number'

   If successful, the command returns the OpenSearch version number.

Run a Query

OpenSearch vector databases include the k-NN, ML Commons, and hybrid search plugins. After the cluster is active, you can create vector indexes and run similarity queries.

This example creates a small k-NN index with 4-dimensional vectors, adds sample documents, and then searches for the closest matches to a coffee-related query vector:

1. Using the trusted source, open a terminal session. For example, if you added your current IP address as a trusted source, open the terminal from the same computer and network using that IP address.

2. Then, create an index that stores 4-dimensional vectors:

   Note

   Use the dimension required by your embedding model, such as 384, 768, 1024, or 1536 for production use.

   curl -X PUT "$OS/articles" \
     -H "Content-Type: application/json" \
     -d '{
       "settings": {
         "index": {
           "knn": true,
           "knn.algo_param.ef_search": 100
         }
       },
       "mappings": {
         "properties": {
           "title": { "type": "text" },
           "body":  { "type": "text" },
           "embedding": {
             "type": "knn_vector",
             "dimension": 4,
             "method": {
               "name": "hnsw",
               "engine": "lucene",
               "space_type": "cosinesimil",
               "parameters": {
                 "m": 16,
                 "ef_construction": 128
               }
             }
           }
         }
       }
     }'

   In this index, "knn": true enables k-NN search, knn_vector defines the vector field, and dimension must match the embedding model.

3. Add four sample documents with precomputed embeddings:

   curl -X POST "$OS/articles/_bulk" \
     -H "Content-Type: application/x-ndjson" \
     --data-binary '
   { "index": { "_id": "1" } }
   { "title": "Coffee brewing basics", "body": "Pour-over, espresso, and cold brew compared.", "embedding": [0.91, 0.10, 0.05, 0.02] }
   { "index": { "_id": "2" } }
   { "title": "Best espresso machines", "body": "A buyer guide for home espresso setups.", "embedding": [0.88, 0.15, 0.07, 0.04] }
   { "index": { "_id": "3" } }
   { "title": "Intro to deep learning", "body": "Neural networks, backpropagation, activations.", "embedding": [0.05, 0.92, 0.18, 0.10] }
   { "index": { "_id": "4" } }
   { "title": "Hiking trails near Denver", "body": "Five scenic day hikes within an hour of the city.", "embedding": [0.12, 0.08, 0.90, 0.22] }
   '

   OpenSearch returns "errors": false when the bulk request succeeds.

4. Search for the two documents closest to a coffee-related query vector:

   curl -X POST "$OS/articles/_search" \
     -H "Content-Type: application/json" \
     -d '{
       "size": 2,
       "query": {
         "knn": {
           "embedding": {
             "vector": [0.90, 0.12, 0.06, 0.03],
             "k": 2
           }
         }
       }
     }'

   The response returns the two coffee-related articles as the highest-ranked results.

Run the Same Query with Python

To run the same query with Python:

1. Install opensearch-py:

   pip install "opensearch-py>=2.4.0"

2. Create a Python file with the following code:

   import os
   from opensearchpy import OpenSearch
   
   client = OpenSearch(
       hosts=[{
           "host": os.environ["OPENSEARCH_HOST"],
           "port": int(os.environ.get("OPENSEARCH_PORT", 25060)),
       }],
       http_auth=(os.environ["OPENSEARCH_USER"], os.environ["OPENSEARCH_PASSWORD"]),
       use_ssl=True,
       verify_certs=True,
   )
   
   response = client.search(
       index="articles",
       body={
           "size": 2,
           "query": {
               "knn": {
                   "embedding": {
                       "vector": [0.90, 0.12, 0.06, 0.03],
                       "k": 2,
                   }
               }
           },
       },
   )
   
   for hit in response["hits"]["hits"]:
       print(hit["_score"], hit["_source"]["title"])

   Fill in the OPENSEARCH_HOST, OPENSEARCH_PORT, OPENSEARCH_USER, and OPENSEARCH_PASSWORD environment variables you exported earlier.

3. Save the file as query-opensearch.py, and then run it:

   python3 query-opensearch.py

   The output lists the closest matching article titles and their scores.