Documentation
¶
Overview ¶
Package oracle exposes Oracle 23ai's native VECTOR column type through the Core vector-store capability interfaces. Documents live in a regular Oracle table (id / content / metadata JSON / embedding VECTOR) reached through `database/sql` + the sijms/go-ora driver. Documents containing media are rejected before indexing I/O because this adapter persists document text and metadata only.
Requirements: Oracle Database 23ai (the AI release). VECTOR is a first-class column type in 23ai, with `VECTOR_DISTANCE()` and `TO_VECTOR()` built-ins.
Distance metrics — three of Oracle's standard variants are exposed:
- DistanceCosine — cosine distance
- DistanceEuclidean — L2 distance
- DistanceDot — dot product (Oracle returns the raw IP; the store maps it into [0, 1] via (1 + ip) / 2)
Searches are exact, and deliberately so. Oracle separates exact from approximate purely by syntax — `FETCH FIRST n ROWS ONLY` compares the query vector against every row, `FETCH APPROX FIRST n ROWS ONLY` permits a vector index — and this store issues the former, so every result is a true nearest neighbor. StoreConfig.InitializeSchema correspondingly creates the table and no vector index: an HNSW index needs the CDB-level `vector_memory_size` raised from its default of 0 and is unavailable on RAC, so provisioning one would fail the bootstrap on ordinary deployments rather than accelerate it.
An operator who wants approximate search owns both halves. The index's DISTANCE must be the metric configured here, because "if you use a different distance function than the one used to create the index, an exact match is triggered because you cannot use the index in this case" — Oracle defaults both the index and `VECTOR_DISTANCE()` to COSINE, which is also DefaultDistanceMetric. Note that the index still will not be used until the query asks for it, and this store's query does not; Oracle reports none of this, silently falling back to a full scan.
Vector binding. The store renders `[v1,v2,...]` as text and wraps each call in `TO_VECTOR(:1, <dim>, FLOAT32)`. Oracle's positional `:N` placeholders mean the filter visitor's placeholders are renumbered to start after the query-vector's `:1` slot.
Filter visitor reaches metadata with `json_value(metadata, '$.key' RETURNING NUMBER)` for numeric / ordering comparisons so the predicate runs against typed numbers, not text. String comparisons drop the RETURNING clause.
Partial writes. Index prepares one MERGE and runs it per document without wrapping the batch in a transaction, so a failure leaves the rows already written in place. The returned error names the id that failed, and repeating the call is safe because the statement is idempotent per row.
See https://docs.oracle.com/en/database/oracle/oracle-database/23/ vecse/index.html for the official reference.
Index ¶
- Constants
- type DistanceMetric
- type Store
- func (s *Store) DeleteIDs(ctx context.Context, ids []string) (err error)
- func (s *Store) DeleteWhere(ctx context.Context, expr filter.Predicate) (err error)
- func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
- func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
- type StoreConfig
Constants ¶
const ( DefaultTableName = "VECTOR_STORE" DefaultIDColumn = "ID" DefaultContentColumn = "CONTENT" DefaultMetadataColumn = "METADATA" DefaultEmbeddingColumn = "EMBEDDING" DefaultDistanceMetric = DistanceCosine )
Exported defaults keep constructor behavior visible and overridable.
const Provider = "Oracle"
Provider is the stable backend name for host-side attribution.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DistanceMetric ¶
type DistanceMetric string
DistanceMetric selects the VECTOR_DISTANCE function variant. The constants mirror Oracle's accepted values exactly so they can flow straight into the SQL.
const ( // DistanceCosine — cosine distance. DistanceCosine DistanceMetric = "COSINE" // DistanceEuclidean — Euclidean (L2) distance. DistanceEuclidean DistanceMetric = "EUCLIDEAN" // DistanceDot — dot product. Oracle returns the raw inner // product; the store wraps it as `(1 + dot) / 2` so scores stay // in [0, 1] for unit-norm vectors. DistanceDot DistanceMetric = "DOT" )
func (DistanceMetric) String ¶
func (d DistanceMetric) String() string
func (DistanceMetric) Valid ¶
func (d DistanceMetric) Valid() bool
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements vector-store capabilities with Oracle AI Vector Search.
func NewStore ¶
func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
NewStore performs schema setup during construction, which is why it takes a context: a store returned before its table and vector index exist would fail on the first index rather than at wiring, where the misconfiguration actually is.
func (*Store) DeleteIDs ¶
DeleteIDs removes rows by primary key — `DELETE ... WHERE <id> IN (:1, :2, …)` with one positional bind per id. An empty slice is a no-op; unknown ids are silently ignored (idempotent). Implements vectorstore.IDDeleter.
func (*Store) DeleteWhere ¶
func (*Store) Index ¶
func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
Index embeds documents and upserts them via MERGE.
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
Search runs VECTOR_DISTANCE against the embedding column.
type StoreConfig ¶
type StoreConfig struct {
// DB is the database handle. Required. Use a *sql.DB built from
// github.com/sijms/go-ora/v2 pointed at an Oracle 23ai
// instance.
DB *sql.DB
// SchemaName is the optional schema prefix (Oracle username).
// When empty the connection user's default schema is used.
SchemaName string
// TableName is the table that stores documents and their
// embeddings. Optional: defaults to [DefaultTableName].
TableName string
// IDColumn / ContentColumn / MetadataColumn / EmbeddingColumn
// override the column names of the generated schema. Each
// defaults to its respective Default* constant when empty.
IDColumn string
ContentColumn string
MetadataColumn string
EmbeddingColumn string
// EmbeddingModel produces vectors for the documents. Required.
EmbeddingModel embedding.Model
// DocumentBatcher batches documents before insertion. Required.
DocumentBatcher vectorstore.Batcher
// Dimensions sets the VECTOR column width, and is required when
// InitializeSchema is true: the width is part of the column type, and
// nothing here can read it off a table that does not exist yet. It is also
// what TO_VECTOR is told at query time.
Dimensions int
// DistanceMetric selects the distance function. Optional:
// defaults to [DistanceCosine].
DistanceMetric DistanceMetric
// InitializeSchema, when true, creates the table if it doesn't
// already exist.
InitializeSchema bool
}
StoreConfig contains configuration options for the Oracle 23ai vector store.
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files