Bringing Oracle Database AI Vector Search to Semantic Kernel in Python: A Complete Guide

Semantic Kernel just landed a major boost for Python developers using Oracle Database. The latest Semantic Kernel release now includes built-in support for the Oracle Database Vector Store connector, which means you can plug Oracle Database straight into your AI apps and instantly get fast embeddings, semantic search, and full RAG pipelines, all running inside Oracle AI Database 26ai and higher.

Refer: Oracle Database AI Vector Search See also: Oracle Vector Database

What’s really exciting is that Oracle AI Database 26ai now has native VECTOR types and super-fast indexing including:

HNSW (Hierarchical Navigable Small World) an in-memory graph index for extremely fast similarity search HNSW Blog IVF_FLAT (Inverted File — Flat) a scalable disk-based partitioned index ideal for very large datasets IVF Blog

In plain English?

You can now unlock the full potential of Oracle AI Database 26ai’s vector capabilities, without requiring any external vector engines or extra services. And because Semantic Kernel now supports these capabilities directly in Python, everything works together smoothly.

In this blog, we’ll explore how the Oracle Vector Store connector fits into your Python workflow, what features it unlocks, and why it makes building intelligent, memory-rich AI applications dramatically easier and way more fun.

What is Semantic Kernel?

Semantic Kernel is an open-source AI orchestration framework from Microsoft designed to help developers build intelligent applications by combining LLMs, embeddings, vector search, memory, planning and traditional code. Semantic Kernel acts as the “AI middleware” in your application, offering a unified way to:

• Run prompt-based functions
• Store and query semantic memory
• Build (dynamic) RAG pipelines
• Orchestrate multi-step workflows and agents
• Integrate external data sources and tools

With Semantic Kernel, developers can easily blend AI reasoning with classic programming constructs, enabling applications that can understand, remember and act.

Refer: Semantic Kernel Overview Semantic Kernel Vector Stores

Here’s what the Oracle Vector Store connector brings to the table.

1. Native Vector Storage

The Oracle Vector Store connector uses Oracle Database’s built-in VECTOR datatype to store embeddings directly in the database. No serialization. No custom formats. Just native vector support with full Oracle performance and indexing capabilities.

2. Automatic Collection/Table Management

An Oracle Database vector store collection is a logical dataset that Semantic Kernel maps to an Oracle table. Each collection stores:

• Vector embeddings (in an Oracle Database VECTOR column)
• Metadata fields
• A key/identifier

When you work with an Oracle Database Vector Store collection, Semantic Kernel can automatically:

• Create the underlying Oracle Database table
• Set up the correct VECTOR column
• Generate and store metadata fields
• Maintain the table schema behind the scenes

You simply call Semantic Kernel APIs like *get_collection()* and Semantic Kernel handles all the Oracle Database side details for you.

3. High-Performance Vector Indexing

The Oracle Vector Store connector gives you access to Oracle’s powerful vector indexing options:

• HNSW (Hierarchical Navigable Small World)
• IVF_FLAT (Inverted File Flat)

These indexes make similarity search extremely fast, even with large datasets.

Note: Oracle Database Vector Store connector does not choose a default index type. If the user does not specify *index_kind* in the model definition, no vector index will be created and the connector will log a warning to indicate this. Similarity search will still work, but performance may be slower for large collections.

4. Multiple Distance Metrics

Depending on your use case, you can choose:

• Cosine distance
• Dot product
• Euclidean distance
• Euclidean squared distance
• Hamming
• Manhattan

Semantic Kernel includes configuration options to pick your preferred metric for searches.

Refer to the Oracle Database documentation on Vector Distance Metrics for more details.

5. Full CRUD + Semantic Search

The Oracle Vector Store connector supports:

• Inserting/Upserting records
• Deleting records
• Fetching memory entries
• Similarity search

You can treat Oracle Database as both a semantic memory store and a relational database.

Installation

The Oracle Database vector store connector ships with the latest Semantic Kernel release for Python. To install Semantic Kernel with Oracle Database support, simply run:

pip install semantic-kernel[oracledb]

Oracle Database Vector Store integration will be available in Semantic Kernel for Python releases after version 1.39.0.

pip install "semantic-kernel[oracledb]>1.39.0"

Once everything is installed, connecting Semantic Kernel to Oracle Database is simple. Define a data model, connect Semantic Kernel to Oracle Database, insert data, and run vector search, all using the new Oracle Database vector store connector.

The full source code for Semantic Kernel, including the vector store abstractions, is available on GitHub: https://github.com/microsoft/semantic-kernel

1. Define Your Vector Model

Semantic Kernel uses the *@vectorstoremodel* decorator to define how your data should be stored in Oracle Database. Below is a fully annotated example called DocumentRecord.

Required Imports

import asyncio

# Semantic Kernel vector store APIs
from semantic_kernel.data.vector import (
    VectorStoreField,
    IndexKind,
    vectorstoremodel,
)

# BaseModel for structured data models (Pydantic)
from pydantic import BaseModel, ConfigDict

# Typing helpers
from typing import Annotated, Any, List, Dict

# Oracle Database vector store connector classes
from semantic_kernel.connectors.oracle import OracleSettings, OracleStore

DocumentRecord Model Example

@vectorstoremodel(collection_name="documents_collection")
class DocumentRecord(BaseModel):
    # Primary key for the record (stored as a unique ID in Oracle)
    Id: Annotated[str, VectorStoreField("key")]

    # Optional title stored as metadata
    Title: Annotated[str | None, VectorStoreField("data")] = None

    # Main text content of the document
    Content: Annotated[str, VectorStoreField("data")]

    # Vector embedding stored in Oracle VECTOR type
    # - type="float64" → matches Oracle's FLOAT64 vector storage
    # - dimensions=1536 → typical embedding size (e.g., OpenAI text-embedding-ada-002)
    # - index_kind=IndexKind.IVF_FLAT → creates an IVF_FLAT vector index in Oracle
    ContentVector: Annotated[
        list | str | None,
        VectorStoreField(
            "vector",
            type="float64",
            dimensions=1536,
            index_kind=IndexKind.IVF_FLAT,
        ),
    ] = None

    # Tags stored as a list of values in metadata
    Tags: Annotated[list[str], VectorStoreField("data")]

    # Additional optional metadata stored as JSON
    Metadata: Annotated[dict[str, Any] | None, VectorStoreField("data")] = None

This collection maps directly to a VECTOR-enabled Oracle Database table.

2. Load or Create Sample Data

async def load_sample_records(embedder) -> list[DocumentRecord]:
    samples = []

    # ---- Document D1 ----
    content_1 = "Vector search allows semantic matching of text."
    emb_1 = (await embedder.generate_embeddings([content_1]))[0].tolist()

    samples.append(
        DocumentRecord(
            Id="D1",
            Title="Introduction to Vector Search",
            Content=content_1,
            ContentVector=emb_1,
            Tags=["ai", "vectors", "semantic"],
            Metadata={"category": "tutorial"}
        )
    )

    # ---- Document D2 ----
    content_2 = "Oracle Database introduces native vector support."
    emb_2 = (await embedder.generate_embeddings([content_2]))[0].tolist()

    samples.append(
        DocumentRecord(
            Id="D2",
            Title="Understanding Oracle Database 26ai",
            Content=content_2,
            ContentVector=emb_2,
            Tags=["oracle", "database"],
            Metadata={"category": "database"}
        )
    )

    return samples

3. Connect to Oracle Database

Oracle Database Configuration

Semantic Kernel’s Oracle Database vector store connector can be configured using either:

1. An .*env file (e.g., `oracle.env`*), or

2. Direct environment variables exported in your shell.

Both approaches provide the same configuration values.

Required Environment Variables

These variables specify Oracle Database credentials and connection details:

export ORACLE_USER=<database username>
export ORACLE_PASSWORD=<database password>
export ORACLE_CONNECT_STRING=<host:port/service_name or TNS alias>

Optional Pool Configuration

export ORACLE_POOL_MIN=1
export ORACLE_POOL_MAX=5
export ORACLE_POOL_INCREMENT=1

Optional Wallet Configuration

export ORACLE_WALLET_LOCATION=/path/to/wallet
export ORACLE_WALLET_PASSWORD=<wallet password>

Using a ‘.env’ File

*oracle.env *is simply a text file that contains environment variables:

ORACLE_USER=myuser
ORACLE_PASSWORD=mypassword
ORACLE_CONNECT_STRING=dbhost:1521/orclpdb1

ORACLE_POOL_MIN=1
ORACLE_POOL_MAX=5
ORACLE_POOL_INCREMENT=1

ORACLE_WALLET_LOCATION=/path/to/wallet
ORACLE_WALLET_PASSWORD=secret

Load it using OracleSettings

from semantic_kernel.connectors.oracle import OracleSettings

oracle_settings = OracleSettings(
    env_file_path="/path/to/oracle.env"
)

Using Direct Environment Variables

If you export environment variables directly (no *.env* file), simply initialize:

oracle_settings = OracleSettings()

No file path is needed.

Create the async connection pool

Semantic Kernel’s Python SDK is fully asynchronous, so Oracle connections must be created inside an async event loop:

import asyncio

async def main():
    oracle_settings = OracleSettings(env_file_path="/path/to/your/oracle.env")
    pool = await oracle_settings.create_connection_pool()
    # Continue with OracleStore setup...

asyncio.run(main())

Note: *create_connection_pool() is an async method. It cannot be used without `asyncio`* when working with Semantic Kernel.

4. Get Your Vector Collection

Use the connector to access your collection:

store = OracleStore(
    connection_pool=pool
)

async with store.get_collection(
    record_type=DocumentRecord,
    settings=oracle_settings,
) as collection:

Semantic Kernel will create the Oracle Database table if it doesn’t already exist.

You can also create the collection directly:

async with OracleCollection(
    record_type=DocumentRecord,
    settings=oracle_settings,
) as collection:

5. Upsert Records Into Oracle Database

Semantic Kernel Insert/Upsert record(s) into a specific collection.

records = await load_sample_records()
await collection.upsert(records)

Oracle Database supports batch inserts.

6. Retrieve and Query Data

Fetch records with key:

results = await collection.get(["D1"])
print("\n=== GET RESULT (ID = 'D1') ===")
print(f"• ID: {results.Id}")
print(f"  Title: {results.Title}")
print(f"  Content: {results.Content}")

Output:

7. Run Vector Search (Semantic Search)

Generate an embedding for your query (using your embedding provider):

query_vector = (await text_embedding.generate_embeddings(["vector search basics"]))[0]

Run similarity search:

results = await collection.search(
   vector_property_name="ContentVector",
   vector=query_vector,
   include_vectors=False,
   filter=lambda x: x.Title.contains("Oracle")
)

Iterate over results:

print("\n=== VECTOR SEARCH RESULTS ===")
idx = 1
async for result in results.results:
    rec = result.record
    print(f"\nResult #{idx}")
    print("-----------")
    print(f"• Title:  {rec.Title}")
    print(f"• Score:  {result.score:.5f}")
    print(f"• ID:     {rec.Id}")
    print(f"• Preview:")
    print(f"    {rec.Content}")
    idx += 1
    print("\n=== DONE ===")

Output:

Oracle Database performs similarity search using its native vector engine.

8. Use as a search function (Optional)

Once you have a collection, you can create one or more functions from that collection, these functions allow you to specifically expose one or more ways for your AI applications to call search dynamically.

Use the create_search_function method on the collection to do this, it has several settings, including filters, custom parameters (including descriptions), and output mappers. All these parameters together allow you full control over what is exposed to the model, what is returned to the model (which fields, or combination thereof) from your data model. And because you can have multiple functions, you can combine multiple, for instance for a generic search and a detailed search, where the first one returns just a summary, but the top 5 hits, or a single most relevant item with all the details.

9. Delete the Collection (Optional)

await collection.ensure_collection_deleted()

Semantic Kernel drops a collection (Oracle Database table) if it exists and all associated artifacts.

10. Check if collection Exists

result = await collection.collection_exists()
print(result)

Checks if a given collection (table) exists in Oracle Database schema.

Final Thoughts

Using Semantic Kernel’s Oracle connector in Python, you can now:

• Define custom data models
• Store embeddings in Oracle AI Database 26ai and higher
• Run fast vector searches
• Combine metadata + semantic filtering
• Build RAG systems without a separate vector database.
• Use the Oracle database search functions with both Semantic Kernel and Agent Framework.

All in just a few lines of Python.

With the new Oracle Vector Store connector now available in Semantic Kernel for Python, developers finally have a simple, scalable, production-ready way to add semantic memory to their AI applications.

Oracle AI Database 26ai and higher delivers:

• Native vector search
• High-performance indexes
• Enterprise reliability

And Semantic Kernel makes it incredibly easy to use.

Whether you’re building RAG pipelines, search systems, document intelligence or AI agents, this integration removes the usual friction. No additional vector databases, no mixers of services, just Oracle Database doing the heavy lifting.

Huge thanks again to the Microsoft Semantic Kernel team for collaborating with Oracle to bring this to life. And this is only the beginning. More features, performance improvements, and deeper integrations are on the way.

If you’re excited to try it out, experiment with the connector, load your own embeddings and start building powerful AI applications backed by Oracle Vector Search.

Happy coding!