MLE JavaScript Support for the VECTOR Data Type

Oracle Multilingual Engine (MLE) supports conversions between JavaScript TypedArrays and SQL vectors with formats INT8, FLOAT32, and FLOAT64. Data exchanges between JavaScript and the VECTOR data type are supported by the MLE JavaScript SQL driver, MLE call specifications, and MLE JavaScript bindings.

The VECTOR data type can appear as an IN, OUT, and IN OUT bind argument, as well as a return type. The SIGNATURE clause of an MLE call specification supports the following JavaScript types:

Float32Array
Float64Array
Int8Array
SparseVector

Table A-5 Mapping from VECTOR Data Type to JavaScript Types

SQL Type	JavaScript Type
`VECTOR(*, float32)`	`Float32Array` (TypedArray)
`VECTOR(*, float64)`	`Float64Array` (TypedArray)
`VECTOR(*, int8)`	`Int8Array` (TypedArray)
`VECTOR(*)`	`Float64Array`^Foot 1 (TypedArray)
`VECTOR(*, float32, SPARSE)`	`SparseVector`^Foot 2

^Footnote 1When no vector format or storage format is specified, a dense Float64Array is used by default

^Footnote 2When the storage format is not specified, the dense format is used by default. The format of the sparse vector depends on the format of the input, which can be FLOAT32, FLOAT64, or INT8.

Table A-6 Mapping from JavaScript Types to VECTOR Data Type

JavaScript Type	SQL Type
`Float32Array`	`VECTOR(*, float32)`
`Float64Array`	`VECTOR(*, float64)`
`Int8Array`	`VECTOR(*, int8)`
`Array`	`VECTOR(*, float64)`
`SparseVector`	`VECTOR(*, [float32 \| float64 \| int8], SPARSE)`^Foot 3

^Footnote 3The format of the sparse vector in SQL is dependent on the format specified in the function signature.

Unless specified, the storage format of a vector defaults to DENSE, which means that all dimensions of the vector are physically stored, including zero-values. SPARSE vectors are vectors in which most dimensions are zero and only non-zero values are stored physically. In cases when you have vectors that are almost entirely comprised of zero-value dimensions, using sparse vectors can improve performance and reduce storage requirements.

With in-database JavaScript, sparse (and dense) vectors can be inserted into the database and fetched from MLE, used as IN, OUT, and INOUT function arguments, and can be specified in the signature of an MLE call specification. In JavaScript, sparse vectors are represented using SparseVector objects, which have the following properties:

numDimensions: The number of dimensions of the vector, including zero and non-zero values.
indices: An array that contains the indices (zero-based) of the dimensions that have non-zero values.
values: An array containing the non-zero values of the dimensions at the specified indices.

You can convert a SparseVector object to a dense vector using the dense() method. When dense() is used on a SparseVector, a TypedArray of 8-bit integers, 32-bit floating-point numbers, or 64-bit floating-point numbers is returned, depending on the storage format of the sparse vector column's non-zero values in Oracle AI Database.

A SparseVector object can be defined in the following ways:

As a string in the form of a JSON array that includes the number of dimensions, an array of indices representing the location of non-zero values, and an array of values:
```
oracledb.SparseVector('[10, [1, 3, 5], [1.5, 3.5, 7.7]]')
```
As an object that contains an array of values, an array of indices representing the location of non-zero values, and the number of dimensions:
```
oracledb.SparseVector({values: [1.5, 3.5, 7.7], indices: [1, 3, 5], numDimensions: 10})
```
As a dense array, which can be a JavaScript array or TypedArray:
```
oracledb.SparseVector([0, 1.5, 0, 3.5, 0, 7.7, 0, 0, 0, 0])
```

See Also:

Oracle AI Database AI Vector Search User's Guide for more information about the VECTOR data type and Oracle AI Vector Search capabilities
Oracle AI Database AI Vector Search User's Guide for more information about SPARSE vectors.

Example A-1 Use VECTOR Data Type with MLE

This example demonstrates support of the VECTOR data type used in arguments and as return type in MLE call specifications.

SET SERVEROUTPUT ON;
CREATE OR REPLACE MLE MODULE vec_mod
LANGUAGE JAVASCRIPT AS

/**
 * Add two vectors
 * @param v1 the first vector
 * @param v2 the second vector
 * @returns the resulting vector after adding v1 and v2
 */
export function addVectors(v1, v2){
  return v1.map((element, index) => element + v2[index]);
}

/**
 * Subtract two vectors
 * @param v1 the first vector
 * @param v2 the second vector
 * @returns the resulting vector after subtracting v2 from v1
 */
export function subtractVectors(v1, v2){
  return v1.map((element, index) => element - v2[index]);
}
/

CREATE OR REPLACE PACKAGE mle_vec_pkg AS

  FUNCTION addVectors(
    input_vector1 IN VECTOR,
    input_vector2 IN VECTOR
  )
  RETURN VECTOR
    AS MLE MODULE vec_mod
    SIGNATURE 'addVectors';

  FUNCTION subtractVectors(
    input_vector1 IN VECTOR,
    input_vector2 IN VECTOR
  )
  RETURN VECTOR
    AS MLE MODULE vec_mod
    SIGNATURE 'subtractVectors';

END mle_vec_pkg;
/

SELECT mle_vec_pkg.addVectors(
  VECTOR('[1, 2]'),
  VECTOR('[3, 4]')
) AS result;

Result:

RESULT
---------------------------------------------
[4.0E+000,6.0E+000]

SELECT mle_vec_pkg.subtractVectors(
  VECTOR('[3, 4]'),
  VECTOR('[1, 2]')
) AS result;

Result:

RESULT
---------------------------------------------
[2.0E+000,2.0E+000]

Example A-2 Use Sparse Vectors with MLE

CREATE OR REPLACE MLE MODULE my_sparse_mod
LANGUAGE JAVASCRIPT AS

    /**
     * print out the dimensions of a sparse vector input by first 
     * calling the sparseVector constructor over the input argument 
     * and then by changing the JavaScript object to a JSON string
     * @param {vector} input - a vector with dimension values to be printed
     */

    export function printSparseVec(input) {
        const sparseVec = oracledb.SparseVector(input);
        const sparseVal = JSON.stringify(sparseVec);
        console.log(sparseVal);
    }
/

CREATE OR REPLACE PROCEDURE 
print_sparse_vec(input IN VECTOR)
AS MLE MODULE MY_SPARSE_MOD
SIGNATURE 'printSparseVec(SparseVector)';
/

BEGIN
    print_sparse_vec(vector('[5, [2, 3], [41.0, 51.0]]', 5, FLOAT64, SPARSE));
END;
/

Result:

{"numDimensions":5,"indices":{"0":2,"1":3},"values":{"0":41,"1":51}}

You can also specify the type in the signature as, for example, Float64Array. If no type is included in the signature, the default is SparseVector.

CREATE OR REPLACE PROCEDURE
print_sparse_vec_64(input IN VECTOR)
AS MLE MODULE MY_SPARSE_MOD
SIGNATURE 'printSparseVec(Float64Array)';
/

BEGIN
    print_sparse_vec_64(vector('[5,[2,3],[41.0,51.0]]', 5, FLOAT64, SPARSE));
END;
/

Result:

0,0,41,51,0

Parent topic: MLE Type Conversions