24. Extending node-oracledb
Added in node-oracledb version 6.8.
You can extend the functionalities of node-oracledb by using plugins. The plugins provided by node-oracledb are listed in this section.
24.1. Cloud Native Authentication Plugins
Added in node-oracledb version 6.8.
Node-oracledb provides pre-supplied plugins for cloud native authentication which are listed in this section. These plugins enable token generation using the Software Development Kit (SDK) of the respective token-authentication method.
The cloud native authentication token plugin implementation is available in the plugins/token directory of the node-oracledb package.
To load these node-oracledb plugins in your application, use
require('oracledb/plugins/token/<name of plugin>'), for example:
require('oracledb/plugins/token/extensionOci');
24.1.1. Oracle Cloud Infrastructure (OCI) Cloud Native Authentication Plugin
Node-oracledb’s extensionOci plugin enables token generation using OCI
Software Development Kit (SDK) when
authenticating with IAM token-based authentication.
The extensionOci plugin is available as part of the plugins/token directory in the node-oracledb package. This plugin
requires the minimum Node.js version supported by OCI
SDK.
Adding this plugin to your code defines and registers a built-in hook function
that generates IAM tokens. This function is internally invoked when the
tokenAuthConfigOci property is specified in the
oracledb.getConnection() or oracledb.createPool().
See Cloud Native Authentication with the extensionOci Plugin for more information.
24.1.2. Azure Cloud Native Authentication Plugin
Node-oracledb’s extensionAzure plugin enables token generation using Azure
Software Development Kit (SDK) when
authenticating with OAuth 2.0 token-based authentication.
The extensionAzure plugin implementation is available as part of the
plugins/token directory in the node-oracledb package.
This plugin requires the minimum Node.js version supported by Azure SDK.
Adding this plugin to your code defines and registers a built-in hook function
that generates OAuth 2.0 tokens. This function is internally invoked when the
tokenAuthConfigAzure property is specified in the
oracledb.getConnection() or oracledb.createPool().
See Cloud Native Authentication with the extensionAzure Plugin for more information.
24.1.3. End-User Security Provider Plugin
Added in node-oracledb version 26.0.0.
Node-oracledb’s endUserSecurityProvider plugin can be used with Oracle
Deep Data Security to create and apply end-user security contexts for database
operations.
The endUserSecurityProvider plugin implementation is available in the
plugins/token/endUserSecurityProvider
directory of the node-oracledb package.
Adding this plugin to your code defines and registers a built-in process
configuration hook that creates an end-user security context provider. This
provider is configured when the endUserSecParams property is specified in
oracledb.getConnection() or oracledb.createPool().
Request-specific metadata is supplied with
securityContextProvider.runWithContext(), and the generated end-user
security context is applied only to database operations executed within that
callback.
See End-User Security Context Payload Creation Using endUserSecurityProvider Plugin for more information.
24.2. Centralized Configuration Provider Plugins
Added in node-oracledb version 6.9.
Node-oracledb provides pre-supplied plugins for centralized configuration providers which are listed in this section. These plugins provide access to database connection credentials and application configuration information stored in a centralized configuration provider.
The centralized configuration provider plugin implementation is available in the plugins/configProviders directory of the node-oracledb package.
To load these node-oracledb plugins in your application, use
require('oracledb/plugins/configProviders/<name of plugin>'), for example:
require('oracledb/plugins/configProviders/ociobject');
24.2.1. OCI Object Storage Centralized Configuration Provider Plugin
Added in node-oracledb version 6.9.
ociobject is a plugin that can be loaded in your application to provide
access to configuration information stored in
Oracle Cloud Infrastructure (OCI) Object Storage.
This plugin is implemented as a centralized configuration provider hook
function to handle connection strings which have the
prefix config-ociobject, see OCI Object Storage connection strings.
To load the ociobject plugin in your application, use:
require('oracledb/plugins/configProviders/ociobject');
See Using an OCI Object Storage Centralized Configuration Provider for more information.
24.2.2. OCI Vault Centralized Configuration Provider Plugin
Added in node-oracledb version 6.9.
ocivault is a plugin that can be loaded in your application to provide
access to configuration information stored in
Oracle Cloud Infrastructure (OCI) Vault.
This plugin is implemented as a centralized configuration provider hook
function to handle connection strings which have the
prefix config-ocivault, see OCI Vault connection strings.
To load the ocivault plugin in your application, use:
require('oracledb/plugins/configProviders/ocivault');
See Using an OCI Vault Centralized Configuration Provider for more information.
24.2.3. Microsoft Azure App Centralized Configuration Provider Plugin
Added in node-oracledb version 6.9.
azure is a plugin that can be loaded in your application to provide
access to configuration information stored in
Azure App Configuration.
This plugin is implemented as a centralized configuration provider hook
function to handle connection strings which have the
prefix config-azure, see Azure App Configuration connection strings.
To load the azure plugin in your application, use:
require('oracledb/plugins/configProviders/azure');
See Using an Azure App Centralized Configuration Provider for more information.
24.2.4. Microsoft Azure Key Vault Centralized Configuration Provider Plugin
Added in node-oracledb version 6.9.
azurevault is a plugin that can be loaded in your application to provide
access to configuration information stored in
Azure Key Vault.
This plugin is implemented as a centralized configuration provider hook
function to handle connection strings which have the
prefix config-azurevault, see Azure Key Vault connection strings.
To load the azurevault plugin in your application, use:
require('oracledb/plugins/configProviders/azurevault');
See Using an Azure Key Vault Centralized Configuration Provider for more information.
24.2.5. Amazon Simple Storage Service (S3) Centralized Configuration Provider Plugin
Added in node-oracledb version 7.0.
awss3 is a plugin that can be loaded in your application to provide access
to configuration information stored in AWS S3.
This plugin is implemented as a centralized configuration provider hook
function to handle connection strings which have the
prefix config-awss3, see Amazon S3 connection strings.
To load the awss3 plugin in your application, use:
require('oracledb/plugins/configProviders/awss3');
See Using an Amazon Web Service (AWS) Simple Storage Service (S3) Centralized Configuration Provider for more information.
24.2.6. AWS Secrets Manager Centralized Configuration Provider Plugin
Added in node-oracledb version 7.0.
awssecretsmanager is a plugin that can be loaded in your application to
provide access to configuration information stored in
AWS Secrets Manager.
This plugin is implemented as a centralized configuration provider hook
function to handle connection strings which have the
prefix config-awssecretsmanager, see AWS Secrets Manager connection
strings.
To load the awssecretsmanager plugin in your application, use:
require('oracledb/plugins/configProviders/awssecretsmanager');
See Using an AWS Secrets Manager Centralized Configuration Provider for more information.
24.2.7. Google Cloud Storage Centralized Configuration Provider Plugin
Added in node-oracledb version 26.0.0.
gcpstorage is a plugin that can be loaded in your application to provide
access to configuration information stored in
Google Cloud Storage.
This plugin is implemented as a centralized configuration provider hook
function to handle connection strings which have the
prefix config-gcpstorage, see Google Cloud Storage connection
strings.
To load the gcpstorage plugin in your application, use:
require('oracledb/plugins/configProviders/gcpstorage');
See Using a Google Cloud Storage Centralized Configuration Provider for more information.
24.3. Vector SDK Plugin
Added in node-oracledb version 26.0.0.
Node-oracledb provides a pre-supplied Vector SDK plugin with a high-level interface for Oracle AI Vector Search workflows in Node.js applications. This plugin provides APIs for creating vector stores, storing documents and embeddings, searching by vector or text, creating vector indexes, and managing embedding models in Oracle Database.
The vectorsdk plugin implementation is available in the plugins/vectorsdk
directory of the node-oracledb package. The Vector SDK requires Oracle
Database 23.4 or later.
The vectorsdk plugin provides the OracleVecDB class for creating and
using a database-backed vector store. An OracleVecDB instance stores the
configuration the Vector SDK uses for vector table, document, embedding, and
search operations, such as the database source, table name, vector definition,
and distance metric.
To load the vectorsdk plugin and access the OracleVecDB class, use:
const { OracleVecDB } = require('oracledb/plugins/vectorsdk');
The plugin also provides functions for managing embedding models stored in
Oracle Database and checking vector index build status. To load
OracleVecDB with these additional functions, use:
const {
OracleVecDB,
loadModel,
dropModel,
describeModel,
listModels,
getIndexBuildStatus
} = require('oracledb/plugins/vectorsdk');
For more information on these functions, see this table.
After loading the vectorsdk plugin, you can:
Create an OracleVecDB instance to configure the vector store.
Create the Oracle Database table for the vector store, if needed.
Generate embeddings from text, if needed.
Create a vector index, if needed.
Manage embedding models, if needed.
These are detailed in the subsequent sections.
For information on using the Oracle Database VECTOR data type directly with
node-oracledb, see Using VECTOR Data.
24.3.1. Creating a Vector Store
A vector store is an OracleVecDB instance that contains the configuration
used by the Vector SDK for vector table, document, embedding, and search
operations. This configuration includes the database source,
table name, vector column definition, and distance metric.
Create an OracleVecDB instance to configure how the Vector SDK connects to
the database, which table and columns it uses, and how vector searches are
performed. For example:
const oracledb = require('oracledb');
const {OracleVecDB} = require('oracledb/plugins/vectorsdk');
const connection = await oracledb.getConnection({
user : "hr",
password : mypw, // contains the hr schema password
connectString : "localhost/FREEPDB1"
});
const vectorStore = new OracleVecDB({
dbSource: connection,
tableName: 'MY_VECTOR_TABLE',
vector: {
dimensions: 3,
storageFormat: 'FLOAT32',
storageType: 'DENSE'
},
vectorDistanceType: 'COSINE'
});
For information on the properties of the OracleVecDB class, see
OracleVecDB Class Properties.
Note that creating an OracleVecDB instance does not create any database
objects. It only sets this configuration in your application. To create the
Oracle Database table used by the vector store, see
Creating a Vector Table.
The OracleVecDB constructor takes an options parameter that configures
the vector store. You can configure the following properties in the
options parameter:
Property |
Description |
Required or Optional |
|---|---|---|
|
Custom names and comments for the generated table columns. See Column Configuration for more information. |
Optional |
|
Controls how the Vector SDK gets a database connection for each
operation. It can be a node-oracledb See Database Source Configuration for more information. |
Required |
|
A comment for a table created by the SDK. It must be a non-empty string when specified. See Table Comment Configuration for more information. |
Optional |
|
The distance metric used by searches and indexes. The possible values are COSINE, EUCLIDEAN, EUCLIDEAN_SQUARED, L2_SQUARED, MANHATTAN, DOT, HAMMING, and JACCARD. Note that JACCARD can only be used with BINARY vectors. The default value is COSINE. For BINARY vectors, the default value is HAMMING. See Distance Metrics Configuration for more information. |
Optional |
|
Database-side embedding model parameters. This is required for text-based operations such as See Model Parameters Configuration for more information. |
Optional |
|
Determines whether the configured identifiers are quoted. Set it to true to quote identifiers and preserve their values exactly. The default value is false. See Identifier Quoting Configuration for more information. |
Optional |
|
A string containing a simple table name, or an object with A string always represents one identifier. Use the object form to qualify a table with a schema. |
Required |
|
The vector-column configuration. See Vector Configuration for more information. |
Required |
In an OracleVecDB instance, the configured table and column identifiers
are validated before use. This includes the tableName value, the vector
column name, and any custom column names specified in columns. Do not
include double quotation marks in configured identifier values such as
tableName, the vector column, or column names specified in
columns. When quoteIdentifiers is set to true, the Vector SDK adds
quotation marks when it uses these identifiers in SQL statements.
The following example shows an OracleVecDB instance that configures all
the properties described above:
const vectorStore = new OracleVecDB({
dbSource: connection,
tableName: 'DOCUMENT_VECTORS',
vector: {
column: 'DOC_EMBEDDING',
dimensions: 384,
storageFormat: 'FLOAT32',
storageType: 'DENSE'
},
columns: {
rowid: 'ROW_ID',
id: 'DOCUMENT_ID',
content: {
name: 'DOCUMENT_TEXT',
annotation: 'Source document text'
},
metadata: {
name: 'DOCUMENT_METADATA',
annotation: 'Document metadata'
}
},
description: 'Embeddings for product documentation',
modelParams: {
provider: 'database',
model: 'DOC_EMBED_MODEL'
},
vectorDistanceType: 'COSINE',
quoteIdentifiers: true
});
24.3.1.1. Database Source Configuration
Set the dbSource property to specify how the Vector SDK gets a database
connection for each operation. The value can be a node-oracledb
Connection, a node-oracledb Pool, or a provider function that returns
a promise resolving to either one.
When dbSource is a provider function, the Vector SDK invokes it at the
start of every operation and awaits the promise it returns. The promise must
resolve to a Connection or Pool that is ready for use.
The provider resolves a database source that is managed by the application. Invoking the provider does not imply that it creates a new source. It can return the same source for multiple operations or return another source according to the application’s requirements. The Vector SDK does not store a returned source for use by later operations.
For example, an application can cache pools by credentials so that repeated operations using the same credentials resolve to the same pool:
const poolCache = new Map();
async function getDbSource() {
// "credentials" contains database credentials managed by the application.
// "getCredentialCacheKey()" is defined by the application using an
// identifier that it manages, and returns a stable key that identifies
// the credential set without exposing sensitive values such as passwords.
const cacheKey = getCredentialCacheKey(credentials);
let pool = poolCache.get(cacheKey);
if (pool === undefined) {
pool = await oracledb.createPool({
user: credentials.user,
password: credentials.password,
connectString: credentials.connectString
});
poolCache.set(cacheKey, pool);
}
return pool;
}
const vectorStore = new OracleVecDB({
dbSource: getDbSource,
tableName: 'documents',
vector: {
dimensions: 384
}
});
In this example, the application manages the database credentials and the pool
cache. It implements getCredentialCacheKey() to associate each group of
credentials with its pool without placing sensitive values in the cache key.
When the Vector SDK invokes the provider, the provider uses this key to return
the cached pool or to create and cache one if none exists. The application
is responsible for closing the pools when they are no longer needed. If
concurrent provider invocations can occur before a pool is available, the
application should coordinate pool creation so that the invocations resolve to
the same pool. For example, the application may use a pool manager or cache
the pool creation promise.
The application owns every Connection or Pool supplied through
dbSource and remains responsible for its lifecycle. The Vector SDK does
not create, cache, replace, or close these sources. It also does not create a
Connection or Pool from connection attributes or pool configuration;
the application must create and manage the database source.
When the source is a Pool, the Vector SDK acquires a connection for the
operation and releases that connection when the operation completes, returning
it to the pool. The application remains responsible for closing the pool.
When the source is a Connection, the Vector SDK uses it without closing
it. The application must close the connection when it is no longer needed.
Applications that always use the same Connection or Pool should
normally pass it directly as dbSource. Provider functions are intended for
applications that resolve their database source through an external resource
manager.
See Transaction Management for transaction behavior with connections and pools.
24.3.1.2. Vector Configuration
Set the vector property in an OracleVecDB instance to
define the Oracle Database VECTOR column used by the vector store. This
configuration sets the vector dimensions, vector column name, element format,
and storage representation.
You can configure the vector property with the following values:
Property |
Description |
Required or Optional |
|---|---|---|
|
The vector column name. This property can be a string containing the vector column name, or an object with the following optional properties:
The default value is embedding. |
Optional |
|
A positive integer specifying the number of dimensions in each vector. For BINARY vectors, this property must be a multiple of eight. See Using BINARY Vectors for more information. |
Required |
|
The element format. The possible values are FLOAT32, FLOAT64, INT8, BINARY, or *. Values supplied for a * format column are converted to FLOAT64. The default value is FLOAT32. |
Optional |
|
The storage representation. The possible values are DENSE or SPARSE. The default value is DENSE. BINARY format cannot be combined with the SPARSE storage type. See Using BINARY Vectors and Using SPARSE Vectors for more information. |
Optional |
An example of creating a vector store with a 384-dimensional FLOAT32
vector column named DOC_EMBEDDING is shown below:
const vectorStore = new OracleVecDB({
vector: {
column: 'DOC_EMBEDDING',
dimensions: 384,
storageFormat: 'FLOAT32',
storageType: 'DENSE'
}
});
To add a comment to the vector column while using the default database column
name, specify annotation without name as shown in the example below:
vector: {
dimensions: 384,
column: {
annotation: 'Document embedding'
}
}
24.3.1.3. Column Configuration
Set the columns property in an OracleVecDB instance
to customize the table columns used by the vector store.
You can configure the following properties in the columns object:
Property |
Description |
|---|---|
|
Internal primary key row identifier generated by Oracle Database. If this property is not set, the Vector SDK uses |
|
External document ID supplied by the application or generated by the Vector SDK. If this property is not set, the Vector SDK uses |
|
Document text stored with each vector embedding. If this property is not set, the Vector SDK uses |
|
JSON metadata associated with each document. If this property is not set, the Vector SDK uses |
All the properties listed in the above table can be a string containing the
column name, or an object with optional name and annotation properties.
The name property overrides the default database column name, and the
annotation property adds a comment to the column. If name is omitted,
the default database column name is used.
Configured column names must be unique. The column name distance is
reserved for search results. It cannot be used for any configured table
column, including vector column or columns
specified in columns of an OracleVecDB instance.
For the default database column names and database definitions used when
createVectorTable() creates a table, see
Default Vector SDK table columns.
An example of creating a vector store with custom column names is shown below:
const vectorStore = new OracleVecDB({
columns: {
rowid: 'ROW_ID',
id: 'DOCUMENT_ID',
content: 'DOCUMENT_TEXT',
metadata: 'DOCUMENT_METADATA'
}
});
To add a comment to the content column while using the default database column
name, specify annotation without name as shown in the example below:
columns: {
content: {
annotation: 'Source document text'
}
}
24.3.1.4. Table Comment Configuration
Use the description property in an OracleVecDB instance to add a comment to a table created by the Vector SDK.
When specified, the description value must be a non-empty string.
An example of specifying table and column comments is shown below:
const vectorStore = new OracleVecDB({
description: 'Embeddings for product documentation'
});
24.3.1.5. Distance Metrics Configuration
Set the vectorDistanceType property to specify the distance metric used by vector searches and vector indexes. The distance metric determines how similarity is calculated between the query vector and stored vectors.
The supported distance metrics are COSINE, EUCLIDEAN, EUCLIDEAN_SQUARED, L2_SQUARED, MANHATTAN, DOT, HAMMING, and JACCARD.
The default distance metric is COSINE.
The JACCARD distance metric requires BINARY vectors. For BINARY vectors, the default distance metric is HAMMING. Other supported distance metrics can be used for exact searches on BINARY vectors.
For example:
const vectorStore = new OracleVecDB({
vectorDistanceType: 'COSINE'
});
For more information on distance metrics, see Vector Distance Metrics.
24.3.1.6. Model Parameters Configuration
Set the modelParams property when the vector store
needs to generate embeddings in Oracle Database. The Vector SDK passes
modelParams to Oracle Database when generating embeddings.
The modelParams parameter can identify either a model loaded into Oracle
Database or a supported remote embedding provider configured for use by Oracle
Database.
These model parameters identify the database embedding model used by
text-based operations such as addDocuments(), generateEmbeddings(),
insertWithEmbeddings(), and text-based search().
The modelParams object is passed to Oracle Database when embeddings are
generated.
For a model loaded into Oracle Database, modelParams commonly includes
provider set to database and model set to the loaded model name.
For example:
const vectorStore = new OracleVecDB({
modelParams: {
provider: 'database',
model: 'DOC_EMBED_MODEL'
}
});
For a remote embedding provider, specify the provider-specific parameters required by Oracle Database. For example, to use OpenAI:
modelParams: {
provider: 'openai',
credential_name: 'OPENAI_CRED',
url: 'https://api.openai.com/v1/embeddings',
model: 'text-embedding-3-small'
}
For remote embedding providers, credential_name identifies the Oracle
Database credential used to authenticate with the provider, url specifies
the provider endpoint, and model specifies the embedding model to use.
The supported remote embedding providers include cohere, googleai,
huggingface, ocigenai, openai, vertexai, mistralai, ollama, and
privateai.
For information about loading and managing embedding models in Oracle Database, see Managing Embedding Models.
24.3.1.7. Identifier Quoting Configuration
By default, configured identifiers are unquoted Oracle Database identifiers. The Vector SDK removes leading and trailing whitespace, validates each value as a simple SQL name, and lets Oracle Database apply its normal case-insensitive identifier semantics.
Set quoteIdentifiers to true to make the Vector SDK quote configured
identifiers. The SDK preserves each quoted identifier value exactly, including
case and leading or trailing whitespace. Empty identifiers, double quotation
marks, and null characters are not supported. Supply identifier values without
double quotation marks.
For example:
const vectorStore = new OracleVecDB({
dbSource: connection,
tableName: {
schema: 'hr',
name: 'employees'
},
columns: {
content: 'JOB_DESCRIPTION',
metadata: 'EMPLOYEE_METADATA'
},
vector: {
column: 'EMPLOYEE_EMBEDDING',
dimensions: 384
},
quoteIdentifiers: true
});
This configuration uses the schema-qualified table name
"hr"."employees".
24.3.1.8. OracleVecDB Methods
After creating an OracleVecDB instance, you can use the following methods:
Method |
Description |
|---|---|
|
Generates embeddings for documents and adds them to the vector table. |
|
Adds supplied vectors and their associated documents to the vector table. |
|
Creates an HNSW or IVF vector index for approximate nearest-neighbor searches. |
|
Creates the configured vector table, if it does not already exist. |
|
Deletes documents by external ID, or deletes all documents from the vector table. |
|
Drops the configured vector table. |
|
Generates vector embeddings for text values without storing them. |
|
Inserts rows from a source table into the vector table, generating embeddings from source text values. |
|
Searches for documents by supplied vector or by text. |
24.3.1.9. Vector SDK Helper Functions
The vectorsdk plugin also provides the following helper functions for
managing embedding models stored in Oracle Database and for checking vector
index build status. These functions are called directly from the plugin
export.
Function |
Description |
|---|---|
|
A function that loads an embedding model into Oracle Database. |
|
A function that drops an embedding model from Oracle Database. |
|
A function that returns metadata for a loaded embedding model. This function requires Oracle Database 26.2 or later. |
|
A function that lists models in the current schema. This function requires Oracle Database 26.2 or later. |
|
A function that returns vector index build status information for a table. This function requires Oracle Database 26.2 or later. |
24.3.2. Creating a Vector Table
To create the Oracle Database table configured in the
OracleVecDB instance if the table does not already
exist, use OracleVecDB.createVectorTable(). For example:
const tableName = await vectorStore.createVectorTable();
The table is created using the configured table name, vector column definition, column names, and optional table and column comments. This method returns the SQL table identifier used by the SDK.
When createVectorTable() is called, the Vector SDK creates the following
columns by default. You can override these default column names by setting the
corresponding property in columns or by setting vector.column in the
vector property.
Property |
Default Database Column Name |
Database Type or Definition |
Description |
|---|---|---|---|
|
id |
RAW(16) DEFAULT SYS_GUID() PRIMARY KEY |
Internal primary-key row identifier generated by Oracle Database. |
|
external_id |
VARCHAR2(255) UNIQUE |
External document ID supplied by the application or generated by the Vector SDK. |
|
embedding |
VECTOR with the configured dimensions, format, and storage |
Vector embedding used for similarity searches. |
|
text |
CLOB |
Document text associated with the vector embedding. |
|
metadata |
JSON |
JSON metadata associated with the document. |
24.3.3. Vector Input Representations
The Vector SDK accepts several JavaScript representations for vector values and converts them to the vector format configured for the vector store.
The methods OracleVecDB.addVectors() and vector-based
OracleVecDB.search() accept JavaScript arrays, Float32Array, Float64Array,
and Int8Array values. The SDK converts them to the configured vector format.
For a SPARSE vector store, the SDK accepts either dense vector input, such
as a JavaScript array or supported TypedArray, or an
oracledb.SparseVector object. When dense input
is used with a SPARSE vector store, the SDK converts it to sparse form by
storing only the non-zero values and their indices. Zero values are omitted
from the sparse representation. An oracledb.SparseVector object can only
be used with a vector store whose vector storage
value is SPARSE. It cannot be used with a DENSE vector store.
For INT8 vectors, input values are rounded to integers before they are stored or searched. Each rounded value must be in the range -128 through 127.
For BINARY vectors, you can pass a Uint8Array containing the packed binary
representation of the vector. The Uint8Array must contain exactly
dimensions / 8 bytes. For example, a BINARY vector with 16 dimensions
requires a Uint8Array with 2 bytes. You can also pass a JavaScript array or
another supported TypedArray for a BINARY vector. In this case, the SDK
converts the input to packed binary form by treating positive values as 1
and zero or negative values as 0.
24.3.4. Adding Supplied Vectors
Use OracleVecDB.addVectors() when your application already has vector
embeddings, such as embeddings generated by an external model or service.
This method stores each supplied vector with its associated document content
and metadata in the vector table. For example:
const ids = await vectorStore.addVectors(
[
new Float32Array([1, 0, 0]),
new Float32Array([0, 1, 0])
],
[
{
content: 'Oracle Database supports vector search.',
metadata: {category: 'database', year: 2026}
},
{
content: 'Node.js is a JavaScript runtime.',
metadata: {category: 'javascript', year: 2026}
}
],
{
ids: ['document-1', 'document-2'],
autoCommit: true
}
);
The parameters of OracleVecDB.addVectors() are:
Parameter |
Description |
Required or Optional |
|---|---|---|
|
A non-empty array of vector values. Each vector must follow the vector input rules. |
Required |
|
A non-empty array of document objects. The number of documents must match the number of vectors. Each document must contain a non-empty string |
Required |
|
An object that contains options for document IDs, upserts, and commits. See addVectors(): options Parameter Properties. |
Optional |
The options object can contain the following properties:
Property |
Description |
Required or Optional |
|---|---|---|
|
A boolean value which commits the inserted or updated rows. It must be set to true for |
Required |
|
An array of strings that contains external document IDs. The number of IDs must match the number of documents. Each ID must be a non-empty string no longer than 255 bytes. If omitted, the SDK generates UUIDs. The method returns the supplied or generated IDs in input order. |
Optional |
|
A boolean value which indicates whether to update an existing row with the same external document ID. When set to true, updates an existing row with the same external document ID. An upsert replaces its vector, content, and metadata while preserving its internal RAW row ID. If omitted or false, duplicate IDs produce a database constraint error. |
Optional |
24.3.5. Generating and Adding Embeddings
The Vector SDK can generate embeddings in Oracle Database by using the embedding model configured with modelParams in the OracleVecDB instance. This lets your application pass document text to the SDK instead of generating vector embeddings separately. See Model Parameters Configuration for more information.
The methods described below use the embedding model specified by
modelParams to generate vector embeddings from text. See
Managing Embedding Models.
24.3.5.1. Adding Documents
Use addDocuments() to generate embeddings from document content and store
the documents and embeddings in the vector table. For example:
const ids = await vectorStore.addDocuments(
[
{
content: 'Oracle Database supports vector search.',
metadata: {category: 'database'}
},
{
content: 'Node.js applications can use node-oracledb.',
metadata: {category: 'javascript'}
}
],
{
ids: ['document-1', 'document-2'],
autoCommit: true
}
);
The method uses the same document, ID, and upsert rules as
addVectors() and also requires that autoCommit be set to true.
See addVectors(): options Parameter Properties for more information on these properties.
The addDocuments() method returns IDs in input order. For large document
sets, divide the input into smaller chunks and call addDocuments() once
for each chunk.
24.3.5.2. Generating Embeddings Without Storing Them
Use generateEmbeddings() to generate embeddings for text values without
inserting rows into the vector table. Pass a non-empty array of non-empty
strings to the method. For example:
const embeddings = await vectorStore.generateEmbeddings([
'Oracle Database supports vector search.',
'Node.js is a JavaScript runtime.'
]);
The method returns one embedding for each input string, preserving input order.
For large input arrays, divide the input into smaller chunks and call
generateEmbeddings() once for each chunk.
24.3.5.3. Inserting from a Source Table
Use insertWithEmbeddings() to read rows from another table, generate an
embedding from each row’s content, and insert the results into the configured
vector table. For example:
const rowsAffected = await vectorStore.insertWithEmbeddings({
sourceTable: {
schema: 'My Schema',
name: 'Source Documents'
},
idColumn: 'Document ID',
contentColumn: 'Document Text',
metadataColumn: 'Document Metadata',
quoteSource: true,
autoCommit: true
});
The insertWithEmbeddings() method requires
modelParams to be configured on the OracleVecDB
instance because embeddings are generated from the source table’s content
column.
The insertWithEmbeddings() method takes a single options parameter.
You can specify the following properties in the options parameter:
Property |
Description |
Required or Optional |
|---|---|---|
|
A boolean that indicates whether the insert operation is committed automatically. |
Optional |
|
A string that identifies the name of the source column containing text values to embed. |
Required |
|
A string that identifies the name of the source column containing external document IDs. |
Required |
|
A string that identifies the name of the source column containing document metadata. |
Optional |
|
A boolean that determines whether source table and column identifiers are quoted and preserved exactly. The default value is false. |
Optional |
|
A string containing simple source table name, or an object
containing its |
Required |
Supply raw source identifier values without double quotation marks. When
quoteSource is true, the SDK preserves identifier values exactly,
including case and whitespace, and safely quotes them. The quoteSource
option affects only the source table and source columns. The destination vector
table continues to use the quoteIdentifiers setting configured on the
OracleVecDB instance.
Note that this method does not provide an upsert option.
24.3.6. Searching a Vector Store
Use OracleVecDB.search() to find documents in the vector store that are
most similar to a supplied query. You can search by using a
vector or text.
You can limit the number of results, request a target search accuracy, filter results by document metadata, and optionally include the stored vector in each result.
The SDK requests an approximate search. Oracle Database uses an eligible vector
index when one is available; otherwise, or when the optimizer does not use the
index, it returns exact results instead. In that case, an accuracy setting
has no effect.
The search() method takes a single options object that specifies the
query input, result count, target accuracy, metadata filter, and whether to
include vectors in the returned results.
You can specify the following properties in the options parameter:
Parameter |
Description |
Required or Optional |
|---|---|---|
|
An object containing exactly one of If set to If set to |
Required |
|
A positive integer specifying the maximum number of results. The default value is 5. |
Optional |
|
An integer from 1 through 100 specifying target approximate search accuracy. If omitted, Oracle Database uses its default target accuracy. |
Optional |
|
An object that contains the metadata filter. See Filtering by Metadata. |
Optional |
|
A boolean that determines whether to include the stored vector in each result. If set to true, it includes the stored vector in each result. The default value is false. |
Optional |
For both vector-based and text-based searches, search() returns an array
of result objects, ordered by ascending distance. Each result object contains
the id, content, metadata, and distance properties, for
example:
[
{
id: 'document-1',
content: 'Oracle Database supports vector search.',
metadata: {category: 'database'},
distance: 0
}
]
When includeVector is true, each result also contains the vector
property. Distance values have metric-specific meanings and should not be
compared across different metrics.
24.3.6.1. Search by Vector
Use vector in the queryBy property of search() to search with a
vector supplied by your application. This is useful when the query embedding
has already been generated outside the Vector SDK.
const results = await vectorStore.search({
queryBy: {
vector: new Float32Array([1, 0, 0])
},
topK: 5
});
The query vector must follow the vector input rules described in Vector Input Representations. The SDK converts the supplied vector to the configured vector format before running the search.
24.3.6.2. Search by Text
Use text in the queryBy property of search() to search with text
supplied by your application. The Vector SDK generates an embedding for the
query text in Oracle Database by using the model configured with
modelParams, and then uses that embedding to search
the vector store. Text-based search requires modelParams to be configured
on the OracleVecDB instance so that the Vector SDK can generate an
embedding for the query text in Oracle Database.
For example:
const results = await vectorStore.search({
queryBy: {
text: 'How does Oracle Database perform vector search?'
},
topK: 5
});
24.3.7. Filtering by Metadata
Use the filter option of the OracleVecDB.search() method to restrict
search results by values stored in the metadata column. Metadata filters are
applied before the nearest vector matches are returned.
Metadata fields can be matched directly by specifying field names and values in
the filter object:
const results = await vectorStore.search({
queryBy: {vector: [1, 0, 0]},
filter: {
category: 'database'
}
});
Multiple fields in one filter object are implicitly combined with AND.
For example, the following filter matches only documents where both conditions
are true: category is database and the nested document.year value is
greater than or equal to 2024.
filter: {
category: 'database',
'document.year': {$gte: 2024}
}
Use dotted field names to access nested metadata properties. Filter paths must
contain one or more identifier-like components separated by periods, such as
tenant or document.year. Arbitrary JSON path syntax is not accepted. An
empty top-level filter object applies no filter.
The supported comparison operators are:
Operator |
Operand |
Description |
|---|---|---|
|
JSON scalar |
Matches values equal to the operand. |
|
JSON scalar |
Matches unequal values and documents where the field is absent. |
|
String or finite number |
Matches values greater than the operand. |
|
String or finite number |
Matches values greater than or equal to the operand. |
|
String or finite number |
Matches values less than the operand. |
|
String or finite number |
Matches values less than or equal to the operand. |
|
Two values of the same supported type |
Matches the inclusive range. |
|
Non-empty array of JSON scalars |
Matches at least one value in the array. |
|
Non-empty array of JSON scalars |
Matches none of the values, including when the field is absent. |
|
String |
Matches the specified Oracle JSON path pattern. |
|
Boolean |
Tests whether the field exists. |
An array value is shorthand for the $in operator. Multiple operators
specified for the same metadata field are combined with AND. For example,
this filter matches documents whose category is either database or
javascript:
filter: {
category: ['database', 'javascript']
}
Use $and and $or with non-empty arrays to create logical expressions.
For example, this filter matches documents whose category is database,
or documents whose category is javascript and whose year value is
greater than or equal to 2025:
filter: {
$or: [
{category: 'database'},
{
$and: [
{category: 'javascript'},
{year: {$gte: 2025}}
]
}
]
}
A logical filter node must contain exactly one logical operator. A field-level operator object and each logical-array item must be non-empty.
24.3.8. Creating a Vector Index
Use OracleVecDB.createVectorIndex() to create a vector index on the vector
column configured for the OracleVecDB instance. Vector indexes improve
approximate nearest-neighbor searches over large vector tables. The Vector SDK
supports Hierarchical Navigable Small World (HNSW) and Inverted File Flat (IVF)
index types. For more information on these indexes, see the Manage the
Different Categories of Vector Indexes section in
the Oracle AI Vector Search User’s Guide.
Oracle Database supports only the HAMMING and JACCARD distance metrics for vector indexes on BINARY vector columns.
Note
The database user must have the privileges required to create a vector
index. Creating an HNSW index also requires sufficient vector pool memory,
configured using VECTOR_MEMORY_SIZE.
For an HNSW index, set the type parameter to HNSW in
createVectorIndex() and specify HNSW parameters. For example:
await vectorStore.createVectorIndex({
indexName: 'DOCUMENT_VECTOR_IDX',
type: 'HNSW',
accuracy: 90,
parameters: {
neighbors: 16,
efConstruction: 200
}
});
The createVectorIndex() method takes a single options object that
specifies the index name, index type, target accuracy, index-specific
parameters, parallel creation degree, partitioning scheme, and any columns
to include.
You can specify the following properties in the options parameter:
Parameter |
Description |
Required or Optional |
|---|---|---|
|
The index name. |
Required |
|
An object containing HNSW or IVF specific parameters. For an HNSW index, the commonly used parameters are:
For an IVF index, use |
Required |
|
The index type. The possible values are HNSW or IVF. The default value is HNSW. |
Optional |
|
An integer from 1 through 100 specifying the target accuracy. |
Optional |
|
A positive integer specifying the degree of parallelism used during index creation. The default value is 1. |
Optional |
|
The partitioning scheme. The possible values are GLOBAL or LOCAL. The default value is GLOBAL. |
Optional |
|
An optional array of additional table columns to include in the index. |
Optional |
For an IVF index, set type to IVF in createVectorIndex() and
specify the IVF parameters:
await vectorStore.createVectorIndex({
indexName: 'DOCUMENT_VECTOR_IVF_IDX',
type: 'IVF',
parameters: {
partitions: 16
}
});
24.3.8.1. Checking Index Build Status
Use getIndexBuildStatus() to retrieve build status information for vector
indexes on a table. Pass a node-oracledb Connection and the table name to
check. For example:
const status = await getIndexBuildStatus(
connection,
'DOCUMENT_VECTORS'
);
The function returns index build status information as a JavaScript object.
Note
This function requires Oracle Database 26.2 or later.
24.3.9. Managing Embedding Models
An Open Neural Network Exchange (ONNX) model is a portable machine learning model format. In Oracle AI Vector Search workflows, an ONNX embedding model can be loaded into Oracle Database and used to generate vector embeddings from text.
Before you can use an ONNX embedding model in modelParams, the model must
be loaded into Oracle Database. You can use the model management functions to
load, describe, list, and drop models. These functions take a node-oracledb
Connection as their first argument.
Before loading a model, a database administrator must create an Oracle directory object for the database server directory that contains the ONNX file. The administrator must also grant the application user the required privileges to read from that directory and to create, describe, list, or drop models.
This section describes how to manage ONNX embedding models loaded into Oracle
Database. You do not need to use these functions when modelParams
specifies to use a remote embedding provider.
24.3.9.1. Loading a Model
Use loadModel() to load an embedding model into Oracle Database.
Currently, this function supports only model files in ONNX format. Pass a
node-oracledb Connection as the first argument and the options
parameter as the second argument. For example:
await loadModel(connection, {
dirName: 'MODEL_DIR',
modelFile: 'document_embedding.onnx',
modelName: 'EMBED_MODEL'
});
You can specify the following properties in the options parameter:
Property |
Description |
Required or Optional |
|---|---|---|
|
Oracle directory object name for the database server directory that contains the model file. |
Required |
|
Name of the model file to load. |
Required |
|
Name to assign to the loaded model in Oracle Database. |
Required |
|
Plain object containing metadata associated with the model. |
Optional |
24.3.9.2. Describing and Listing Models
Use describeModel() to return information about one loaded model.
Pass a node-oracledb Connection as the first argument and the model name
as the second argument. For example:
const description = await describeModel(connection, 'EMBED_MODEL');
The function returns the parsed model description as a JavaScript object. For example:
{
"model_name": "EMBED_MODEL",
"algorithm": "ONNX",
"mining_function": "EMBEDDING",
"creation_date": "2026-09-07T00:44:53.000000+01:00",
"attributes": [
{
"name": "DATA",
"value": "TEXT",
"data_type": "VARCHAR2",
"data_length": 32767,
"vector_info": null
},
{
"name": "ORA$ONNXTARGET",
"value": "VECTOR",
"data_type": "VECTOR",
"data_length": 1593,
"vector_info": "VECTOR(384,FLOAT32)"
}
]
}
The returned attributes and their values depend on the loaded model.
Use listModels() to return information about models in the current schema.
Pass a node-oracledb Connection as the argument. For example:
const models = await listModels(connection);
console.log(models);
For example, the output may contain:
{
models: [
{
model_name: 'EMBED_MODEL',
algorithm: 'ONNX',
mining_function: 'EMBEDDING',
creation_date: '2026-09-07T00:44:53.000000000+01:00',
attributes: [Array]
},
{
model_name: 'EMBED_MODEL_TEST',
algorithm: 'ONNX',
mining_function: 'EMBEDDING',
creation_date: '2026-09-07T00:48:05.000000000+01:00',
attributes: [Array]
}
]
}
Each item in models has the same structure as the object returned by
describeModel().
Note
describeModel() and listModels() require Oracle Database 26.2 or
later.
24.3.9.3. Dropping a Model
Use dropModel() to remove an embedding model from Oracle Database. Pass a
node-oracledb Connection as the first argument and the model name as the
second argument. For example:
await dropModel(connection, 'EMBED_MODEL', true);
The optional third argument controls whether the model is forcibly dropped. If
not specified, the value defaults to false. On success, dropModel()
completes without returning a value.
24.3.10. Deleting Documents
Use delete() to delete documents from the vector table. To delete specific
documents, pass their external document IDs in the ids array. For example:
const result = await vectorStore.delete({
ids: ['document-1', 'document-2'],
autoCommit: true
});
IDs must be non-empty strings no longer than 255 bytes. The method returns an
object whose message property reports the number of deleted records.
To delete every document from the vector table, set deleteAll to true:
const result = await vectorStore.delete({
deleteAll: true
});
The deleteAll property cannot be set to true when the ids property
contains a non-empty array. Setting deleteAll to true truncates the
vector table, commits implicitly, and cannot be rolled back. If neither a
non-empty ids array nor deleteAll: true is supplied, the method
performs no operation.
24.3.11. Dropping a Vector Table
Use dropTable() to drop the Oracle Database table configured in the
OracleVecDB instance, if it exists:
await vectorStore.dropTable();
By default, the dropped table is moved to the recycle bin. Pass true to purge the table instead:
await vectorStore.dropTable(true);
On success, dropTable() completes without returning a value. Dropping a
table is a DDL operation and commits implicitly.
24.3.12. Transaction Management
When calling addVectors() or addDocuments(), set the autoCommit
property to true. Calls that omit autoCommit or set it to false
reject before executing SQL.
The insertWithEmbeddings() and ID-based
delete() methods pass their optional autoCommit value through to
node-oracledb. When these methods use a directly supplied connection and
autoCommit is omitted or set to false, the application must explicitly
call connection.commit() or connection.rollback().
When a pool is used, the SDK acquires a connection from the pool for each
operation and calls connection.close() when the operation completes,
returning the connection to the pool. Set autoCommit to true for
pool-backed write operations; otherwise, the connection is returned to the
pool before the application can commit the transaction.
Setting deleteAll to true truncates the vector table, commits
implicitly, and cannot be rolled back. Table and vector index DDL operations
also commit implicitly.