Quickstart

Start Oracle 26ai Free

First run downloads the image and initializes the database. Expect three to five minutes. The --wait flag runs a bounded SQL readiness probe so the command only returns when the PDB accepts connections.

$ onnx2oracle docker up --wait --wait-timeout 900
  pulling container-registry.oracle.com/database/free:latest
  starting onnx2oracle-oracle ...
  waiting for SQL readiness ....... ready

Preflight the database

preflight checks the banner, DBMS_VECTOR, VECTOR_EMBEDDING, mining-model privileges, and the mining-model catalog before you spend time building an ONNX graph.

$ onnx2oracle preflight --target local
  Connected ... ok
  DBMS_VECTOR package ... ok
  VECTOR_EMBEDDING function ... ok

Load the default model

With no --target or --dsn, the loader uses the local compose DSN: system/${ORACLE_PWD:-onnx2oracle}@localhost:${ORACLE_PORT:-1521}/FREEPDB1. The augmented ONNX is built in memory and streamed to Oracle as a BLOB — nothing touches the filesystem of the database container.

$ onnx2oracle load all-MiniLM-L6-v2 --target local
  downloading sentence-transformers/all-MiniLM-L6-v2 (90 MB)
  wrapping tokenizer (onnxruntime-extensions)
  adding mean pool + L2 norm
  calling DBMS_VECTOR.LOAD_ONNX_MODEL ... ok
  model registered as ALL_MINILM_L6_V2

The first load caches the HuggingFace download under ~/.onnx2oracle/cache/. Subsequent runs skip the network.

Verify

verify embeds a canned string twice, asserts the output is 384-d float32, and confirms cosine(v, v) = 1.0. If that fails, the issue is in the graph, not your app.

$ onnx2oracle verify --target local
  model: ALL_MINILM_L6_V2
  VECTOR_EMBEDDING(...) returned 384-d ... ok
  cosine(self, self) = 1.000000 ... ok
  cosine(cat, dog)   = 0.672 ... sensible

Embed your own rows

Straight SQL from here on. The model name is the one printed above.

SELECT VECTOR_EMBEDDING(ALL_MINILM_L6_V2 USING 'hello world' AS DATA) AS v
FROM dual;

Store the result in a VECTOR(384, FLOAT32) column, build an IVF_FLAT or HNSW index, and you're doing retrieval inside the DB.