#10266·agno

[Feature Request] Oracle Database support as a vector database provider

Author: juliosouzamCreated Sep 17, 2026Updated Sep 17, 2026

Problem Description

Agno ships vector database backends for Postgres (PgVector), MySQL, MongoDB, ClickHouse, SingleStore, Chroma, Qdrant, LanceDB, Milvus and others, but there is no backend for Oracle Database. Teams that already run Oracle for storage (or whose infrastructure standardizes on Oracle) cannot use it for retrieval — they have to introduce and operate a second database engine just for vector/knowledge search, even when Oracle's own native VECTOR type and Oracle Text already cover the need.

Proposed Solution

Add a first-class OracleVector backend, designed as a drop-in equivalent to PgVector:

  • OracleVector in agno/vectordb/oracle/, built on SQLAlchemy with the native Oracle VECTOR type and VECTOR_DISTANCE() (requires Oracle Database 23ai or later).
  • Same retrieval modes as PgVector: vector similarity search, keyword search (Oracle Text CONTAINS), hybrid search (weighted combination, so the weight parameter actually controls the ranking), and metadata filters using the same FilterExpr DSL.
  • An explicit optimize() step that creates the ANN vector index (IVF or HNSW) and the Oracle Text index, since Oracle's index creation is a separate, explicit statement rather than implicit.
  • Oracle-specific semantics handled inside the backend: the same empty-string-folds-to-NULL owner-scoping issue the storage provider (#9044) already solves, JSON metadata stored via a TypeDecorator (no native JSON support in the SQLAlchemy Oracle dialect prior to 21c), and numeric JSON filter comparisons that explicitly request RETURNING NUMBER to avoid lexicographic string comparison.
  • oracle extra in pyproject.toml (shared with the storage provider), unit tests (mock engine, CI-safe), a differential conformance suite comparing directly against PgVector, and a cookbook example mirroring 04_pgvector.py.

Alternatives Considered

  • Running a separate vector database alongside Oracle storage — defeats the purpose for teams standardizing on Oracle, and doubles operational surface for no correctness benefit.
  • Relying on a generic embedding-search layer bolted onto Oracle — no maintained option fits Agno's VectorDb provider interface or its filter DSL.

Additional Context

Depends on the Oracle storage provider (#9044 / #10265) for the shared oracle extra and SQLAlchemy engine setup, but has no other dependency on its internals — the owner-scoping sentinel is reimplemented locally in this module. I have a complete implementation ready and validated against a real Oracle AI Database 26ai Free instance, including a differential conformance suite run directly against PgVector. PR to follow, linked to this issue, once the storage PR (#10265) lands.

Would you like to work on this?

  • Yes, I'd love to work on it!