Quick Start Guide

Use this quickstart to connect to Oracle VecDB, insert sample vectors, and run a basic similarity search.

This quickstart walks through installing the SDK, configuring a client, creating a table, loading sample vectors, and running a similarity query. Use it to sanity-check your Oracle VecDB environment, hosted through Oracle AI Database 23.26.3+ and ORDS 26.2.2+, before building more advanced apps.

Requirements

Installation

python -m pip install --upgrade oracle-vecdb

For environments that require an HTTP proxy, add the --proxy option:

python -m pip install oracle-vecdb --upgrade --user --proxy=http://proxy.example.com:80

Note: Hosts typically look like https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/. Ensure TLS is enabled and the URL is reachable from your environment.

1. Configure the client

from oracle_vecdb import OracleVecDB, Configuration

config = Configuration(
    rest_url="https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/",
    # choose one auth method
    access_token="<bearer-token>",
    # or username="<user>", password="<pass>",
)

vecdb = OracleVecDB(config)

For all constructor parameters and object attributes, see Configuration.

2. Create an integrated embedding vector table

Create a table that generates embeddings from text stored in metadata. The configured model must already be available in Oracle AI Database.

vecdb.create_vector_table(
    name="demo",
    table_params={"auto_generate_id": True},
    embed_params={
        "model": "all_MiniLM_L12_v2",
        "embed_metadata_jsonpath": "content",
    },
)

3. Load integrated embedding records

When an integrated embedding vector table is configured, provide text in the metadata field selected by embed_metadata_jsonpath. The database generates the vector during the upsert.

vecdb.upsert_vectors(
    table_name="demo",
    vectors=[
        {
            "metadata": {
                "title": "Comedy movie review",
                "content": "A lighthearted comedy with fast-paced jokes.",
                "genre": "comedy",
            }
        },
        {
            "metadata": {
                "title": "Drama movie review",
                "content": "An emotional family drama with strong performances.",
                "genre": "drama",
            }
        },
    ],
)

4. Run a text query with filtering

A text query uses the table’s configured embedding model to generate the query vector.

results = vecdb.query(
    table_name="demo",
    query_by={"text": "family drama"},
    filters={"genre": {"$eq": "drama"}},
    top_k=1,
)

for index in range(len(results)):
    item = results[index]
    row = item if isinstance(item, dict) else item.model_dump()
    print(row["id"], row["distance"], row["metadata"])

Ingestion Options

Bring your own vectors

For precomputed embeddings, omit embed_params when creating the vector table, and provide dense_vector values in each record.

vecdb.create_vector_table(name="demo_byov")
vecdb.upsert_vectors(
    table_name="demo_byov",
    vectors=[
        {"id": "1", "dense_vector": [0.1, 0.1], "metadata": {"genre": "comedy"}},
        {"id": "2", "dense_vector": [0.2, 0.2], "metadata": {"genre": "drama"}},
    ],
)

results = vecdb.query(
    table_name="demo_byov",
    query_by={"vector": [0.15, 0.1]},
    filters={"genre": {"$eq": "drama"}},
    top_k=1,
)

for index in range(len(results)):
    item = results[index]
    row = item if isinstance(item, dict) else item.model_dump()
    print(row["metadata"]["genre"])

Indexing and tuning

Create indexes after loading data

Create the table first and build its index explicitly when the data-loading workflow is complete.

vecdb.create_vector_table(
    name="demo_manual",
    index_params={"vector_index_params": {"auto_index": False}},
)

vecdb.create_index(table_name="demo_manual")

Create an HNSW index

Use INMEMORY GRAPH organization for an HNSW (Hierarchical Navigable Small World) vector index.

vecdb.create_vector_table(
    name="demo_hnsw",
    index_params={
        "vector_index_params": {
            "organization": "INMEMORY GRAPH",
            "advanced_params": {
                "neighbors": 32,
                "efConstruction": 200,
            },
        },
    },
)

Query-time HNSW tuning

Use advanced_options to adjust HNSW runtime search behavior. efsearch is HNSW-only; use it to control the candidate pool size and balance recall against query latency without rebuilding the index.

results = vecdb.query(
    table_name="demo",
    query_by={"text": "family drama"},
    filters={"genre": {"$eq": "drama"}},
    top_k=1,
    advanced_options={
        "idx_parameters": {
            "efsearch": 64,
        }
    },
)

Sample notebooks and apps

Next steps