Install AI Agent Skills  View Python SDK  View Notebook  Open in Colab

Quickstart: Build Vector Search with Python

This tutorial shows how to use the Oracle VecDB Python SDK to build a working vector search application in Python. You will create a vector table, add records, and run a similarity search against Oracle AI Database.

To run the quickstart in a notebook, select Open in Colab in the badges at the top of this page.

The notebook follows the same database setup, table creation, record loading, and semantic search flow as this page.

This quickstart uses the integrated-embedding workflow. To compare it with the bring-your-own-vector workflow, see Embedding Workflows.

When you finish

You will have created a vector table, loaded records, and run a semantic search that returns the closest records by meaning. Oracle AI Database creates and maintains the vector and metadata indexes automatically, so you do not need to create an index for this quickstart.

Requirements

Before you begin

Set up your Oracle AI Database environment before you install the SDK:

  1. Choose a database deployment, then complete the setup page for your deployment.
  2. Save the vector-user name and password, and copy the SDK REST endpoint. You do not use the Console URL in the Python configuration.
  3. This quickstart uses integrated embeddings. Load the all_MiniLM_L12_v2 embedding model before running it. You can use another integrated embedding model; if you do, replace the model value in the table creation step with the exact name of the model you loaded. See Load a Model Using the Vector Database Console.

The quickstart uses the SDK REST endpoint, not the Console URL, and uses username and password authentication by default. For bearer-token configuration, see Configuration.

1. Install the SDK

Install the latest version of the SDK:

python -m pip install --upgrade oracle-vecdb

If you use uv, add the SDK to your uv-managed project:

uv add oracle-vecdb

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

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

Warning: Use the lowercase REST URL mapping in the /ords/<vector_user>/ segment. This is different from the uppercase <VECTOR_USER> database user placeholder used in the SQL and Python examples. For example, a database user named VECTOR_USER uses /ords/vector_user/ in the URL.

The SDK REST endpoint typically looks like https://<host>:<port>/ords/<vector_user>/_/db-api/stable/vecdb/. Ensure TLS is enabled and the URL is reachable from your environment.

2. Configure the client

from oracle_vecdb import OracleVecDB, Configuration

config = Configuration(
    rest_url="https://<host>:<port>/ords/<vector_user>/_/db-api/stable/vecdb/",
    username="<VECTOR_USER>",
    password="<VECTOR_USER_PASSWORD>",
)

vecdb = OracleVecDB(config)

For all constructor parameters and object attributes, see Configuration. Keep credentials out of source control.

If you have an OAuth access token, pass it to Configuration instead of the username and password. See Configuration for authentication options.

config = Configuration(
    rest_url="https://<host>:<port>/ords/<vector_user>/_/db-api/stable/vecdb/",
    access_token="<BEARER_TOKEN>",
)

If you rerun this quickstart and the demo table already exists, delete it before continuing. This also deletes its vectors and indexes.

vecdb.drop_vector_table(name="demo")

3. Create an integrated embedding vector table

Create a table that generates embeddings from text stored in metadata. The model value must match the embedding model that you loaded during deployment setup. Set embed_metadata_jsonpath to the path of the text inside each record’s metadata. Here, the path is content, so the database automatically embeds metadata["content"] with the selected model when you upsert a record.

For how a vector table relates to records, metadata, embeddings, and indexes, see Vector Table.

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

4. Load integrated embedding records

An upsert inserts a new record or updates the existing record with the same ID. For an integrated-embedding table, provide text in the metadata field selected by embed_metadata_jsonpath. The database generates the vector during the upsert.

Each item you upsert is a record containing an ID and metadata. The database adds the generated vector to that record.

vecdb.upsert_vectors(
    table_name="demo",
    vectors=[
        {
            "id": "comedy-1",
            "metadata": {
                "title": "Comedy movie review",
                "content": "A lighthearted comedy filled with witty dialogue and unexpected situations.",
                "genre": "comedy",
            }
        },
        {
            "id": "drama-1",
            "metadata": {
                "title": "Drama movie review",
                "content": "A heartfelt story about relatives overcoming a difficult situation together.",
                "genre": "drama",
            }
        },
        {
            "id": "science-fiction-1",
            "metadata": {
                "title": "Science fiction movie review",
                "content": "A futuristic adventure about explorers traveling beyond the solar system.",
                "genre": "science fiction",
            }
        },
        {
            "id": "documentary-1",
            "metadata": {
                "title": "Documentary movie review",
                "content": "An informative film examining ocean conservation and marine ecosystems.",
                "genre": "documentary",
            }
        },
        {
            "id": "thriller-1",
            "metadata": {
                "title": "Thriller movie review",
                "content": "A suspenseful mystery about an investigator searching for a missing artifact.",
                "genre": "thriller",
            }
        },
    ],
)

The quickstart uses explicit IDs so you can refer to records such as drama-1 in later queries. To use database-generated IDs instead, see create_vector_table.

5. Run a semantic search

A text query uses the table’s configured embedding model to generate the query vector. This query describes the meaning of the drama record without repeating its exact words.

For an overview of how content and query embeddings are used in vector search, see Oracle AI Vector Search.

results = vecdb.query(
    table_name="demo",
    query_by={"text": "A moving story about people supporting one another through hardship"},
    top_k=3,
)

for item in results:
    print(
        f"id: {item.id} | distance: {item.distance} | "
        f"genre: {item.metadata['genre']} | title: {item.metadata['title']}"
    )

Success: You created an integrated embedding vector table, loaded records, and ran a semantic search.

For example, the semantically closest result is the drama record, even though the query does not use the words family or drama:

id: drama-1 | distance: <DISTANCE> | genre: drama | title: Drama movie review
id: comedy-1 | distance: <DISTANCE> | genre: comedy | title: Comedy movie review
id: documentary-1 | distance: <DISTANCE> | genre: documentary | title: Documentary movie review

The exact distances and order of the results can vary with the embedding model and index configuration.

Next steps

Continue building your application with these three tasks:

Read the concepts behind this quickstart

More examples and reference