pgvector Data Types: vector, halfvec, bit, and sparsevec

pgvector provides four main representations: vector for single-precision dense values, halfvec for smaller half-precision dense values, bit for binary signatures, and sparsevec for mostly zero coordinates. Type choice affects dimensions, storage, supported metrics, operator classes, accuracy, and indexing. Choose through workload measurement, not novelty.

What will you be able to do?

Create and inspect each vector representation.
State current indexed dimensional limits.
Match a type to its metric operator class.
Use expression casts for alternate representations.
Design a quality comparison before changing precision.

How do the types compare?

As verified against pgvector v0.8.6 documentation, HNSW supports vector up to 2,000 dimensions, halfvec up to 4,000, bit up to 64,000 bits, and sparsevec up to 1,000 non-zero elements. IVFFlat supports vector up to 2,000, halfvec up to 4,000, and bit up to 64,000. Confirm limits for your installed version.

sql

CREATE TABLE type_lab (
  dense vector(3),
  compact halfvec(3),
  signature bit(8),
  sparse sparsevec(6)
);

INSERT INTO type_lab VALUES (
  '[0.1,0.2,0.3]',
  '[0.1,0.2,0.3]',
  B'10110010',
  '{1:0.5,4:0.9}/6'
);

Sparse syntax records non-zero index:value pairs and total dimensions. Inspect canonical output before building a loader.

When should you use each type?

Use vector as the default for ordinary dense embeddings within supported dimensions.
Evaluate halfvec when dimensions or footprint justify reduced precision.
Use bit for binary features or quantized first-stage retrieval with quality measurement.
Use sparsevec for genuinely sparse learned or engineered vectors; do not convert dense embeddings merely to use a different type.

You may store full vectors and index an expression cast:

sql

CREATE INDEX items_half_hnsw
ON items USING hnsw ((embedding::halfvec(1536)) halfvec_cosine_ops);

The query must use the same expression shape to use the index, then can rerank candidates by the original vector.

How do you verify it?

Use pg_column_size on representative values, then build a small exact-retrieval baseline. Compare top-k overlap and recall after half precision or binary quantization. Use EXPLAIN to confirm expression-index matching.

What breaks in production?

Dimension limits are assumed from a newer README than the installed extension.
A query casts differently from the expression index.
Quantized results are returned without full-precision reranking.
Sparse index coordinates are off by one.
Precision decisions use only average recall and hide critical slices.

AI pair-work prompt

Given dimensions, row count, metric, recall target, write rate, latency target, and memory budget [values], compare vector, halfvec, bit, and sparsevec. Eliminate incompatible options, propose an exact baseline and experiment, and generate matching index/query expressions. Cite the installed-version limits I provide.

Verification contract: Accept a new type only after measuring storage, build time, write throughput, latency, and per-slice retrieval quality against the original vectors.

Check your understanding

Which type is the ordinary dense default?
Why might an expression index be useful?
What must happen after binary first-stage retrieval when quality is sensitive?

Official references

pgvector Data Types: vector, halfvec, bit, and sparsevec

How do the types compare?

sql

CREATE TABLE type_lab (
  dense vector(3),
  compact halfvec(3),
  signature bit(8),
  sparse sparsevec(6)
);

INSERT INTO type_lab VALUES (
  '[0.1,0.2,0.3]',
  '[0.1,0.2,0.3]',
  B'10110010',
  '{1:0.5,4:0.9}/6'
);

Sparse syntax records non-zero index:value pairs and total dimensions. Inspect canonical output before building a loader.

When should you use each type?

Use vector as the default for ordinary dense embeddings within supported dimensions.

Evaluate halfvec when dimensions or footprint justify reduced precision.

Use bit for binary features or quantized first-stage retrieval with quality measurement.

Use sparsevec for genuinely sparse learned or engineered vectors; do not convert dense embeddings merely to use a different type.

You may store full vectors and index an expression cast:

sql

CREATE INDEX items_half_hnsw
ON items USING hnsw ((embedding::halfvec(1536)) halfvec_cosine_ops);

The query must use the same expression shape to use the index, then can rerank candidates by the original vector.

What breaks in production?

Dimension limits are assumed from a newer README than the installed extension.

A query casts differently from the expression index.

Quantized results are returned without full-precision reranking.

Sparse index coordinates are off by one.

Precision decisions use only average recall and hide critical slices.

AI pair-work prompt

Given dimensions, row count, metric, recall target, write rate, latency target, and memory budget [values], compare vector, halfvec, bit, and sparsevec. Eliminate incompatible options, propose an exact baseline and experiment, and generate matching index/query expressions. Cite the installed-version limits I provide.

Verification contract: Accept a new type only after measuring storage, build time, write throughput, latency, and per-slice retrieval quality against the original vectors.