Tensor & Vector Types

VectorTENSOR(N)SQL

Stable On by default · production-ready

What it is

TENSOR(N) is a native column type that stores a fixed-width float vector of N dimensions — not a generic blob. Because the engine knows the column is a vector of a known width, distance functions like cosine and L2 run directly against it, and you can build a vector index on it for fast k-nearest-neighbour (kNN) search.

The practical payoff: you can declare an embedding column, populate it at ingest, and rank rows by vector distance alongside an ordinary SQL WHERE clause in the same query — no separate vector store to keep in sync.

flowchart LR
  classDef a fill:#1f2640,stroke:#7c5cff,color:#e8eaf0
  classDef g fill:#1f2640,stroke:#4ade80,color:#4ade80
  classDef b fill:#1f2640,stroke:#00d4ff,color:#e8eaf0

  Row["Row: (id, text, embedding TENSOR(384))"]:::a
  Vec["embedding column<br/>384-dim vector"]:::g
  Dist["cosine / L2 distance per row"]:::a
  Idx["HNSW / IVFFLAT index<br/>(optional, for kNN)"]:::b

  Row --> Vec
  Vec --> Dist
  Vec -.-> Idx
  Idx -.->|shortlist| Dist
  Dist --> Out["ranked rows"]

Why it matters

An embedding is a first-class column here, not a blob you hand to another service. Because the engine knows the column is a fixed-width vector, it can compute distances directly and index it for fast search — and you can combine that search with an ordinary WHERE clause in one statement, over one copy of your data.

• Embeddings live with the rows — no separate vector store to populate and keep in sync.
• Filter and rank together — a metadata predicate and a similarity ranking are the same query.
• Typed, not opaque — the known width is what makes distance math and vector indexing possible.

How fast it is

Cosine / L2 distance runs directly against the typed column in the query engine — no export to an external service and back — and the same column can carry a vector index for sub-linear kNN search.

Declare a tensor column

Declare the column with its dimensionality. Pick the width to match the embedding model you intend to use (typically 384, 768, 1024, or 1536).

CREATE TABLE support_tickets (
  id        BIGINT,
  subject   TEXT,
  body      TEXT,
  region    TEXT,
  embedding TENSOR(384)        -- 384-dim vector
);

You can populate the column however you like — bulk-loaded from a precomputed file, or written from your application.

Rank by vector distance

TENSOR_COSINE and TENSOR_L2 return distances (smaller = closer), so order ascending. You can pre-filter by ordinary columns first and rank by distance second, all in one statement.

SELECT id, subject,
       TENSOR_COSINE(embedding, :query_vec) AS dist
FROM   support_tickets
WHERE  region = 'EU'
ORDER BY dist ASC
LIMIT 10;

For larger tables, build a vector index so the kNN search is sub-linear — see Vector Search.

Key concepts

Concept	What it means
TENSOR(N)	A column holding a fixed-width float vector of N dimensions.
Cosine / L2 distance	Built-in functions that score how close two vectors are (smaller = closer).
Vector index	An HNSW or IVFFLAT structure for sub-linear kNN at scale.

Notes & caveats

Pick the dimension once

Choose the embedding dimensionality once and keep it for the lifetime of the column — changing it later means regenerating every vector. Match it to the model you use (384, 768, 1024, or 1536 are common).

In-engine inference functions are still evolving

Some examples elsewhere call inference helpers (for example semantic_summary(text)) that run a local model inline. Those AI helper functions are Beta — the TENSOR(N) column type, distance functions, and indexes described on this page are the stable surface.

Vector Search →

Build HNSW / IVFFLAT indexes and run kNN queries.

Semantic NLP →

How text columns become AI-ready token streams.

Quickstart →

Tensor column, vector index, and kNN end-to-end.

Define Data →

The full typed-schema DDL surface.