oracledb 7.0.0 → 26.0.0

package/plugins/vectorsdk/utils.js

@@ -0,0 +1,370 @@
+// Copyright (c) 2026, Oracle and/or its affiliates.
+
+//-----------------------------------------------------------------------------
+//
+// This software is dual-licensed to you under the Universal Permissive License
+// (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+// 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+// either license.
+//
+// If you elect to accept the software under the Apache License, Version 2.0,
+// the following applies:
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//-----------------------------------------------------------------------------
+
+'use strict';
+
+const oracledb = require('oracledb');
+
+//-----------------------------------------------------------------------------
+// Constants
+//-----------------------------------------------------------------------------
+const DISTANCE_METRICS = new Set([
+  'COSINE',
+  'EUCLIDEAN',
+  'MANHATTAN',
+  'HAMMING',
+  'JACCARD',
+  'DOT',
+  'L2_SQUARED',
+  'EUCLIDEAN_SQUARED'
+]);
+
+//-----------------------------------------------------------------------------
+// Distance metric
+//-----------------------------------------------------------------------------
+function normalizeVectorDistanceType(vectorDistanceType) {
+  if (vectorDistanceType == null) {
+    return null;
+  }
+  const metric = String(vectorDistanceType).trim().toUpperCase();
+  if (!DISTANCE_METRICS.has(metric)) {
+    throw new TypeError(
+      `Distance Metric must be one of: ${[...DISTANCE_METRICS].join(', ')}`
+    );
+  }
+  return metric;
+}
+
+//-----------------------------------------------------------------------------
+// Assertions
+//-----------------------------------------------------------------------------
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+
+  // Accepts only ordinary objects, reject class instances and built-in objects
+  // such as Date, Map, and Set
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function assertCondition(condition, message) {
+  if (!condition) {
+    throw new TypeError(message);
+  }
+}
+
+function assertPlainObject(value, name) {
+  assertCondition(
+    isPlainObject(value),
+    `${name} must be an object.`
+  );
+}
+
+function assertOptionalPlainObject(value, name) {
+  if (value != null) {
+    assertPlainObject(value, name);
+  }
+}
+
+function assertBoolean(value, name) {
+  assertCondition(
+    typeof value === 'boolean',
+    `${name} must be a boolean.`
+  );
+}
+
+function assertOptionalBoolean(value, name) {
+  if (value !== undefined) {
+    assertBoolean(value, name);
+  }
+}
+
+function assertNonEmptyString(value, name) {
+  assertCondition(
+    typeof value === 'string' && value.trim() !== '',
+    `${name} must be a non-empty string.`
+  );
+}
+
+function assertPositiveInteger(value, name) {
+  assertCondition(
+    Number.isInteger(value) && value > 0,
+    `${name} must be a positive integer.`
+  );
+}
+
+function assertIntegerInRange(value, name, min, max) {
+  assertCondition(
+    Number.isInteger(value) && value >= min && value <= max,
+    `${name} must be an integer between ${min} and ${max}.`
+  );
+}
+
+function assertArray(value, name) {
+  assertCondition(
+    Array.isArray(value),
+    `${name} must be an array.`
+  );
+}
+
+function assertNonEmptyArray(value, name) {
+  assertCondition(
+    Array.isArray(value) && value.length > 0,
+    `${name} must be a non-empty array.`
+  );
+}
+
+function assertOptionalArray(value, name) {
+  if (value != null) {
+    assertArray(value, name);
+  }
+}
+
+//-----------------------------------------------------------------------------
+// Database helpers
+//-----------------------------------------------------------------------------
+async function readLobAsString(value) {
+  // CLOB output may already be materialized or may expose the Lob getData API.
+  if (value == null || typeof value === 'string') return value;
+  if (typeof value.getData !== 'function') {
+    throw new Error(
+      'Expected a CLOB LOB or string value from Oracle Database.'
+    );
+  }
+  try {
+    return await value.getData();
+  } finally {
+    value.destroy();
+  }
+}
+
+function assertDatabaseVersion(connection, label) {
+  // oracleServerVersion encodes 23.26.2.0.0 as 2326020000.
+  if (connection.oracleServerVersion < 2326020000) {
+    throw new Error(
+      `${label} requires Oracle Database 23.26.2.0.0 or later.`
+    );
+  }
+}
+
+//-----------------------------------------------------------------------------
+// Vector preparation
+//-----------------------------------------------------------------------------
+function isVectorValue(value) {
+  return (value instanceof Float32Array ||
+    value instanceof Float64Array ||
+    value instanceof Int8Array || (Object.getPrototypeOf(value)
+      === Uint8Array.prototype) || value instanceof oracledb.SparseVector);
+}
+
+function assertDimensions(vector, definition) {
+  const dimensions = vector instanceof oracledb.SparseVector
+    ? vector.numDimensions
+    : vector.length;
+
+  if (dimensions !== definition.dimensions) {
+    throw new TypeError(
+      `Vector dimensions must be ${definition.dimensions}; ` +
+      `received ${dimensions}`
+    );
+  }
+}
+
+function convertInt8(values) {
+  const converted = new Int8Array(values.length);
+
+  for (let index = 0; index < values.length; index++) {
+    const value = values[index];
+    if (!Number.isFinite(value)) {
+      throw new TypeError(
+        `Vector value at index ${index} must be finite.`
+      );
+    }
+
+    const rounded = Math.round(value);
+    if (rounded < -128 || rounded > 127) {
+      throw new TypeError(
+        `INT8 vector value at index ${index} must be within [-128, 127].`
+      );
+    }
+    converted[index] = rounded;
+  }
+
+  return converted;
+}
+
+function packBinaryVector(values, dimensions) {
+  if (values.length !== dimensions) {
+    throw new TypeError(
+      `Vector dimensions must be ${dimensions}; received ${values.length}`
+    );
+  }
+
+  const packed = new Uint8Array(dimensions / 8);
+
+  for (let index = 0; index < dimensions; index++) {
+    const value = values[index];
+
+    if (!Number.isFinite(value)) {
+      throw new TypeError(
+        `Vector value at index ${index} must be finite.`
+      );
+    }
+
+    // Pack positive dimensions as one, from the most significant bit to the
+    // least significant bit within each byte.
+    if (value > 0) {
+      packed[index >> 3] |= 1 << (7 - (index & 7));
+    }
+  }
+
+  return packed;
+}
+
+function convertValuesForFormat(values, format) {
+  switch (format) {
+    case 'FLOAT32':
+      return values instanceof Float32Array
+        ? values
+        : new Float32Array(values);
+    // We use a consistent default for wildcard (*) formats. Otherwise, similarity
+    // search fails when the stored and query vector formats do not match.
+    case '*':
+    case 'FLOAT64':
+      return values instanceof Float64Array
+        ? values
+        : new Float64Array(values);
+    case 'INT8':
+      return values instanceof Int8Array
+        ? values
+        : convertInt8(values);
+    default:
+      throw new TypeError(
+        `Unsupported vector format: ${format}.`
+      );
+  }
+}
+
+function convertDenseVector(values, definition) {
+  if (definition.storageFormat === 'BINARY') {
+    if (values instanceof Uint8Array) {
+      if (values.length !== definition.dimensions / 8) {
+        throw new TypeError(
+          `BINARY vector must contain ${definition.dimensions / 8} bytes.`
+        );
+      }
+      return values;
+    }
+    return packBinaryVector(values, definition.dimensions);
+  }
+
+  assertDimensions(values, definition);
+  return convertValuesForFormat(values, definition.storageFormat);
+}
+
+function convertDenseToSparseVector(vector, format) {
+  // Convert before identifying nonzero values. This matters for INT8 because
+  // values may become zero after rounding.
+  const converted = convertValuesForFormat(vector, format);
+
+  const indices = [];
+  const values = [];
+
+  for (let i = 0; i < converted.length; i++) {
+    if (converted[i] !== 0) {
+      indices.push(i);
+      values.push(converted[i]);
+    }
+  }
+
+  return new oracledb.SparseVector({
+    numDimensions: vector.length,
+    indices: new Uint32Array(indices),
+    values: new converted.constructor(values),
+  });
+}
+
+function prepareVector(vector, vectorDefinition) {
+
+  if (vector == null) {
+    throw new TypeError('Vector must not be null or undefined.');
+  }
+
+  if (!Array.isArray(vector) && !isVectorValue(vector)) {
+    throw new TypeError('Unsupported vector representation.');
+  }
+
+  const definition = vectorDefinition;
+
+  if (definition.storageType === 'SPARSE') {
+    if (vector instanceof oracledb.SparseVector) {
+      assertDimensions(vector, definition);
+      return new oracledb.SparseVector({
+        numDimensions: vector.numDimensions,
+        indices: vector.indices,
+        values: convertValuesForFormat(
+          vector.values,
+          definition.storageFormat
+        )
+      });
+    }
+
+    assertDimensions(vector, definition);
+    // Convert a dense input when the configured column uses sparse storage.
+    return convertDenseToSparseVector(vector, definition.storageFormat);
+  }
+
+  if (vector instanceof oracledb.SparseVector) {
+    throw new TypeError(
+      'A SparseVector cannot be used with DENSE storage.'
+    );
+  }
+
+  return convertDenseVector(vector, definition);
+}
+
+//-----------------------------------------------------------------------------
+// Exports
+//-----------------------------------------------------------------------------
+
+module.exports = {
+  normalizeVectorDistanceType,
+  prepareVector,
+  assertDatabaseVersion,
+  readLobAsString,
+  assertBoolean,
+  assertIntegerInRange,
+  assertNonEmptyArray,
+  assertNonEmptyString,
+  assertOptionalArray,
+  assertOptionalBoolean,
+  assertOptionalPlainObject,
+  assertPlainObject,
+  assertPositiveInteger,
+  isPlainObject
+};

package/plugins/vectorsdk/vectorEmbedding.js

@@ -0,0 +1,223 @@
+// Copyright (c) 2026, Oracle and/or its affiliates.
+
+//-----------------------------------------------------------------------------
+//
+// This software is dual-licensed to you under the Universal Permissive License
+// (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+// 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+// either license.
+//
+// If you elect to accept the software under the Apache License, Version 2.0,
+// the following applies:
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//-----------------------------------------------------------------------------
+
+'use strict';
+
+const oracledb = require('oracledb');
+const { normalizeIdentifier } = require('./vectorSchema.js');
+const {
+  assertBoolean,
+  assertNonEmptyString,
+  assertOptionalPlainObject,
+  assertPlainObject,
+  readLobAsString,
+  assertDatabaseVersion,
+  assertNonEmptyArray
+} = require('./utils.js');
+
+//-----------------------------------------------------------------------------
+// generateEmbeddings()
+
+// Generate a vector embedding for input text using a preloaded model.
+//-----------------------------------------------------------------------------
+async function generateEmbeddings(connection, modelParams, texts) {
+  assertNonEmptyArray(texts, 'texts');
+  assertPlainObject(modelParams, 'modelParams');
+
+  const embeddingSql = `
+    DECLARE
+      generated_embedding VECTOR;
+    BEGIN
+      generated_embedding := DBMS_VECTOR.UTL_TO_EMBEDDING(
+        :query_text,
+        :model_params
+      );
+      :embedding := generated_embedding;
+    END;
+  `;
+
+  const result = await connection.executeMany(
+    embeddingSql,
+    texts.map((text, index) => {
+      assertNonEmptyString(text, `texts[${index}]`);
+      return {
+        query_text: text,
+        model_params: modelParams
+      };
+    }),
+    {
+      bindDefs: {
+        query_text: {
+          type: oracledb.DB_TYPE_CLOB
+        },
+        model_params: {
+          type: oracledb.DB_TYPE_JSON
+        },
+        embedding: {
+          dir: oracledb.BIND_OUT,
+          type: oracledb.DB_TYPE_VECTOR
+        }
+      }
+    }
+  );
+
+  return result.outBinds.map((binds) => binds.embedding);
+}
+
+//-----------------------------------------------------------------------------
+// loadModel()
+
+// Load an embedding model into Oracle AI Database.
+//-----------------------------------------------------------------------------
+async function loadModel(connection, options) {
+  assertPlainObject(options, 'options');
+
+  const {
+    dirName,
+    modelFile,
+    modelName,
+    modelMetadata = null,
+  } = options;
+
+  assertNonEmptyString(modelFile, 'options.modelFile');
+  assertOptionalPlainObject(
+    modelMetadata,
+    'options.modelMetadata'
+  );
+
+  const binds = {
+    dir_name: normalizeIdentifier(dirName, 'options.dirName'),
+    model_file: modelFile,
+    model_name: normalizeIdentifier(modelName, 'options.modelName')
+  };
+
+  const plsqlParams = [
+    'directory => :dir_name',
+    'file_name => :model_file',
+    'model_name => :model_name'
+  ];
+
+  if (modelMetadata != null) {
+    binds.model_metadata = {
+      val: modelMetadata,
+      type: oracledb.DB_TYPE_JSON
+    };
+    plsqlParams.push('metadata => :model_metadata');
+  }
+
+  const plsql = `
+    BEGIN
+      DBMS_VECTOR.LOAD_ONNX_MODEL(
+        ${plsqlParams.join(', ')}
+      );
+    END;
+  `;
+
+  await connection.execute(plsql, binds);
+}
+
+//-----------------------------------------------------------------------------
+// describeModel()
+
+// Return metadata for a loaded model, including its algorithm, mining function,
+// creation date, and attributes.
+//-----------------------------------------------------------------------------
+async function describeModel(connection, modelName) {
+  // requires Oracle Database 23.26.2.0.0 or later
+  assertDatabaseVersion(connection, 'describeModel()');
+
+  const binds = {
+    model_name: normalizeIdentifier(modelName, 'modelName'),
+    result: {
+      dir: oracledb.BIND_OUT,
+      type: oracledb.STRING,
+      maxSize: 1024 * 1024
+    }
+  };
+
+  const plsql = `
+    BEGIN
+      :result := DBMS_VECTOR_DATABASE.DESCRIBE_MODEL(MODEL_NAME  => :model_name);
+    END;`;
+
+  const res = await connection.execute(plsql, binds);
+  return JSON.parse(res.outBinds.result);
+}
+
+//-----------------------------------------------------------------------------
+// listModels()
+
+// Return the models available in the current schema.
+//-----------------------------------------------------------------------------
+async function listModels(connection) {
+  // requires Oracle Database 23.26.2.0.0 or later
+  assertDatabaseVersion(connection, 'listModels()');
+
+  const binds = {
+    result: {
+      dir: oracledb.BIND_OUT,
+      type: oracledb.DB_TYPE_CLOB
+    }
+  };
+
+  const plsql = `
+    BEGIN
+      :result := DBMS_VECTOR_DATABASE.LIST_MODELS();
+    END;`;
+
+  const res = await connection.execute(plsql, binds);
+  const output = await readLobAsString(res.outBinds.result);
+  return JSON.parse(output);
+}
+
+//-----------------------------------------------------------------------------
+// dropModel()
+
+// Remove an embedding model from Oracle AI Database.
+//-----------------------------------------------------------------------------
+async function dropModel(connection, modelName, force = false) {
+  assertBoolean(force, 'force');
+
+  const safeModelName = normalizeIdentifier(modelName, 'modelName');
+  const dropModelSql = `
+      BEGIN
+        DBMS_VECTOR.DROP_ONNX_MODEL(
+          model_name => :model_name,
+          force => ${force ? 'TRUE' : 'FALSE'}
+        );
+      END;
+    `;
+
+  await connection.execute(dropModelSql, { model_name: safeModelName });
+}
+
+module.exports = {
+  generateEmbeddings,
+  loadModel,
+  describeModel,
+  listModels,
+  dropModel
+};