@oracle/langchain-oracledb 0.1.1 → 1.0.0

package/dist/vectorstores.js

@@ -1,8 +1,18 @@
+import crypto from "node:crypto";
 import oracledb from "oracledb";
-import { createHash } from "crypto";
 import { VectorStore, } from "@langchain/core/vectorstores";
 import { Document } from "@langchain/core/documents";
 import { maximalMarginalRelevance } from "@langchain/core/utils/math";
+import { LangChainOracleError, ErrorCode, createErrorFromCodeWithCause, isLangChainOracleError, throwError, } from "./errors.js";
+export { LangChainOracleError, ErrorCode };
+export { LangChainOracleError as OracleVSError, ErrorCode as OracleVSErrorCode, };
+export { isLangChainOracleError };
+function validateMetadataKey(column) {
+    const pattern = /^[a-zA-Z0-9_.[\],\s*]*$/;
+    if (!column || !pattern.test(column)) {
+        throwError(ErrorCode.FILTER_INVALID_METADATA_KEY, column);
+    }
+}
 export function generateWhereClause(dbFilter, bindValues) {
     // Handle $and
     if ("$and" in dbFilter && Array.isArray(dbFilter.$and)) {
@@ -37,6 +47,7 @@ export function generateWhereClause(dbFilter, bindValues) {
         : conditions[0];
 }
 function generateOperatorCondition(column, operator, value, bindValues) {
+    validateMetadataKey(column);
     switch (operator) {
         case "$eq":
             return jsonCompare(column, "=", value, bindValues);
@@ -51,20 +62,23 @@ function generateOperatorCondition(column, operator, value, bindValues) {
         case "$gte":
             return jsonCompare(column, ">=", value, bindValues);
         case "$in": {
-            if (!Array.isArray(value))
-                throw new Error("$in requires array");
+            if (!Array.isArray(value)) {
+                throwError(ErrorCode.FILTER_INVALID_VALUE, "$in requires array");
+            }
             const inClauses = value.map((v) => jsonCompare(column, "=", v, bindValues));
             return `(${inClauses.join(" OR ")})`;
         }
         case "$nin": {
-            if (!Array.isArray(value))
-                throw new Error("$nin requires array");
+            if (!Array.isArray(value)) {
+                throwError(ErrorCode.FILTER_INVALID_VALUE, "$nin requires array");
+            }
             const ninClauses = value.map((v) => jsonCompare(column, "!=", v, bindValues));
             return `(${ninClauses.join(" AND ")})`;
         }
         case "$between": {
-            if (!Array.isArray(value) || value.length !== 2)
-                throw new Error("$between requires [low, high]");
+            if (!Array.isArray(value) || value.length !== 2) {
+                throwError(ErrorCode.FILTER_INVALID_VALUE, "$between requires [low, high]");
+            }
             const [low, high] = value;
             bindValues.push(low, high);
             const posLow = bindValues.length - 1;
@@ -79,7 +93,7 @@ function generateOperatorCondition(column, operator, value, bindValues) {
                 return `NOT JSON_EXISTS(metadata, '$.${column}')`;
             }
         default:
-            throw new Error(`Unsupported operator: ${operator}`);
+            throwError(ErrorCode.FILTER_UNSUPPORTED_OPERATOR, operator);
     }
 }
 // Helper: build JSON_EXISTS clause for comparison
@@ -90,6 +104,17 @@ function jsonCompare(column, op, value, bindValues) {
     const operator = op === "=" ? "==" : op; // Oracle requires '==' for equality
     return `JSON_EXISTS(metadata, '$.${column}?(@ ${operator} $${alias})' PASSING :${pos} AS "${alias}")`;
 }
+export const VectorType = {
+    DENSE: "DENSE",
+    SPARSE: "SPARSE",
+};
+export const VectorElementFormat = {
+    INT8: "INT8",
+    FLOAT32: "FLOAT32",
+    FLOAT64: "FLOAT64",
+    BINARY: "BINARY",
+    FLEX: "*",
+};
 export const DistanceStrategy = {
     COSINE: "COSINE",
     DOT_PRODUCT: "DOT",
@@ -99,32 +124,33 @@ export const DistanceStrategy = {
     EUCLIDEAN_SQUARED: "EUCLIDEAN_SQUARED",
 };
 function handleError(error) {
-    // Type guard to check if the error is an object and has 'name' and 'message' properties
-    if (typeof error === "object" &&
+    // Preserve LangChainOracleError instances created by this package instead of
+    // wrapping them again as generic SYSTEM_ERROR failures.
+    if (isLangChainOracleError(error)) {
+        throw error;
+    }
+    // Preserve a useful message for both real Error instances and thrown
+    // object literals shaped like { message: string }.
+    const details = typeof error === "object" &&
         error !== null &&
-        "name" in error &&
-        "message" in error) {
-        const err = error; // Type assertion based on guarded checks
-        // Handle specific error types based on the name property
-        switch (err.name) {
-            case "RuntimeError":
-                throw new Error("Database operation failed due to a runtime error.");
-            case "ValidationError":
-                throw new Error("Operation failed due to a validation error.");
-            default:
-                throw new Error(`An unexpected error occurred during the operation. ${error}`);
-        }
-    }
-    throw new Error(`An unknown and unexpected error occurred. ${error}`);
+        "message" in error &&
+        typeof error.message === "string"
+        ? error.message
+        : String(error);
+    // Normalize all underlying anomalies into a unified telemetry payload.
+    throw createErrorFromCodeWithCause(ErrorCode.SYSTEM_ERROR, error, `An unexpected error occurred during the operation. ${details}`);
 }
 function isPool(client) {
     return "getConnection" in client;
 }
+function isClientProvider(client) {
+    return typeof client === "function";
+}
 function quoteIdentifier(identifier) {
     const name = identifier.trim();
     const validateRegex = /^(?:"[^"]+"|[^".]+)(?:\.(?:"[^"]+"|[^".]+))*$/;
     if (!validateRegex.test(name)) {
-        throw new Error(`Identifier name ${identifier} is not valid.`);
+        throwError(ErrorCode.VALIDATION_INVALID_IDENTIFIER, identifier);
     }
     // extracts parts of the identifier with quoted and unquoted.
     const matchRegex = /"([^"]+)"|([^".]+)/g;
@@ -135,10 +161,78 @@ function quoteIdentifier(identifier) {
     const quotedParts = groups.map((g) => `"${g}"`);
     return quotedParts.join(".");
 }
-export async function createTable(connection, tableName, embeddingDim) {
+const isFloat32Array = (value) => 
+// eslint-disable-next-line no-instanceof/no-instanceof
+value instanceof Float32Array;
+const isFloat64Array = (value) => 
+// eslint-disable-next-line no-instanceof/no-instanceof
+value instanceof Float64Array;
+const isInt8Array = (value) => 
+// eslint-disable-next-line no-instanceof/no-instanceof
+value instanceof Int8Array;
+const isUint8Array = (value) => 
+// eslint-disable-next-line no-instanceof/no-instanceof
+value instanceof Uint8Array;
+const isSparseVector = (value) => 
+// eslint-disable-next-line no-instanceof/no-instanceof
+value instanceof oracledb.SparseVector;
+function normalizeVectorTypeValue(value) {
+    const normalized = value?.toUpperCase();
+    if (normalized === VectorType.DENSE || normalized === VectorType.SPARSE) {
+        return normalized;
+    }
+    return VectorType.DENSE;
+}
+function normalizeVectorFormat(value, vectorType) {
+    if (!value) {
+        return VectorElementFormat.FLOAT32;
+    }
+    const normalizedValue = value === VectorElementFormat.FLEX
+        ? VectorElementFormat.FLEX
+        : value.toUpperCase();
+    const validFormats = Object.values(VectorElementFormat);
+    const format = validFormats.includes(normalizedValue)
+        ? normalizedValue
+        : VectorElementFormat.FLOAT32;
+    if (vectorType === VectorType.SPARSE && format === VectorElementFormat.BINARY) {
+        throwError(ErrorCode.VECTOR_INVALID_CONFIGURATION, "BINARY format is not supported for SPARSE vectors.");
+    }
+    return format;
+}
+function buildVectorColumnDefinition(embeddingDim, customization) {
+    if (embeddingDim === undefined || embeddingDim === null) {
+        throwError(ErrorCode.VECTOR_INVALID_CONFIGURATION, "Embedding dimension is required to create the vector column.");
+    }
+    if (!Number.isInteger(embeddingDim) || embeddingDim <= 0) {
+        throwError(ErrorCode.VECTOR_INVALID_CONFIGURATION, "Embedding dimension must be a positive integer.");
+    }
+    const vectorType = normalizeVectorTypeValue(customization?.vectorType);
+    if (vectorType === VectorType.SPARSE && customization?.format === undefined) {
+        throwError(ErrorCode.VECTOR_INVALID_CONFIGURATION, "Sparse vector type requires a vector format to be specified.");
+    }
+    const format = normalizeVectorFormat(customization?.format, vectorType);
+    if (format === VectorElementFormat.BINARY && embeddingDim % 8 !== 0) {
+        throwError(ErrorCode.VECTOR_INVALID_CONFIGURATION, "BINARY vector format requires dimensions to be a multiple of 8.");
+    }
+    const dimensionSegment = String(embeddingDim);
+    const formatSegment = format ?? VectorElementFormat.FLOAT32;
+    if (vectorType === VectorType.SPARSE) {
+        return `VECTOR(${dimensionSegment}, ${formatSegment}, SPARSE)`;
+    }
+    return `VECTOR(${dimensionSegment}, ${formatSegment})`;
+}
+function escapeCommentText(comment) {
+    return comment.replace(/'/g, "''");
+}
+function escapePlSqlLiteral(sql) {
+    return sql.replace(/'/g, "''");
+}
+export async function createTable(connection, tableName, embeddingDim, customization) {
+    const tableIdentifier = quoteIdentifier(tableName);
     const colsDict = {
         id: "RAW(16) DEFAULT SYS_GUID() PRIMARY KEY",
-        embedding: `vector(${embeddingDim}, FLOAT32)`,
+        external_id: `VARCHAR2(36) UNIQUE`,
+        embedding: buildVectorColumnDefinition(embeddingDim, customization),
         text: "CLOB",
         metadata: "JSON",
     };
@@ -146,11 +240,33 @@ export async function createTable(connection, tableName, embeddingDim) {
         const ddlBody = Object.entries(colsDict)
             .map(([colName, colType]) => `${colName} ${colType}`)
             .join(", ");
-        const ddl = `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(tableName)}
+        const createTableSql = `CREATE TABLE IF NOT EXISTS ${tableIdentifier}
                    (
                        ${ddlBody}
                    )`;
-        await connection.execute(ddl);
+        const statements = [
+            `EXECUTE IMMEDIATE '${escapePlSqlLiteral(createTableSql)}';`,
+        ];
+        const tableDescription = customization?.description?.trim();
+        if (tableDescription) {
+            const escapedDescription = escapeCommentText(tableDescription);
+            statements.push(`EXECUTE IMMEDIATE 'COMMENT ON TABLE ${tableIdentifier} IS ''${escapedDescription}''';`);
+        }
+        if (customization?.annotations) {
+            for (const [columnName, note] of Object.entries(customization.annotations)) {
+                const trimmedNote = note?.trim();
+                if (!trimmedNote)
+                    continue;
+                const columnKey = columnName.trim().toLowerCase();
+                if (!(columnKey in colsDict))
+                    continue;
+                const normalizedColumnIdentifier = `${tableIdentifier}.${quoteIdentifier(columnKey.toUpperCase())}`;
+                const escapedNote = escapeCommentText(trimmedNote);
+                statements.push(`EXECUTE IMMEDIATE 'COMMENT ON COLUMN ${normalizedColumnIdentifier} IS ''${escapedNote}''';`);
+            }
+        }
+        const block = `BEGIN\n  ${statements.join("\n  ")}\nEND;`;
+        await connection.execute(block);
     }
     catch (error) {
         handleError(error);
@@ -160,8 +276,60 @@ function _getIndexName(baseName) {
     const uniqueId = crypto.randomUUID().replace(/-/g, "");
     return `${baseName}_${uniqueId}`;
 }
+// Packs an array of 0/1 numbers into a big-endian Uint8Array for BINARY VECTOR storage.
+function packBinaryVector(bits) {
+    const byteLength = Math.ceil(bits.length / 8);
+    const buffer = new Uint8Array(byteLength);
+    for (let i = 0; i < bits.length; i += 1) {
+        const bit = bits[i] > 0 ? 1 : 0;
+        if (bit === 1) {
+            const byteIndex = Math.floor(i / 8);
+            const bitOffset = 7 - (i % 8);
+            buffer[byteIndex] |= 1 << bitOffset;
+        }
+    }
+    return buffer;
+}
+// Converts a dense numeric vector into the typed array that matches the configured element format.
+function convertDenseVectorForFormat(values, format) {
+    switch (format) {
+        case VectorElementFormat.FLOAT32:
+        case undefined:
+            return new Float32Array(values);
+        case VectorElementFormat.FLOAT64:
+            return new Float64Array(values);
+        case VectorElementFormat.INT8: {
+            const clamped = new Int8Array(values.length);
+            for (let i = 0; i < values.length; i += 1) {
+                const rounded = Math.round(values[i]);
+                if (rounded < -128 || rounded > 127) {
+                    throwError(ErrorCode.VECTOR_INVALID_VALUE, "INT8 vector values must be within [-128, 127].");
+                }
+                clamped[i] = rounded;
+            }
+            return clamped;
+        }
+        case VectorElementFormat.BINARY:
+            return packBinaryVector(values);
+        default:
+            return new Float64Array(values);
+    }
+}
+function unpackBinaryVector(bytesLike, dimension) {
+    const bytes = isUint8Array(bytesLike)
+        ? bytesLike
+        : Uint8Array.from(bytesLike);
+    const result = new Float32Array(dimension);
+    for (let i = 0; i < dimension; i += 1) {
+        const byteIndex = Math.floor(i / 8);
+        const bitOffset = 7 - (i % 8);
+        const byte = bytes[byteIndex] ?? 0;
+        result[i] = (byte >> bitOffset) & 1;
+    }
+    return result;
+}
 export async function createIndex(client, vectorStore, params) {
-    const idxType = params?.idxType || "HNSW";
+    const idxType = (params?.idxType ?? "HNSW").toUpperCase();
     if (idxType === "IVF") {
         await createIVFIndex(client, vectorStore, params);
     }
@@ -169,122 +337,48 @@ export async function createIndex(client, vectorStore, params) {
         await createHNSWIndex(client, vectorStore, params);
     }
 }
-async function createHNSWIndex(connection, oraclevs, params) {
+async function createHNSWIndex(connection, oraclevs, params = {}) {
     try {
-        const defaults = {
-            idxName: "HNSW",
-            idxType: "HNSW",
-            neighbors: 32,
-            efConstruction: 200,
-            accuracy: 90,
-            parallel: 8,
-        };
-        // if params then copy params to config
-        const config = params
-            ? { ...params }
-            : { ...defaults };
-        // Ensure compulsory parts are included
-        const compulsoryKeys = ["idxName", "parallel"];
-        for (const key of compulsoryKeys) {
-            if (!(key in config)) {
-                if (key === "idxName") {
-                    config[key] = _getIndexName(defaults[key]);
-                }
-                else {
-                    config[key] = defaults[key];
-                }
-            }
-        }
-        // Validate keys in config against defaults
-        for (const key of Object.keys(config)) {
-            if (!(key in defaults)) {
-                throw new Error(`Invalid parameter: ${key}`);
-            }
-        }
-        const { idxName } = config;
-        const baseSql = `CREATE VECTOR INDEX IF NOT EXISTS ${quoteIdentifier(idxName)}
-                              ON ${oraclevs.tableName}(embedding) 
-                              ORGANIZATION INMEMORY NEIGHBOR GRAPH`;
-        const accuracyPart = config.accuracy
-            ? ` WITH TARGET ACCURACY ${config.accuracy}`
-            : "";
-        const distancePart = ` DISTANCE ${oraclevs.distanceStrategy}`;
-        let parametersPart = "";
-        if ("neighbors" in config && "efConstruction" in config) {
-            parametersPart = ` parameters (type ${config.idxType}, 
-                                     neighbors ${config.neighbors}, 
-                                     efConstruction ${config.efConstruction})`;
-        }
-        else if ("neighbors" in config && !("efConstruction" in config)) {
-            config.efConstruction = defaults.efConstruction;
-            parametersPart = ` parameters (type ${config.idxType}, 
-                                     neighbors ${config.neighbors}, 
-                                     efConstruction ${config.efConstruction})`;
-        }
-        else if (!("neighbors" in config) && "efConstruction" in config) {
-            config.neighbors = defaults.neighbors;
-            parametersPart = ` parameters (type ${config.idxType}, 
-                                     neighbors ${config.neighbors}, 
-                                     efConstruction ${config.efConstruction})`;
-        }
-        const parallelPart = ` PARALLEL ${config.parallel}`;
-        const ddl = baseSql + accuracyPart + distancePart + parametersPart + parallelPart;
+        const { idxName = _getIndexName("HNSW"), idxType = "HNSW", neighbors = 32, efConstruction = 200, accuracy = 90, parallel = 8, ...extra } = params;
+        const invalidKeys = Object.keys(extra);
+        if (invalidKeys.length > 0) {
+            throwError(ErrorCode.VECTOR_INVALID_INDEX_PARAMETERS, invalidKeys);
+        }
+        const ddl = `
+      CREATE VECTOR INDEX IF NOT EXISTS ${quoteIdentifier(idxName)}
+      ON ${oraclevs.tableName}(embedding)
+      ORGANIZATION INMEMORY NEIGHBOR GRAPH
+      WITH TARGET ACCURACY ${accuracy}
+      DISTANCE ${oraclevs.distanceStrategy}
+      PARAMETERS (type ${idxType}, neighbors ${neighbors}, efConstruction ${efConstruction})
+      PARALLEL ${parallel}
+    `
+            .trim()
+            .replace(/\s+/g, " ");
         await connection.execute(ddl);
     }
     catch (error) {
         handleError(error);
     }
 }
-async function createIVFIndex(connection, oraclevs, params) {
+async function createIVFIndex(connection, oraclevs, params = {}) {
     try {
-        const defaults = {
-            idxName: "IVF",
-            idxType: "IVF",
-            neighborPart: 32,
-            accuracy: 90,
-            parallel: 8,
-        };
-        // Combine defaults with any provided params. Note: params could contain keys not explicitly declared in IndexConfig
-        const config = params
-            ? { ...params }
-            : { ...defaults };
-        // Ensure compulsory parts are included
-        const compulsoryKeys = ["idxName", "parallel"];
-        for (const key of compulsoryKeys) {
-            if (!(key in config)) {
-                if (key === "idxName") {
-                    config[key] = _getIndexName(defaults[key]);
-                }
-                else {
-                    config[key] = defaults[key];
-                }
-            }
-        }
-        // Validate keys in config against defaults
-        for (const key of Object.keys(config)) {
-            if (!(key in defaults)) {
-                throw new Error(`Invalid parameter: ${key}`);
-            }
-        }
-        // Base SQL statement
-        const { idxName } = config;
-        const baseSql = `CREATE VECTOR INDEX IF NOT EXISTS ${quoteIdentifier(idxName)}
-                              ON ${oraclevs.tableName}(embedding) 
-                              ORGANIZATION NEIGHBOR PARTITIONS`;
-        // Optional parts depending on parameters
-        const accuracyPart = config.accuracy
-            ? ` WITH TARGET ACCURACY ${config.accuracy}`
-            : "";
-        const distancePart = ` DISTANCE ${oraclevs.distanceStrategy}`;
-        let parametersPart = "";
-        if ("idxType" in config && "neighborPart" in config) {
-            parametersPart = ` PARAMETERS (type ${config.idxType}, 
-                         neighbor partitions ${config.neighborPart})`;
-        }
-        // Always included part for parallel - assuming parallel is compulsory and always included
-        const parallelPart = ` PARALLEL ${config.parallel}`;
-        // Combine all parts
-        const ddl = baseSql + accuracyPart + distancePart + parametersPart + parallelPart;
+        const { idxName = _getIndexName("IVF"), idxType = "IVF", neighborPart = 32, accuracy = 90, parallel = 8, ...extra } = params;
+        const invalidKeys = Object.keys(extra);
+        if (invalidKeys.length > 0) {
+            throwError(ErrorCode.VECTOR_INVALID_INDEX_PARAMETERS, invalidKeys);
+        }
+        const ddl = `
+      CREATE VECTOR INDEX IF NOT EXISTS ${quoteIdentifier(idxName)}
+      ON ${oraclevs.tableName}(embedding)
+      ORGANIZATION NEIGHBOR PARTITIONS
+      WITH TARGET ACCURACY ${accuracy}
+      DISTANCE ${oraclevs.distanceStrategy}
+      PARAMETERS (type ${idxType}, neighbor partitions ${neighborPart})
+      PARALLEL ${parallel}
+    `
+            .trim()
+            .replace(/\s+/g, " ");
         await connection.execute(ddl);
     }
     catch (error) {
@@ -312,6 +406,14 @@ export class OracleVS extends VectorStore {
             writable: true,
             value: void 0
         });
+        // Tracks connections borrowed from a pool so retConnection() can return them
+        // without closing direct connections owned by the caller.
+        Object.defineProperty(this, "poolConnections", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new WeakSet()
+        });
         Object.defineProperty(this, "embeddingDimension", {
             enumerable: true,
             configurable: true,
@@ -336,6 +438,30 @@ export class OracleVS extends VectorStore {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "description", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "annotations", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "vectorType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "vectorFormat", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "query", {
             enumerable: true,
             configurable: true,
@@ -349,11 +475,120 @@ export class OracleVS extends VectorStore {
                 dbConfig.distanceStrategy ?? this.distanceStrategy;
             this.query = dbConfig.query;
             this.filter = dbConfig.filter;
+            this.description = dbConfig.description;
+            this.annotations = dbConfig.annotations
+                ? { ...dbConfig.annotations }
+                : undefined;
+            this.vectorType = dbConfig.vectorType;
+            this.vectorFormat = dbConfig.format;
         }
         catch (error) {
             handleError(error);
         }
     }
+    getActiveVectorType() {
+        return this.vectorType ? normalizeVectorTypeValue(this.vectorType) : VectorType.DENSE;
+    }
+    ensureEmbeddingDimension() {
+        if (this.embeddingDimension === undefined || this.embeddingDimension === null) {
+            throwError(ErrorCode.STATE_INVALID, "Embedding dimension is not initialized for this vector store.");
+        }
+        return this.embeddingDimension;
+    }
+    prepareVectorForStorage(vector) {
+        if (this.embeddingDimension === undefined || this.embeddingDimension === null) {
+            this.embeddingDimension = vector.length;
+        }
+        const dimension = this.ensureEmbeddingDimension();
+        const vectorType = this.getActiveVectorType();
+        const format = this.vectorFormat
+            ? normalizeVectorFormat(this.vectorFormat, vectorType)
+            : VectorElementFormat.FLOAT32;
+        if (vectorType === VectorType.SPARSE) {
+            if (vector.length !== dimension) {
+                throwError(ErrorCode.VECTOR_INVALID_VALUE, "Sparse vectors must supply full-dimension arrays for conversion.");
+            }
+            let sparseInput = vector;
+            if (format === VectorElementFormat.INT8) {
+                const clamped = new Int8Array(vector.length);
+                for (let i = 0; i < vector.length; i += 1) {
+                    const rounded = Math.round(vector[i]);
+                    if (rounded < -128 || rounded > 127) {
+                        throwError(ErrorCode.VECTOR_INVALID_VALUE, "INT8 sparse vector values must be within [-128, 127].");
+                    }
+                    clamped[i] = rounded;
+                }
+                sparseInput = clamped;
+            }
+            else if (format === VectorElementFormat.FLOAT64) {
+                sparseInput = new Float64Array(vector);
+            }
+            else if (format === VectorElementFormat.FLOAT32) {
+                sparseInput = new Float32Array(vector);
+            }
+            return new oracledb.SparseVector(sparseInput);
+        }
+        if (vector.length !== dimension) {
+            throwError(ErrorCode.VECTOR_INVALID_VALUE, "Vector length does not match the embedding dimension.");
+        }
+        return convertDenseVectorForFormat(vector, format);
+    }
+    prepareQueryVector(vector) {
+        return this.prepareVectorForStorage(vector);
+    }
+    // Preserves the native driver representation, only expanding sparse vectors to dense form.
+    // Preserves the native driver representation, only expanding sparse vectors to dense form.
+    normalizeReturnedEmbedding(value) {
+        if (isSparseVector(value)) {
+            const dense = value.dense?.();
+            if (!dense) {
+                throwError(ErrorCode.VECTOR_UNSUPPORTED_REPRESENTATION, "Unable to expand sparse vector to dense representation.");
+            }
+            if (isFloat32Array(dense)) {
+                return dense;
+            }
+            if (isFloat64Array(dense)) {
+                return new Float32Array(dense);
+            }
+            if (isInt8Array(dense)) {
+                return Float32Array.from(dense);
+            }
+            if (Array.isArray(dense)) {
+                return Float32Array.from(dense);
+            }
+            return Float32Array.from(dense);
+        }
+        if (isFloat32Array(value) || isFloat64Array(value) || isInt8Array(value) || isUint8Array(value)) {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            return value;
+        }
+        throwError(ErrorCode.VECTOR_UNSUPPORTED_REPRESENTATION, "Received unsupported vector representation from the database.");
+    }
+    // Normalizes any supported vector representation into Float32Array so downstream math
+    // (MMR, distance calculations) can assume a consistent element type without forcing
+    // callers to give up the native shape returned by node-oracledb.
+    coerceEmbeddingToFloat32(value) {
+        if (isFloat32Array(value)) {
+            return value;
+        }
+        if (isFloat64Array(value)) {
+            return new Float32Array(value);
+        }
+        if (isInt8Array(value)) {
+            return Float32Array.from(value);
+        }
+        if (isUint8Array(value)) {
+            const byteLength = value.length;
+            const dimension = this.embeddingDimension ?? byteLength * 8;
+            return unpackBinaryVector(value, dimension);
+        }
+        if (Array.isArray(value)) {
+            return Float32Array.from(value);
+        }
+        return this.coerceEmbeddingToFloat32(this.normalizeReturnedEmbedding(value));
+    }
     async getEmbeddingDimension(query) {
         const embeddingVector = await this.embeddings.embedQuery(query);
         return embeddingVector.length;
@@ -363,7 +598,12 @@ export class OracleVS extends VectorStore {
         try {
             this.embeddingDimension = await this.getEmbeddingDimension(this.query);
             connection = await this.getConnection();
-            await createTable(connection, this.tableName, this.embeddingDimension);
+            await createTable(connection, this.tableName, this.embeddingDimension, {
+                description: this.description,
+                annotations: this.annotations,
+                vectorType: this.vectorType,
+                format: this.vectorFormat
+            });
         }
         catch (error) {
             handleError(error);
@@ -373,12 +613,20 @@ export class OracleVS extends VectorStore {
                 await this.retConnection(connection);
         }
     }
+    async resolveClient() {
+        return isClientProvider(this.client)
+            ? await this.client()
+            : this.client;
+    }
     async getConnection() {
         try {
-            if (isPool(this.client)) {
-                return await this.client.getConnection();
+            const client = await this.resolveClient();
+            if (isPool(client)) {
+                const connection = await client.getConnection();
+                this.poolConnections.add(connection);
+                return connection;
             }
-            return this.client;
+            return client;
         }
         catch (error) {
             handleError(error);
@@ -387,9 +635,10 @@ export class OracleVS extends VectorStore {
     // Close connection or return it to the pool
     async retConnection(connection) {
         try {
-            // If the client is a pool, close the connection (return it to the pool)
-            if (isPool(this.client)) {
+            // If this public connection came from any pool, close it to return it to the pool.
+            if (this.poolConnections.has(connection)) {
                 await connection.close();
+                this.poolConnections.delete(connection);
             }
         }
         catch (error) {
@@ -402,73 +651,79 @@ export class OracleVS extends VectorStore {
      * @param vectors The vectors to add.
      * @param documents The documents associated with the vectors.
      * @param options
+     * ** Add { mutateOnDuplicate?: boolean } to do upsert
      * @returns Promise that resolves when the vectors have been added.
      */
     async addVectors(vectors, documents, options) {
         if (vectors.length === 0) {
-            throw new Error("Vectors input null. Nothing to add...");
+            throwError(ErrorCode.VALIDATION_INVALID_INPUT, "Vectors input null. Nothing to add...");
         }
-        const ids = options?.ids;
+        const inputIds = options?.ids;
         let connection = null;
         try {
             // Ensure there are IDs for all documents
-            if (ids !== undefined && ids.length !== vectors.length) {
-                throw new Error("The number of ids must match the number of vectors provided.");
+            if (inputIds !== undefined && inputIds.length !== vectors.length) {
+                throwError(ErrorCode.VALIDATION_INVALID_INPUT, "The number of ids must match the number of vectors provided.");
             }
-            connection = await this.getConnection();
+            const finalIds = [];
             const binds = [];
             for (let index = 0; index < documents.length; index += 1) {
                 const doc = documents[index];
-                let processedId;
-                if (ids) {
-                    processedId = createHash("sha256")
-                        .update(ids[index])
-                        .digest("hex")
-                        .substring(0, 16)
-                        .toUpperCase();
-                }
-                else {
-                    const sourceId = doc.metadata.id ?? crypto.randomUUID();
-                    processedId = createHash("sha256")
-                        .update(sourceId)
-                        .digest("hex")
-                        .substring(0, 16)
-                        .toUpperCase();
-                }
-                const idBuffer = Buffer.from(processedId, "hex");
-                const bind = {
-                    id: idBuffer,
+                // Generate ID if not provided: Priority (Options -> Metadata -> Random)
+                const externalId = inputIds?.[index] ?? doc.metadata.id ?? crypto.randomUUID();
+                finalIds.push(externalId);
+                const preparedEmbedding = this.prepareVectorForStorage(vectors[index]);
+                const row = {
+                    ext_id: externalId,
                     text: doc.pageContent,
                     metadata: doc.metadata,
-                    embedding: new Float32Array(vectors[index]),
+                    embedding: preparedEmbedding,
                 };
-                binds.push(bind);
+                binds.push(row);
             }
-            const sql = `INSERT INTO ${this.tableName} (id, embedding, text, metadata )
-               VALUES (:id, :embedding, :text, :metadata)`;
-            const options = {
+            const isMutateOnDuplicate = options?.mutateOnDuplicate ?? false; // Default to false for better performance
+            const insertSql = `
+        INSERT INTO ${this.tableName} (external_id, embedding, text, metadata)
+        VALUES (:ext_id, :embedding, :text, :metadata)`;
+            const mergeSql = `
+      MERGE INTO ${this.tableName} t
+      USING (
+        SELECT :ext_id as external_id, :embedding as embedding,
+               :metadata as metadata, :text as text FROM DUAL
+      ) s
+      ON (t.external_id = s.external_id)
+      WHEN MATCHED THEN
+        UPDATE SET
+          t.embedding = s.embedding,
+          t.metadata = s.metadata,
+          t.text = s.text
+      WHEN NOT MATCHED THEN
+        INSERT (external_id, embedding, metadata, text)
+        VALUES (s.external_id, s.embedding, s.metadata, s.text)`;
+            const sql = isMutateOnDuplicate ? mergeSql : insertSql;
+            const executeOptions = {
                 bindDefs: {
-                    id: { type: oracledb.BUFFER, maxSize: 24 },
+                    ext_id: { type: oracledb.STRING, maxSize: 255 },
                     text: { type: oracledb.STRING, maxSize: 10000000 },
                     metadata: { type: oracledb.DB_TYPE_JSON },
                     embedding: { type: oracledb.DB_TYPE_VECTOR },
                 },
                 autoCommit: false,
             };
-            await connection.executeMany(sql, binds, options);
+            connection = await this.getConnection();
+            await connection.executeMany(sql, binds, executeOptions);
             // Commit once all inserts are queued up
             await connection.commit();
-            console.log("All documents have been inserted and committed.");
+            return finalIds;
         }
         catch (error) {
-            handleError(error);
+            return handleError(error);
         }
         finally {
             if (connection) {
                 await this.retConnection(connection);
             }
         }
-        return ids;
     }
     async addDocuments(documents, options) {
         const texts = documents.map(({ pageContent }) => pageContent);
@@ -485,16 +740,23 @@ export class OracleVS extends VectorStore {
         const docsScoresAndEmbeddings = [];
         let connection = null;
         try {
-            const convertedEmbedding = new Float32Array(query);
-            const bindValues = [convertedEmbedding];
+            const bindValues = [this.prepareQueryVector(query)];
+            const hasFilter = !!filter && Object.keys(filter).length > 0;
+            // Keep the vector index hint for unfiltered searches. When a JSON filter
+            // is present, forcing VECTOR_INDEX_TRANSFORM can change result semantics
+            // by doing approximate top-k before the filter is applied.
+            const selectClause = hasFilter
+                ? "SELECT"
+                : `SELECT /*+ VECTOR_INDEX_TRANSFORM(${this.tableName}) */`;
             let sqlQuery = `
-      SELECT id, 
+      ${selectClause}
+        external_id,
         text,
         metadata,
         vector_distance(embedding, :1, ${this.distanceStrategy}) as distance,
         embedding
       FROM ${this.tableName} `;
-            if (filter && Object.keys(filter).length > 0) {
+            if (hasFilter) {
                 sqlQuery += ` WHERE ${generateWhereClause(filter, bindValues)}`;
             }
             bindValues.push(k);
@@ -513,23 +775,19 @@ export class OracleVS extends VectorStore {
                     const text = row[1];
                     const metadata = row[2];
                     const distance = row[3];
-                    const embedding = row[4];
+                    const embedding = this.normalizeReturnedEmbedding(row[4]);
                     const document = new Document({
                         pageContent: text || "",
                         metadata: metadata || {},
-                        id: row[0].toString("hex"),
+                        id: row[0],
                     });
                     docsScoresAndEmbeddings.push([document, distance, embedding]);
                 }
             }
-            else {
-                // Throw an exception if no rows are found
-                throw new Error("No rows found.");
-            }
         }
         finally {
             if (connection) {
-                await connection.close();
+                await this.retConnection(connection);
             }
         }
         return docsScoresAndEmbeddings;
@@ -576,10 +834,8 @@ export class OracleVS extends VectorStore {
         // Split documents, scores, and embeddings
         const documents = docsScoresEmbeddings.map(([document]) => document);
         const scores = docsScoresEmbeddings.map(([, score]) => score);
-        const embeddings = docsScoresEmbeddings.map(([, , embedding]) => new Float32Array(embedding));
-        // Convert all embeddings to Float32Array for consistency
-        const consistentEmbeddings = embeddings.map((embedding) => Array.from(embedding));
-        const queryEmbedding = Array.from(embedding);
+        const consistentEmbeddings = docsScoresEmbeddings.map(([, , emb]) => Array.from(this.coerceEmbeddingToFloat32(emb)));
+        const queryEmbedding = Array.from(this.coerceEmbeddingToFloat32(embedding));
         // Ensure lambdaMult has a default value if not provided
         const lambdaMult = options.lambda ?? 0.5;
         const mmrSelectedIndices = maximalMarginalRelevance(queryEmbedding, consistentEmbeddings, lambdaMult, options.k);
@@ -612,21 +868,23 @@ export class OracleVS extends VectorStore {
             handleError(error);
         }
         finally {
-            if (connection)
-                await connection.close();
+            if (connection) {
+                await this.retConnection(connection);
+            }
         }
     }
-    static async fromDocuments(documents, embeddings, dbConfig) {
+    static async fromDocuments(documents, embeddings, dbConfig, options) {
         const { client } = dbConfig;
-        if (!client)
-            throw new Error("client parameter is required...");
+        if (!client) {
+            throwError(ErrorCode.VALIDATION_MISSING_REQUIRED_PARAMETER, "client");
+        }
         try {
             const vss = new OracleVS(embeddings, dbConfig);
             await vss.initialize();
             const texts = documents.map(({ pageContent }) => pageContent);
             const vectors = await embeddings.embedDocuments(texts);
             // Assuming a method exists to handle adding texts and metadata appropriately
-            await vss.addVectors(vectors, documents);
+            await vss.addVectors(vectors, documents, options);
             return vss;
         }
         catch (error) {
@@ -639,8 +897,8 @@ export class OracleVS extends VectorStore {
      * inside the pool are terminated.
      */
     async end() {
-        if (isPool(this.client)) {
-            await this.client?.close();
+        if (!isClientProvider(this.client) && isPool(this.client)) {
+            await this.client.close();
         }
     }
 }