Semantic Search

Use the query operation to search a vector table using a query vector, text, or record ID.

The operation performs similarity search to find the most similar vectors in the given table. Filtering by metadata and by various distance metrics is supported. The API retrieves IDs, metadata, vectors, and similarity scores of the most similar items from the table.

See the following example of semantic search using query:

from oracle_vecdb import OracleVecDB, Configuration

client = OracleVecDB(Configuration(
    rest_url="https://<host>/ords/<schema>/_/db-api/stable/vecdb/",
    access_token="<bearer-token>", # or username="<user>", password="<pass>"
))

#search by query vector
vector_results = client.query(
    table_name='products',
    query_by={'vector': [0.1, 0.2, 0.3, ...]},
    top_k=10
)
print(vector_results.items[0].id)


#search by text
text_results = client.query(
    table_name='products',
    query_by={'text': 'wireless headphones'},
    top_k=5
)
print(text_results)


#find similar items to an existing product
similar_item_results = client.query(
    table_name='products',
    query_by={'id': 'prod_12345'},
    top_k=10,
    filters={'category': {'$eq': 'electronics'}}
)
print(similar_item_results)

A JSON response is returned, containing the following information:

An array of matching results with IDs, distances, and metadata
Distance scores (a lower value is more similar for most metrics)
Vector values (if include_vectors is set to true)

Example response:

{
    "items": [
        {
            "id": "prod_001",
            "metadata": {
                "name": "Aurora Trail Boots",
                "category": "footwear",
                "price": 129.99,
                "color": "midnight blue"
            },
            "vector": null,
            "distance": 0.0
        },
        {
            "id": "prod_008",
            "metadata": {
                "name": "Glacier Insulated Bottle",
                "category": "accessories",
                "price": 34.0,
                "color": "arctic white"
            },
            "vector": null,
            "distance": 0.00393
        }
    ]
}

For more information about the query operation, see Python API Reference.

See how POST /vecdb/vector-tables/{vector_table_name}/query can be used in the following examples:

Search by query vector:

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/vector-tables/product_vectors/query" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  # Choose ONE authentication method:

  # Option 1: Basic authentication
  -u "<user>:<password>" \

  # Option 2: OAuth Bearer token
  # -H "Authorization: Bearer <access_token>" \

  -d '{
    "queryBy": {"vector": [0.1, 0.5, 0.4, 0.56]},
    "topK": 5,
    "includeVectors": false
  }'

Search by text with filtering:

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/vector-tables/product_vectors/query" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u "<user>:<password>" \
  -d '{
    "queryBy": {"text": "good headphone"},
    "topK": 5,
    "filters": {
      "$and": [
        {"category": {"$eq": "electronics"}},
        {"price": {"$lt": 200}}
      ]
    },
    "outputSelector": ["product_name", "price", "product_description"],
    "includeVectors": false
  }'

Find similar items to an existing product:

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/vector-tables/product_vectors/query" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u "<user>:<password>" \
  -d '{
    "queryBy": {"id": "id2"},
    "topK": 10,
    "filters": {"category": {"$eq": "electronics"}}
  }'

Search with custom distance metric:

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/vector-tables/product_vectors/query" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u "<user>:<password>" \
  -d '{
    "queryBy": {"text": "good headphone"},
    "topK": 10,
    "advancedOptions": {
      "distance_metric": "EUCLIDEAN",
      "idx_parameters": {
        "efsearch": 128,
        "neighbor_part": 4
      },
      "advanced_params": {
        "rescore_factor": 2
      }
    },
    "includeVectors": true
  }'

Responses:

Example 200 response:

{
  "results": [
    {
      "id": "id2",
      "distance": 0.212,
      "metadata": {
        "product_name": "Studio Monitor Headphones",
        "price": 149.99,
        "product_description": "Professional wired headphones with accurate sound for studio use."
      }
    },
    {
      "id": "id5",
      "distance": 0.678,
      "metadata": {
        "product_name": "Wireless Earbuds",
        "price": 199.99,
        "product_description": "Noise-cancelling wireless earbuds with rich sound and secure fit."
      }
    }
  ]
}

400 - the request body included invalid parameters.
404 - the specified vector table does not exist.

For more information, see REST API Reference.

See how DBMS_VECTOR_DATABASE.SEARCH can be used in the following example:

dbms_vector_database.search(
  table_name      => 'product_vectors',
  query_by        => JSON('{"text": "good headphone"}'),
  top_k           => 5,
  filters         => JSON('{
    "$and": [
      { "category": { "$eq": "electronics" } },
      { "price":   { "$lt": 200 } }
    ]
  }'),
  include_vectors => false
);

Example response:

{"result" :
[
  {"id":"id2", "vector_distance" : 0.212,
   "metadata":{"product_name":"Studio Monitor Headphones","price":149.99,
               "product_description":"Professional wired headphones with accurate sound for studio use."}},
  {"id":"id5", "vector_distance" : 0.678, 
   "metadata":{"product_name":"Wireless Earbuds",,"price":199.99,
   "product_description":"Noise-cancelling wireless earbuds with rich sound and secure fit."}}
]
}

For more information about the PL/SQL implementation, including parameters, see SEARCH.