Install the Python SDK

The Python SDK, oracle-vecdb, is distributed using Python's package repository (PyPI) and can be installed using pip.

First ensure that Python is installed on your system. The versions supported with oracle-vecdb are Python 3.10 and later. You can check your version using the following command:

python --version

Note:

On some platforms, the Python executable may be called python3 instead of python.

Run the following command to install or upgrade oracle-vecdb:

python -m pip install oracle-vecdb --upgrade

Using python -m pip ensures that the package is installed for the same Python interpreter that you are running.

If you are not using a virtual environment and do not have permission to install packages system-wide, you can choose to append the --user option to the end of the install command to indicate a user-level installation.

You can verify the installation by importing the oracle_vecdb package in Python:

python -c "import oracle_vecdb"

If no error is raised, the installation was successful.

Create a Client and Perform Simple Queries

Once you have installed the Python SDK, you can follow these example to first create a client and then create a table, upsert vectors, and perform a semantic search with filters. Note that you will need to input your own rest_url and access_token (or username and password) values to create the client.

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)

Note:

Proxies and retries can be configured using Configuration.

Create an integrated embedding 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",
    },
)
```

Load model-backed records.

When integrated embedding is configured, provide text in the metadata field selected by embed_metadata_jsonpath (in this case, "content"). The database generates the vector during 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",
      }
    },
  ],
)

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"])

Create a Table Bringing Your Own Vectors

For precomputed embeddings, omit the embed_params property from the vector table creation 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"])

Create Indexes and Perform Tuning

Delay index creation.

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 Hierarchical Navigable Small World (HNSW) index.

Use INMEMORY GRAPH as the value for organization for an HNSW-style 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.

Tune HNSW search with advanced_options 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,
    }
  },
)

For more in depth examples that demonstrate how to use Vector Database Console, see the following resources on GitHub: