Skip to main content

Native vector search

AliSQL adds a VECTOR(N) type, Euclidean and cosine distance functions, and an HNSW approximate nearest-neighbor index to the MySQL/InnoDB path. The current guide supports vectors with up to 16,383 dimensions.

AliSQL Vector Index architecture showing the InnoDB data model, HNSW index construction, scalar filtering, approximate nearest-neighbor search, Top K output, core features, and APIs

Storage and query path​

The HNSW graph is persisted as a structured InnoDB auxiliary table. Each graph node is represented by a row containing its layer, base-table reference, quantized vector, and neighbors. Metadata for the base table and auxiliary table participates in MySQL 8.0 data-dictionary and DDL transactions.

At query time, AliSQL can select the vector index by cost, or a query can use an index hint such as FORCE INDEX. Graph nodes are loaded through two cache lifetimes:

  • MHNSW Share is shared by read-only transactions and avoids repeatedly loading the same visible nodes.
  • MHNSW Trx belongs to a read-write transaction, isolates modified nodes, and updates the shared-cache view at commit.

This is why vector search is part of the InnoDB transaction path, not a detached sidecar index.

Enable and create an index​

Vector features are disabled by default. Indexed vector operations require READ COMMITTED:

SET GLOBAL vidx_disabled = OFF;
SET SESSION transaction_isolation = 'READ-COMMITTED';

CREATE TABLE documents (
    id BIGINT PRIMARY KEY,
    title VARCHAR(200),
    embedding VECTOR(3),
    VECTOR INDEX embedding_hnsw (embedding) M=6 DISTANCE=COSINE
) ENGINE=InnoDB;

INSERT INTO documents VALUES
    (1, 'Storage engine notes', VEC_FROMTEXT('[0.1,0.2,0.3]')),
    (2, 'Recovery design',      VEC_FROMTEXT('[0.2,0.1,0.4]'));

Query nearest neighbors using the index distance:

SELECT id,
       title,
       VEC_DISTANCE(
           embedding,
           VEC_FROMTEXT('[0.1,0.2,0.3]')
       ) AS distance
FROM documents
ORDER BY distance
LIMIT 10;

VEC_DISTANCE_EUCLIDEAN and VEC_DISTANCE_COSINE are also available when the distance function should be explicit.

Parameters that shape the graph​

Variable or index optionScopeDefaultDocumented range or values
vidx_disabledGlobalONON, OFF
vidx_default_distanceGlobal, sessionEUCLIDEANEUCLIDEAN, COSINE
vidx_hnsw_default_m / MGlobal, session / index63 to 200
vidx_hnsw_ef_searchGlobal, session201 to 10000
vidx_hnsw_cache_sizeGlobal16 MiB1 MiB to ULLONG_MAX bytes

M changes graph connectivity, ef_search changes the search width, and the cache limit changes how much graph state can remain in memory. Treat all three as workload parameters: measure recall, latency, construction cost, and memory together.

Transaction and DDL boundaries​

  • Vector indexes are supported only on InnoDB tables.
  • Vector-index operations require READ COMMITTED.
  • Read-read and read-write concurrency are supported; write-write concurrency on the same vector table is not currently supported.
  • Creating, modifying, or deleting a vector index cannot use ALGORITHM=INPLACE.
  • Vector indexes cannot be INVISIBLE.
  • A query vector must match the indexed column dimension.
  • Nullable vectors are allowed, but NULL rows are omitted from HNSW and scalar distance returns NULL.
  • HNSW construction uses randomized and heuristic steps, so replicas are not guaranteed to have byte-identical graph topology.

Engineering notes​

The official implementation material describes three performance mechanisms without changing the transactional source of truth:

  1. graph nodes are cached rather than loaded repeatedly from the auxiliary table;
  2. reusable distance work is precomputed during node loading;
  3. supported CPU paths use SIMD, including AVX-512, for batched distance calculations.

Do not copy performance percentages from an article into a capacity plan. Validate the exact release, CPU instruction path, data distribution, recall target, cache size, and update rate used by your application.

Authoritative references​