Nova vector search engine

Novad capacity reference

Novam capacity reference

halfvec (half-precision vectors)

halfvec uses half-precision floating-point numbers, with memory usage approximately half that of vector. It is suitable for memory-sensitive high-dimensional vector scenarios.

-- Create a table with halfvec type
CREATE TABLE chunks_half (
    id SERIAL PRIMARY KEY,
    feature halfvec(1536)
) DISTRIBUTED BY (id);

-- Create an index
CREATE INDEX idx_half ON chunks_half
USING ann(feature)
WITH (
    dim = 1536,
    algorithm = novamr,
    distancemeasure = cosine
);

sq8vector (SQ8 compressed vectors)

sq8vector stores vectors in INT8 format, further compressing memory usage. Use with Novam or Novad indexes.

-- Create a table with sq8vector type
CREATE TABLE chunks_sq8 (
    id SERIAL PRIMARY KEY,
    feature sq8vector(1536)
) DISTRIBUTED BY (id);

-- Create a Novam memory-based SQ8 index
CREATE INDEX idx_sq8 ON chunks_sq8
USING ann(feature)
WITH (
    dim = 1536,
    algorithm = novam,
    distancemeasure = cosine
);

-- You can also create a Novad disk-based SQ8 index
-- sq8vector + novadflat automatically switches to novadsq8
CREATE INDEX idx_sq8_disk ON chunks_sq8
USING ann(feature)
WITH (
    dim = 1536,
    algorithm = novadflat,
    distancemeasure = cosine
);

Sparse vectors (svector)

Nova uses svector to store sparse vectors. Each vector contains two sets of data that correspond one-to-one:

• indices: the dimension numbers of non-zero elements.

• values: the values corresponding to these dimensions.

For example, an 8-dimensional sparse vector with values 1.2, 1.1, and 0.7 at indices 2, 3, and 6 respectively, and 0 elsewhere:

SELECT '{"indices":[2,3,6],"values":[1.2,1.1,0.7]}'::svector(8);

Sample output:

                       svector
------------------------------------------------------
 {"indices":[2,3,6],"values":[1.2,1.1,0.7]}
(1 row)

This vector has 8 dimensions. The values at dimensions 2, 3, and 6 are 1.2, 1.1, and 0.7 respectively. All other dimensions are 0.

svector(N) uses 0-based indexing. The valid range is [0, N-1]. For example, the valid indices for svector(8) are 0 to 7.

The indices and values arrays must have the same number of elements and correspond by position:

Create a sparse vector sample table and an index:

DROP TABLE IF EXISTS sparse_docs;

CREATE TABLE sparse_docs (
    id         BIGINT PRIMARY KEY,
    title      TEXT NOT NULL,
    category   TEXT NOT NULL,
    publish_at TIMESTAMP NOT NULL,
    embedding  svector(8) NOT NULL
) DISTRIBUTED BY (id);

INSERT INTO sparse_docs(id, title, category, publish_at, embedding) VALUES
    (1, 'PostgreSQL full-text search', 'search',    '2024-01-01',
        '{"indices":[1,3,7],"values":[0.8,1.5,0.4]}'),
    (2, 'Nova sparse vector search',   'search',    '2024-02-01',
        '{"indices":[2,3,6],"values":[1.2,1.1,0.7]}'),
    (3, 'Vector database practice',     'vector',    '2024-03-01',
        '{"indices":[1,4,7],"values":[0.9,1.3,1.0]}'),
    (4, 'Data analysis fundamentals',   'analytics', '2024-04-01',
        '{"indices":[5,7],"values":[1.4,0.6]}'),
    (5, 'Hybrid search solution',       'search',    '2024-05-01',
        '{"indices":[2,4,6,7],"values":[0.6,1.1,1.2,0.9]}');

-- Use inner product to measure relevance and create a sparse vector index
CREATE INDEX sparse_docs_embedding_idx
ON sparse_docs
USING ann (embedding)
WITH (
    algorithm = 'novam',
    distancemeasure = 'ip'
);

ANALYZE sparse_docs;

In actual use, the total dimensions of the embedding must match the sparse vector model. Document vectors and query vectors in the same column must use compatible models and the same dimensions.

Create a sparse vector index

When using inner product to measure relevance, create the following index:

-- The index was already created in the table creation step above.
-- This is shown here for reference:
-- CREATE INDEX sparse_docs_embedding_idx
-- ON sparse_docs
-- USING ann (embedding)
-- WITH (
--     algorithm = 'novam',
--     distancemeasure = 'ip'
-- );

Parameter description:

• USING ann (embedding) creates a vector index for the embedding column.

• algorithm = 'novam' uses the Nova memory-based index.

• distancemeasure = 'ip' uses inner product to measure relevance.

Use an 8-dimensional query vector to return the 3 most relevant records:

SELECT
    id,
    title,
    category,
    -(embedding <#>
        '{"indices":[2,3,6],"values":[1,1,0.5]}'::svector(8)
     ) AS score
FROM sparse_docs
ORDER BY embedding <#>
    '{"indices":[2,3,6],"values":[1,1,0.5]}'::svector(8)
LIMIT 3;

Sample output:

In this SQL statement:

• <#> computes the negative inner product. A smaller negative inner product indicates a larger inner product and higher relevance between the two vectors.

• ORDER BY embedding <#> query vector returns data sorted by relevance in descending order and allows the optimizer to use the Nova index.

• LIMIT 3 specifies that only the 3 most relevant records are returned.

Binary vectors (bit)

The bit type is used to store binary vectors, suitable for scenarios such as hash fingerprints. It supports Hamming distance and Jaccard distance.

-- Create a table with bit type
CREATE TABLE chunks_bit (
    id SERIAL PRIMARY KEY,
    feature bit(256)
) DISTRIBUTED BY (id);

-- Create an index using Hamming distance
CREATE INDEX idx_bit ON chunks_bit
USING ann(feature)
WITH (
    dim = 256,
    algorithm = novam,
    distancemeasure = hamming
);

Novam query parameters

Novad query parameters

Common query parameters

Configuration examples

Use index reloptions to pin search parameters for a specific index:

-- Pin Novam index parameters
ALTER INDEX idx_feature_novam_l2 SET (
    nova_ef_search = 200,
    nova_max_scan_points = 5000
);

-- Pin Novad index parameters
ALTER INDEX idx_feature_novad_cosine SET (
    nova_nprobe = 20
);

When a reloption is -1 or has been RESET, queries use the current session GUC instead:

ALTER INDEX idx_feature_novam_l2
RESET (nova_ef_search, nova_max_scan_points);

SET fastann.hnsw_ef_search = 200;
SET fastann.hnsw_max_scan_points = 5000;

Start tuning

The following example tunes topK = 10 and 100 simultaneously with a target recall of 0.99. The test query table docs_eval_queries is provided to guarantee recall on this query set. Each topK and target_recall combination saves a separate configuration. After the task completes, the index automatically applies the largest combination, i.e., topK = 100, target_recall = 0.99.

SELECT *
FROM fastann.nova_autotune(
    index_relation => 'public.docs_embedding_novam_idx'::regclass, -- Required; no default; specifies the index to tune
    topk           => ARRAY[10, 100],                                        -- Required; no default; specifies topK values to tune
    target_recall  => 0.99,                                        -- Optional; default: 0.99; specifies target recall
    n_samples      => 100,                                              -- Optional; default: 300; specifies number of sample queries
    n_trials       => 100,                                               -- Optional; default: 500; specifies number of candidate trials
    query_table    => 'public.docs_eval_queries'::regclass,           -- Optional; default: NULL; specifies the test query table
    query_column   => 'embedding'                                   -- Optional; default: NULL; specifies the query vector column
) AS result(handle);

When no test query table is available, omit query_table and query_column. The system generates queries from the internal index data and fits the parameters:

SELECT *
FROM fastann.nova_autotune(
    index_relation => 'public.docs_embedding_novam_idx'::regclass, -- Required; no default; specifies the index to tune
    topk           => ARRAY[10, 100],                                        -- Required; no default; specifies topK values to tune
    target_recall  => 0.99,                                        -- Optional; default: 0.99; specifies target recall
    n_samples      => 100,                                              -- Optional; default: 300; specifies number of sample queries
    n_trials       => 100                                                -- Optional; default: 500; specifies number of candidate trials
) AS result(handle);

Sample output:

  handle
-----------
 123456790
(1 row)

Check tuning progress

Use the handle returned by nova_autotune to check the task progress:

SELECT
    stage,
    query_count,
    work_done,
    work_total,
    updated_at
FROM fastann.nova_autotune_progress(
    handle => 123456789
);

Sample output:

   stage    | query_count | work_done | work_total |       updated_at
------------+-------------+-----------+------------+------------------------
 evaluating |         300 |       126 |        500 | 2026-07-28 14:20:42+08
(1 row)

work_done / work_total indicates the task progress percentage. When the progress function returns 0 rows, the task has ended or the handle is no longer active. This does not mean the tuning failed. You can use nova_autotune_status to view the selected configurations and read back the index reloption.

Manual parameter configuration

Autotune saves the parameters for each topK and target_recall combination. View all existing tuning results for the index:

SELECT
    topk, target_recall, achieved, autotune_recall,
    ef_search, max_scan_points, nprobe, rescore_amp, applied
FROM fastann.nova_autotune_status(
    index_relation => 'public.docs_embedding_novam_idx'::regclass
)
ORDER BY topk, target_recall;

Sample output:

 topk | target_recall | achieved | autotune_recall | ef_search | max_scan_points | nprobe | rescore_amp | applied
------+---------------+----------+-----------------+-----------+-----------------+--------+-------------+---------
   10 |          0.99 | t        |           0.992 |        80 |            3000 |      0 |         1.2 | f
  100 |          0.99 | t        |           0.991 |       240 |           12000 |      0 |         1.5 | t
(2 rows)

Each topK and target_recall combination corresponds to a set of parameters. Both must be specified together when switching:

-- Use the configuration that achieves 99% recall at topK=10
ALTER INDEX public.docs_embedding_novam_idx SET (
    nova_autotune_topk = 10,
    nova_autotune_recall = 0.99
);

-- Switch to the configuration that achieves 99% recall at topK=100
ALTER INDEX public.docs_embedding_novam_idx SET (
    nova_autotune_topk = 100,
    nova_autotune_recall = 0.99
);

Enable through SET

The following query returns only topK results with a cosine similarity greater than 0.75:

SET fastann_score_filter_switch = on;
SET fastann_score_filter_min = 0.75;
RESET fastann_score_filter_max;

SELECT id,
       chunk,
       1 - (
           feature <=> ARRAY[0.1, 0.2, ...]::real[]
       ) AS score
FROM chunks
ORDER BY score
LIMIT 10;

Sample output (actual data may vary):

SET
SET
RESET
 id |       chunk        | score
----+--------------------+-------
 12 | Nova vector search | 0.921
  7 | PostgreSQL search  | 0.884
(2 rows)

To limit the score range, set both the upper and lower bounds:

SET fastann_score_filter_switch = on;
SET fastann_score_filter_min = 0.75;
SET fastann_score_filter_max = 0.95;

Enable through SQL Hint

The Hint must be placed at the very beginning of a standalone SQL statement, without any preceding SET, RESET, or other statements. It is designed to affect only the current statement. Before using it, verify in the same connection whether the current version affects subsequent queries.

/*+ SET(fastann_score_filter_switch on)
    SET(fastann_score_filter_min 0.75)
    SET(fastann_score_filter_max 0.95) */
SELECT id,
       chunk,
       1 - (
           feature <=> ARRAY[0.1, 0.2, ...]::real[]
       ) AS score
FROM chunks
ORDER BY score
LIMIT 10;

Sample output (actual data may vary):

 id |       chunk        | score
----+--------------------+-------
 12 | Nova vector search | 0.921
  7 | PostgreSQL search  | 0.884
(2 rows)

Enable compatibility mode

In the current version, submit a ticket to enable the pgvector compatibility mode before use. After the feature is enabled, regular users can create and use pgvector-compatible indexes.

To make <-> return Euclidean distance consistent with pgvector, set fastann.pgvector_compatibility = on in the session. This setting is not required when you only use it for TopK sorting without reading distance values or filtering by distance.

Index syntax and Nova backend

You can use the pgvector index syntax directly. The distance metric is determined by the operator class:

CREATE INDEX docs_embedding_hnsw_idx
ON docs USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

CREATE INDEX docs_embedding_ivfflat_idx
ON docs USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 1024);

In this section, hnsw and ivfflat are pgvector-compatible syntax names. Nova supports their index creation and query interfaces, while the actual indexes are implemented by the Nova backend and are not equivalent to native HNSW or IVFFlat indexes. The pgvector-compatible access method and operator class jointly determine the Nova backend and distance metric; specifying algorithm or distancemeasure does not change the backend selection.

Supported operator classes

Parameter mapping

Compatible IVFFlat queries adjust the search scope through nova_nprobe; if not set, it inherits fastann.nova_nprobe with a default value of 5. ivfflat.probes and fastann.ivfflat_probes do not take effect for this compatible index.

Limitations

• L1 operator classes are not supported on Nova indexes. Creating a vector_l1_ops or halfvec_l1_ops index causes an error.

• The cosine operator class for sparsevec is not yet supported for Nova indexes. Cosine search requires normalizing both index and query vectors and then performing an inner product search. The Nova build pipeline does not yet support normalization for sparse vectors, so index creation is explicitly rejected. Use L2 or inner product instead.

• ivfflat only supports L2, inner product, and cosine distance for vector and halfvec.

• pgvector syntax is mapped to the Nova backend. The index structure, quantization method, storage footprint, recall, and performance characteristics differ from native pgvector.

• svector supports up to 1 billion dimensions with up to 4000 non-zero values. indices and values must contain the same number of elements. values must be finite numbers and cannot contain NaN, Infinity, or -Infinity.