pg_lion_vector

Overview

pgvector >= 0.7.

Version

Build

You can build the RPM / DEB packages for pg_lion using pig build:

pig build pkg pg_lion         # build RPM / DEB packages

Install

You can install pg_lion directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install pg_lion;          # Install for current active PG version

pig ext install -y pg_lion -v 18  # PG 18
pig ext install -y pg_lion -v 17  # PG 17
pig ext install -y pg_lion -v 16  # PG 16

dnf install -y pg_lion_18       # PG 18
dnf install -y pg_lion_17       # PG 17
dnf install -y pg_lion_16       # PG 16

apt install -y postgresql-18-pg-lion   # PG 18
apt install -y postgresql-17-pg-lion   # PG 17
apt install -y postgresql-16-pg-lion   # PG 16

Create Extension:

CREATE EXTENSION pg_lion_vector CASCADE;  -- requires: pg_lion, vector

Usage

Sources:

• README
• Reference
• Control file
• Extension SQL

pg_lion_vector 0.3.0 adds the lionvec nearest-neighbor access method for pgvector vector and halfvec values. It uses the parent pg_lion library and requires pgvector 0.7 or later.

Core Workflow

Create the parent and vector extensions first. A separate lion index can filter candidates before distance ranking.

CREATE EXTENSION vector;
CREATE EXTENSION pg_lion;
CREATE EXTENSION pg_lion_vector;
CREATE TABLE lion_items (id integer, category integer, embedding vector(3));
INSERT INTO lion_items VALUES (1, 3, '[1,0,0]'), (2, 3, '[0,1,0]'), (3, 4, '[0,0,1]');
CREATE INDEX lion_embedding ON lion_items USING lionvec (embedding vector_cosine_ops);
CREATE INDEX lion_category ON lion_items USING lion (category);
ALTER FUNCTION cosine_distance(vector, vector) COST 100;
VACUUM ANALYZE lion_items;
SELECT id FROM lion_items
WHERE category = 3
ORDER BY embedding <=> '[1,0,0]'::vector
LIMIT 10;

Upstream recommends COST 100 for the distance function used by the chosen operator class so the planner can compare scan and sort costs. This setting is not preserved by pg_dump and may be reset by an update of vector.

Operator Classes and Tuning

partitions controls the index build’s clustering; maintenance_work_mem must hold an adequate sample. pg_lion.vector_margin and pg_lion.vector_patience control approximate search. Small candidate sets under a supported lion filter can use exact scoring. pg_lion.vector_postfilter controls predicates the lion indexes cannot answer; review the reference before changing it.

Operational Boundaries

Requires PostgreSQL 16 or later and superuser installation. Only one vector or halfvec column, up to 8128 dimensions, is supported; this is generally approximate search. A filter does not turn every query into exact nearest-neighbor search. Heavy churn may require occasional REINDEX. Parent custom-WAL indexes retain their preload requirement. Keep parent and companion files at the same version.