feat(core): add VECTOR datatype support with Oracle vector integration

package.json

@@ -83,7 +83,7 @@
     "chai": "4.5.0",
     "concurrently": "9.2.1",
     "cross-env": "10.1.0",
-    "esbuild": "0.28.0",
+    "esbuild": "0.28.1",
     "eslint": "8.57.1",
     "eslint-plugin-jsdoc": "61.7.1",
     "eslint-plugin-mocha": "10.5.0",

packages/core/src/abstract-dialect/data-types.ts

@@ -2855,6 +2855,217 @@ export class TSVECTOR extends AbstractDataType<string> {
   }
 }
 
+export interface VectorOptions {
+  /**
+   * Optional vector dimension.
+   */
+  dimension?: number;
+  /**
+   * Optional dialect-specific element format (for example float32, int8, binary).
+   */
+  format?: string;
+}
+
+/**
+ * Numeric typed arrays accepted as vector values.
+ */
+export type NumericTypedArray =
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | Int16Array
+  | Uint16Array
+  | Int32Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array;
+
+// Dialects may accept plain arrays or any number-backed typed array. The generic validator
+// checks only the container shape; dialects are responsible for validating dimensions and values.
+export type VectorValue = number[] | NumericTypedArray;
+
+/**
+ * The VECTOR type stores ordered numeric vectors.
+ *
+ * Availability depends on the dialect (for example Oracle, Snowflake, pgvector, ...); check your dialect’s
+ * documentation to confirm supported element formats and dimensions.
+ *
+ * __Fallback policy:__
+ * If this type is not supported, an error will be raised.
+ *
+ * This shared base exists for dialect-specific VECTOR implementations. Dialects that can use Sequelize's
+ * generic {@link VectorOptions} may extend {@link VECTOR}; dialects with a different option shape may extend
+ * this class directly with their own options type.
+ *
+ * @example
+ * ```ts
+ * DataTypes.VECTOR
+ * DataTypes.VECTOR(1536)
+ * DataTypes.VECTOR(1536, 'float32')
+ * DataTypes.VECTOR({ dimension: 1024, format: 'int8' })
+ * DataTypes.VECTOR({ dimension: 2048 })
+ * ```
+ *
+ * @category DataTypes
+ */
+export abstract class AbstractVECTORBase<
+  TOptions extends object,
+> extends AbstractDataType<VectorValue> {
+  readonly options!: TOptions;
+
+  validate(value: unknown): asserts value is VectorValue {
+    if (this._getVectorIterable(value)) {
+      return;
+    }
+
+    ValidationErrorItem.throwDataTypeValidationError(
+      util.format('%O is not a valid vector', value),
+    );
+  }
+
+  protected _getVectorIterable(value: unknown): VectorValue | null {
+    if (Array.isArray(value) || isTypedArrayIterable(value)) {
+      return value;
+    }
+
+    return null;
+  }
+
+  protected _validateVectorElement(item: unknown): number {
+    if (typeof item !== 'number' || !Number.isFinite(item)) {
+      ValidationErrorItem.throwDataTypeValidationError(
+        util.format('%O is not a valid vector', item),
+      );
+    }
+
+    return item;
+  }
+
+  protected _validateDimension(dimension: number, max?: number): number {
+    if (!Number.isInteger(dimension) || dimension <= 0) {
+      throw new TypeError(`Invalid VECTOR dimension: ${dimension}`);
+    }
+
+    if (max !== undefined && dimension > max) {
+      throw new TypeError(`Invalid VECTOR dimension: ${dimension} (max ${max})`);
+    }
+
+    return dimension;
+  }
+
+  protected _checkOptionSupport(dialect: AbstractDialect) {
+    if (!dialect.supports.dataTypes.VECTOR) {
+      throwUnsupportedDataType(dialect, 'VECTOR');
+    }
+  }
+
+  protected abstract _getTypeName(): string;
+
+  protected _getSqlOptionParts(): string[] {
+    return [];
+  }
+
+  toSql(): string {
+    const parts = this._getSqlOptionParts();
+
+    return parts.length ? `${this._getTypeName()}(${parts.join(', ')})` : this._getTypeName();
+  }
+}
+
+/**
+ * Generic VECTOR implementation used by dialects whose options fit {@link VectorOptions}.
+ * Dialects with stricter option models can extend {@link AbstractVECTORBase} directly.
+ */
+export class VECTOR extends AbstractVECTORBase<VectorOptions> {
+  /** @hidden */
+  static readonly [DataTypeIdentifier]: string = 'VECTOR';
+
+  readonly options: VectorOptions;
+
+  constructor();
+  constructor(dimension: number, format?: string);
+  constructor(options: VectorOptions);
+  /** @hidden */
+  constructor(
+    ...args:
+      | []
+      | [dimension: number]
+      | [dimension: number, format: string]
+      | [options: VectorOptions]
+  );
+  constructor(dimensionOrOptions?: number | VectorOptions, format?: string) {
+    super();
+
+    if (typeof dimensionOrOptions === 'object' && dimensionOrOptions !== null) {
+      this.options = {
+        ...(dimensionOrOptions.dimension !== undefined
+          ? { dimension: this._validateDimension(dimensionOrOptions.dimension) }
+          : {}),
+        ...(dimensionOrOptions.format !== undefined
+          ? { format: this._validateFormat(dimensionOrOptions.format) }
+          : {}),
+      };
+
+      return;
+    }
+
+    this.options = {
+      ...(dimensionOrOptions !== undefined
+        ? { dimension: this._validateDimension(dimensionOrOptions) }
+        : {}),
+      ...(format !== undefined ? { format: this._validateFormat(format) } : {}),
+    };
+  }
+
+  protected _getTypeName(): string {
+    return 'VECTOR';
+  }
+
+  protected _validateFormat(format: string): string {
+    const normalized = format.trim().toLowerCase();
+
+    switch (normalized) {
+      case 'float':
+      case 'float32':
+      case 'float64':
+      case 'int':
+      case 'int8':
+      case 'int16':
+      case 'int32':
+      case 'binary':
+        return normalized;
+      default:
+        throw new TypeError(`Invalid VECTOR format: ${format}`);
+    }
+  }
+
+  protected override _getSqlOptionParts(): string[] {
+    return [
+      ...(this.options.dimension !== undefined ? [String(this.options.dimension)] : []),
+      ...(this.options.format !== undefined ? [this.options.format.toUpperCase()] : []),
+    ];
+  }
+}
+
+/**
+ * Returns true when the input is one of Sequelize's accepted numeric typed arrays.
+ *
+ * @param value
+ */
+function isTypedArrayIterable(value: unknown): value is NumericTypedArray {
+  return (
+    value instanceof Int8Array ||
+    value instanceof Uint8Array ||
+    value instanceof Uint8ClampedArray ||
+    value instanceof Int16Array ||
+    value instanceof Uint16Array ||
+    value instanceof Int32Array ||
+    value instanceof Uint32Array ||
+    value instanceof Float32Array ||
+    value instanceof Float64Array
+  );
+}
+
 function rejectBlobs(value: unknown) {
   // We have a DataType called BLOB. People might try to use the built-in Blob type with it, which they cannot.
   // To clarify why it doesn't work, we have a dedicated message for it.

packages/core/src/abstract-dialect/dialect.ts

@@ -200,6 +200,7 @@ export type DialectSupports = {
     GEOGRAPHY: boolean;
     HSTORE: boolean;
     TSVECTOR: boolean;
+    VECTOR: boolean;
     CIDR: boolean;
     INET: boolean;
     MACADDR: boolean;
@@ -461,6 +462,7 @@ export abstract class AbstractDialect<
       GEOGRAPHY: false,
       HSTORE: false,
       TSVECTOR: false,
+      VECTOR: false,
       DATETIME: {
         infinity: false,
       },

packages/core/src/abstract-dialect/query-interface.d.ts

@@ -76,7 +76,7 @@ export interface TableNameWithSchema {
 
 export type TableName = string | TableNameWithSchema;
 
-export type IndexType = AllowLowercase<'UNIQUE' | 'FULLTEXT' | 'SPATIAL'>;
+export type IndexType = AllowLowercase<'UNIQUE' | 'FULLTEXT' | 'SPATIAL' | 'VECTOR'>;
 export type IndexMethod = 'BTREE' | 'HASH' | 'GIST' | 'SPGIST' | 'GIN' | 'BRIN' | string;
 
 export interface IndexField {
@@ -116,7 +116,7 @@ export interface IndexOptions {
   parser?: string | null;
 
   /**
-   * Index type. Only used by mysql. One of `UNIQUE`, `FULLTEXT` and `SPATIAL`
+   * Index type. Used by MySQL (`UNIQUE`, `FULLTEXT`, `SPATIAL`) and Oracle (`VECTOR`).
    */
   type?: IndexType | undefined;
 

packages/core/src/data-types.ts

@@ -88,3 +88,5 @@ export const MACADDR8 = classToInvokable(DataTypes.MACADDR8);
 export const CITEXT = classToInvokable(DataTypes.CITEXT);
 /** This is a simple wrapper to make the DataType constructable without `new`. See the return type for all available options. */
 export const TSVECTOR = classToInvokable(DataTypes.TSVECTOR);
+/** This is a simple wrapper to make the DataType constructable without `new`. See the return type for all available options. */
+export const VECTOR = classToInvokable(DataTypes.VECTOR);

packages/core/src/sequelize.d.ts

@@ -1,6 +1,6 @@
 import type { Options as RetryAsPromisedOptions } from 'retry-as-promised';
 import type { DataTypes, Op, Options, QueryTypes } from '.';
-import type { DataType } from './abstract-dialect/data-types.js';
+import type { DataType, VectorValue } from './abstract-dialect/data-types.js';
 import type { AbstractDialect, ConnectionOptions } from './abstract-dialect/dialect.js';
 import type {
   ColumnsDescription,
@@ -611,6 +611,56 @@ export class Sequelize<
    */
   random(): Fn;
 
+  /**
+   * Build a dialect-specific cosine distance function.
+   * Dialects that advertise `DialectSupportMap.dataTypes.VECTOR` translate this generic helper
+   * into their native similarity operator (Oracle, Snowflake samples, pgvector, ...).
+   *
+   * @param column column name or identifier to compare against
+   * @param value reference vector as a plain numeric array or typed array
+   */
+  cosineDistance(column: string, value: VectorValue): Fn;
+
+  /**
+   * Build a dialect-specific inner product function.
+   * Dialects that advertise `DialectSupportMap.dataTypes.VECTOR` translate this generic helper
+   * into their native similarity operator (Oracle, Snowflake samples, pgvector, ...).
+   *
+   * @param column column name or identifier to compare against
+   * @param value reference vector as a plain numeric array or typed array
+   */
+  innerProduct(column: string, value: VectorValue): Fn;
+
+  /**
+   * Build a dialect-specific L1 distance function.
+   * Dialects that advertise `DialectSupportMap.dataTypes.VECTOR` translate this generic helper
+   * into their native similarity operator (Oracle, Snowflake samples, pgvector, ...).
+   *
+   * @param column column name or identifier to compare against
+   * @param value reference vector as a plain numeric array or typed array
+   */
+  l1Distance(column: string, value: VectorValue): Fn;
+
+  /**
+   * Build a dialect-specific L2 distance function.
+   * Dialects that advertise `DialectSupportMap.dataTypes.VECTOR` translate this generic helper
+   * into their native similarity operator (Oracle, Snowflake samples, pgvector, ...).
+   *
+   * @param column column name or identifier to compare against
+   * @param value reference vector as a plain numeric array or typed array
+   */
+  l2Distance(column: string, value: VectorValue): Fn;
+
+  /**
+   * Build a dialect-specific default vector distance function.
+   * Dialects that advertise `DialectSupportMap.dataTypes.VECTOR` translate this generic helper
+   * into their native similarity operator (Oracle, Snowflake samples, pgvector, ...).
+   *
+   * @param column column name or identifier to compare against
+   * @param value reference vector as a plain numeric array or typed array
+   */
+  vectorDistance(column: string, value: VectorValue): Fn;
+
   /**
    * Execute a query which would set an environment or user variable. The variables are set per connection,
    * so this function needs a transaction.

packages/core/src/sequelize.js

@@ -623,6 +623,38 @@ Use Sequelize#query if you wish to use replacements.`);
     return sql.random;
   }
 
+  cosineDistance(column, value) {
+    return this.#vectorSimilarityFn('COSINE_DISTANCE', column, value);
+  }
+
+  innerProduct(column, value) {
+    return this.#vectorSimilarityFn('INNER_PRODUCT', column, value);
+  }
+
+  l1Distance(column, value) {
+    return this.#vectorSimilarityFn('L1_DISTANCE', column, value);
+  }
+
+  l2Distance(column, value) {
+    return this.#vectorSimilarityFn('L2_DISTANCE', column, value);
+  }
+
+  vectorDistance(column, value) {
+    return this.#vectorSimilarityFn('VECTOR_DISTANCE', column, value);
+  }
+
+  #vectorSimilarityFn(fnName, column, value) {
+    // Dialects that advertise VECTOR support can translate these generic helper names in their
+    // query generator. Oracle is the primary implementation; other dialects may follow this pattern.
+    if (!this.dialect.supports?.dataTypes?.VECTOR) {
+      throw new Error(
+        `${fnName.toLowerCase()} for dialect "${this.dialect.name}" is not implemented`,
+      );
+    }
+
+    return fn(fnName, column, value);
+  }
+
   // Global exports
   static Fn = Fn;
   static Col = Col;