Oracle AI Database 26ai can compute embeddings itself, with no AI provider and no charge per request. The embedding model is loaded into a schema like any other object, and from then on SQL can run it. Nothing you embed leaves the database.
This guide shows how to get one of Oracle's prebuilt ONNX models, give the database access to the file with a directory object, load it with DBMS_VECTOR.LOAD_ONNX_MODEL, check it in the data dictionary, load a model from a BLOB, and drop a model safely.
Code for This Guide
The examples are in the examples/ch05 folder of the Oracle AI code repository on GitHub, files 01 to 03 and 16, each with its output. They load the model into the sample schema ATLAS, which has the CREATE MINING MODEL privilege; the setup/atlas/create-user.sql script grants it.
These examples come from AI Applications with Oracle Database 26ai and APEX 26.1, a book of 237 tested examples of AI in Oracle Database and APEX.
How Oracle Runs Embedding Models
The database runs embedding models in the ONNX format (Open Neural Network Exchange), an open format most machine-learning tools can export. A loaded model is a mining model of the schema, with the mining function EMBEDDING.
A model in the database must do the whole job, from text to vector: split the text into tokens, run the network, and produce one vector. Oracle publishes models prepared that way, called augmented models, which load without any other tool. This guide uses all-MiniLM-L12-v2, a small, widely used English sentence model.
| Property | all-MiniLM-L12-v2 |
|---|---|
| Dimensions | 384, FLOAT32 |
| Vector length | 1 (normalized) |
| Longest input | 256 tokens, about 200 words; the rest is ignored |
| Language | English |
| Size | 127 MB |
A provider's model such as Gemini's returns 3,072 dimensions and reads thousands of tokens. A small model is less precise, but it is fast and free, and for short texts like tickets and help articles it is usually enough.
Step 1: Get the Model File
- Download all_MiniLM_L12_v2_augmented.zip from the list of pretrained ONNX models linked in Oracle's AI Vector Search User's Guide, and unzip it. It contains all_MiniLM_L12_v2.onnx and a README.
- Copy all_MiniLM_L12_v2.onnx to a folder on the database server that the operating-system user oracle can read, such as /opt/oracle/atlas_files.
If the database runs in a Docker container, create the folder and copy the file in with docker exec and docker cp.
Example (container named db26ai):
docker exec db26ai mkdir -p /opt/oracle/atlas_files docker cp all_MiniLM_L12_v2.onnx db26ai:/opt/oracle/atlas_files/
Step 2: Create a Directory Object
The database reads server files through a directory object: a name for a folder on the server, with read and write privileges. Creating one needs CREATE ANY DIRECTORY, so it is an administrator's job.
Syntax:
create [ or replace ] directory directory_name as 'path_on_the_server';
Example (run as SYS in the pluggable database):
create or replace directory atlas_files as '/opt/oracle/atlas_files'; grant read, write on directory atlas_files to atlas;
Output:
Directory ATLAS_FILES created. Grant succeeded.
Step 3: Load the Model
DBMS_VECTOR.LOAD_ONNX_MODEL reads the ONNX file and stores the model in the schema under a name you choose. The model lives inside the database from then on: the file is no longer needed, and the model is exported, backed up, and copied with the schema.
Syntax:
dbms_vector.load_onnx_model( directory varchar2, file_name varchar2, model_name varchar2, metadata json default null, external_data_file_name varchar2 default null) dbms_vector.load_onnx_model( model_name varchar2, model_data blob, metadata json default null)
| Parameter | Use |
|---|---|
| METADATA | Tells the database the model's function and input name. Oracle's augmented models carry it inside the file, so leave it out. A model you export yourself may need something like json('{"function": "embedding", "input": {"input": ["DATA"]}}'). |
| EXTERNAL_DATA_FILE_NAME | For very large models whose weights ONNX keeps in a second file. |
Example (run as ATLAS):
begin
dbms_vector.load_onnx_model(
directory => 'ATLAS_FILES',
file_name => 'all_MiniLM_L12_v2.onnx',
model_name => 'ALL_MINILM_L12_V2');
end;
/Output:
PL/SQL procedure successfully completed.
Loading takes a few seconds. The model name is an ordinary identifier, so SQL can refer to it as all_minilm_l12_v2 in any case.
Step 4: Check the Model
USER_MINING_MODELS lists the schema's models, and USER_MINING_MODEL_ATTRIBUTES describes their inputs and output.
Example:
select model_name, mining_function, algorithm,
round(model_size / 1024 / 1024) as size_mb
from user_mining_models;
select attribute_name, attribute_type, data_type, vector_info
from user_mining_model_attributes
where model_name = 'ALL_MINILM_L12_V2';Output:
MODEL_NAME MINING_FUNCTION ALGORITHM SIZE_MB ____________________ __________________ ____________ __________ ALL_MINILM_L12_V2 EMBEDDING ONNX 127 ATTRIBUTE_NAME ATTRIBUTE_TYPE DATA_TYPE VECTOR_INFO _________________ _________________ ____________ ______________________ DATA TEXT VARCHAR2 ORA$ONNXTARGET VECTOR VECTOR VECTOR(384,FLOAT32)
Two rows here matter later:
- The input is named DATA. VECTOR_EMBEDDING must use that exact name for the text, or it fails with ORA-54421.
- The output, ORA$ONNXTARGET, is a VECTOR(384, FLOAT32). That is how to declare the column that will store the embeddings, as shown in how to generate embeddings in SQL with VECTOR_EMBEDDING.
Load a Model from a BLOB
The second form of LOAD_ONNX_MODEL takes the model as a BLOB. Use it for a model that is not on the database server, such as one uploaded through an APEX page into a table. DROP_ONNX_MODEL removes a model.
Syntax:
dbms_vector.drop_onnx_model(model_name varchar2, force boolean default false)
Without FORCE, dropping a model that does not exist raises ORA-40284; with FORCE => TRUE the call succeeds anyway, which suits scripts that recreate a model.
This example loads the same file again through a BLOB as MINILM_COPY, lists the models, drops the copy, and lists them again.
Example:
-- the same model, loaded from a BLOB under another name
begin
dbms_vector.load_onnx_model(
model_name => 'MINILM_COPY',
model_data => to_blob(bfilename('ATLAS_FILES', 'all_MiniLM_L12_v2.onnx')));
end;
/
select model_name from user_mining_models order by model_name;
begin
dbms_vector.drop_onnx_model(model_name => 'MINILM_COPY');
end;
/
select model_name from user_mining_models order by model_name;Output:
PL/SQL procedure successfully completed. MODEL_NAME ____________________ ALL_MINILM_L12_V2 MINILM_COPY PL/SQL procedure successfully completed. MODEL_NAME ____________________ ALL_MINILM_L12_V2
TO_BLOB(BFILENAME(...)) reads a file of a directory into a BLOB. In an application, the BLOB usually comes from a table instead.
Drop a Model Only After Re-Embedding
Stored embeddings are only useful with the model that computed them, because every search must embed its question with the same model. Dropping or replacing a model leaves the stored embeddings in place, but new query vectors would come from another model, or from none. Re-embed the data with the replacement model first, then drop the old one.
Other Models
Oracle adds models to its list of prebuilt ONNX models over time, and any of them loads the same way. For a Hugging Face model that Oracle does not publish ready-made, Oracle Machine Learning for Python (OML4Py) can convert it to an augmented ONNX file, which LOAD_ONNX_MODEL then loads.
Whatever the model, the same rules hold: declare the vector column with the model's dimensions, embed data and questions with the same model, and keep each text within the model's token limit.
Conclusion
To run an embedding model inside Oracle AI Database 26ai, download one of Oracle's augmented ONNX models, have an administrator create a directory object for its folder, and load it with DBMS_VECTOR.LOAD_ONNX_MODEL, from the file or from a BLOB. USER_MINING_MODEL_ATTRIBUTES then tells you the input name to use and the vector size to declare. Drop a model with DROP_ONNX_MODEL only after the data has been re-embedded with its replacement.
