Skip to content

getting-started.md

Latest commit

 

History

History
96 lines (71 loc) · 2.54 KB

getting-started.md

File metadata and controls

96 lines (71 loc) · 2.54 KB
Raw

Getting Started

Prerequisites

  • Rust stable toolchain
  • cargo-pgrx 0.17: cargo install cargo-pgrx@0.17
  • Native PostgreSQL build dependencies, or PostgreSQL 18 development headers if using an existing server (PG17 is supported as a compatibility build)

Setup

Initialize a local PostgreSQL 18 instance for development:

cargo pgrx init --pg18 download

Build, install, start PostgreSQL, and open psql:

cargo pgrx run --release pg18

For platform prerequisites, existing-PostgreSQL installs, operator CLI setup, and validation commands, see Build From Source.

First Query

Connect to PostgreSQL and create a small table with the canonical ecvector row type:

CREATE EXTENSION ecaz;

CREATE TABLE items (
    id bigint generated always as identity primary key,
    embedding ecvector(4)
);

INSERT INTO items (embedding)
VALUES
    (encode_to_ecvector(ARRAY[1.0, 0.0, 0.0, 0.0]::float4[], 4, 42)),
    (encode_to_ecvector(ARRAY[0.0, 1.0, 0.0, 0.0]::float4[], 4, 42)),
    (encode_to_ecvector(ARRAY[-1.0, 0.0, 0.0, 0.0]::float4[], 4, 42));

CREATE INDEX items_hnsw_idx
ON items USING ec_hnsw (embedding ecvector_ip_ops)
WITH (m = 8, ef_construction = 64);

SELECT id
FROM items
ORDER BY embedding <#> ARRAY[1.0, 0.0, 0.0, 0.0]::float4[]
LIMIT 2;

Expected output:

 id
----
  1
  2
(2 rows)

<#> is negative inner-product distance, so ORDER BY ... ASC returns the highest inner-product matches first.

Other Index Types

Ecaz also includes opt-in IVF and DiskANN access methods.

CREATE INDEX items_ivf_idx
ON items USING ec_ivf (embedding ecvector_ip_ops)
WITH (nlists = 2, nprobe = 1, storage_format = 'turboquant');

The sample rows above are unit-normalized, so they can also be used with DiskANN. DiskANN currently validates this contract because its v0 graph distance wrapper preserves <#> ordering only for unit-normalized vectors:

CREATE INDEX items_diskann_idx
ON items USING ec_diskann (embedding ecvector_diskann_ip_ops)
WITH (graph_degree = 32, build_list_size = 100, list_size = 100);

Next Steps