Reference R1

CLI reference

Every command the Typer-based CLI exposes. Commands that touch Oracle all honour the same DSN resolution rules — described at the bottom.

Info commands

onnx2oracle version
onnx2oracle presets

version prints the package version. presets prints the five registered models with their Oracle names, HF repos, and dimensions.

load

The primary command. Three shapes — embedding preset, reranker preset, or HuggingFace repo (with --task to pick the pipeline shape).

onnx2oracle load <preset> [--target local | --dsn user/pw@host:port/service]
                         [--force] [--name ORACLE_NAME] [--cache-dir PATH]

onnx2oracle load --from-huggingface <hf/repo> --task embedding --pooling {mean,cls}
                 [--normalize/--no-normalize] [--max-length 512]
                 --dims 384 --name ORACLE_NAME
                 [--target local | --dsn ...]

onnx2oracle load --from-huggingface <cross-encoder/...> --task reranker
                 --name ORACLE_NAME [--max-length 512]
                 [--target local | --dsn ...]

Flags

Flag	Meaning
<preset>	One of the registered presets (5 embedding + 2 reranker). `onnx2oracle presets` shows the list and which task each one is.
--from-huggingface	Alternative to preset. Fully-qualified HF repo (e.g. `BAAI/bge-large-en-v1.5` or `cross-encoder/ms-marco-MiniLM-L-6-v2`).
--task	`embedding` (default) or `reranker`. Determines the pipeline shape and the metadata sent to `LOAD_ONNX_MODEL` (`function:"embedding"` vs `function:"regression"`). When a preset is named, its task overrides this flag.
--target local	Use the local Docker DSN `system/${ORACLE_PWD:-onnx2oracle}@localhost:${ORACLE_PORT:-1521}/FREEPDB1`.
--dsn	Explicit connection string. See DSN resolution.
--force	Drop and reload if the model name already exists in `user_mining_models`.
--name	Override the Oracle mining-model identifier. Required for `--from-huggingface`.
--cache-dir	Where to cache the HuggingFace download. Defaults to `~/.onnx2oracle/cache`.
--pooling	`mean` or `cls`. Embedding custom loads only — presets encode this; ignored for reranker loads.
--normalize / --no-normalize	Append L2 normalization. Embedding only. Default on.
--max-length	Token truncation limit. Default 512.
--dims	Asserted output dimension. Embedding custom loads only; required when `--task embedding` with `--from-huggingface`.

preflight

onnx2oracle preflight [--target local | --dsn ...]

Checks the database before a model upload. It connects, prints the database banner, confirms SYS.DBMS_VECTOR is valid, confirms the SQL function catalog includes VECTOR_EMBEDDING, checks mining-model privileges, checks EXECUTE access to DBMS_VECTOR, and confirms user_mining_models is visible.

Exit code 0 means the target is ready for DBMS_VECTOR.LOAD_ONNX_MODEL. Non-zero output names the missing package, function, privilege, or catalog view.

verify

onnx2oracle verify [--target local | --dsn ...] [--name ORACLE_NAME]

Auto-detects the model's task by reading user_mining_models.mining_function. For embedding models, runs VECTOR_EMBEDDING, asserts shape and L2 norm, and runs a cosine-sanity check (king/queen > king/banana). For reranker models (function = REGRESSION), runs PREDICTION on a known-relevant and known-irrelevant pair and asserts relevant > irrelevant.

Exit code 0 on success, non-zero otherwise.

rerank

onnx2oracle rerank --name ORACLE_NAME --query "..." --doc "doc1" [--doc "doc2" ...]
                  [--target local | --dsn ...]

Scores each (query, doc) pair against a registered reranker model using PREDICTION(model USING :q AS DATA1, :d AS DATA2). Returns a sorted table (highest score first) with rank, score, and document. Refuses to run if the named model is registered as anything other than a reranker.

onnx2oracle rerank --name MS_MARCO_MINILM_L_6_V2 \
  --query "How many people live in Berlin?" \
  --doc "Berlin has a population of 3.7 million inhabitants." \
  --doc "Bananas are a popular tropical fruit."

docker

onnx2oracle docker up [--wait] [--wait-timeout 600] [--wait-interval 5]
onnx2oracle docker down [--volumes]
onnx2oracle docker logs [-f]

Thin wrapper around docker compose pointed at the bundled compose file. up --wait runs a SQL readiness probe inside the container until it succeeds or --wait-timeout elapses — see #docker-timeout.

The bundled compose file honors ORACLE_PWD, ORACLE_PORT, and ORACLE_IMAGE. Use ORACLE_PORT=1524 when 1521 is already occupied, or ORACLE_IMAGE=container-registry.oracle.com/database/free:latest-lite to try the smaller Oracle Free image without editing YAML.

logs -f tails Oracle's alert log. Useful when the container comes up but something inside the database doesn't.

config

onnx2oracle config show
onnx2oracle config set key=value

show dumps the effective TOML at ~/.onnx2oracle/config.toml. set writes a single key. Typical keys:

dsn — persistent DSN in the [default] table; wins over --target local but loses to --dsn and ORACLE_DSN.
cache_dir — override ~/.onnx2oracle/cache.
hf_token — persisted HuggingFace token (prefer HF_TOKEN env if you don't want it on disk).

DSN resolution

Every Oracle-bound command resolves a DSN by this order, first match wins:

#	Source	Example
1	`--dsn` flag	--dsn admin/pw@...
2	`ORACLE_DSN` env var	export ORACLE_DSN=...
3	`~/.onnx2oracle/config.toml` `dsn` in `[default]`	config set dsn=...
4	`--target local`	system/${ORACLE_PWD:-onnx2oracle}@localhost:${ORACLE_PORT:-1521}/FREEPDB1
5	Interactive prompt	CLI asks stdin

One exception. docker up/down/logs don't need a DSN — they talk to Docker directly. Every other command walks the table above.

Custom models Troubleshooting