Home

Awesome

💡 Lantern

build test codecov Run on Replit

Lantern is an open-source PostgreSQL database extension to store vector data, generate embeddings, and handle vector search operations.

It provides a new index type for vector columns called lantern_hnsw which speeds up ORDER BY ... LIMIT queries.

Lantern builds and uses usearch, a single-header state-of-the-art HNSW implementation.

🔧 Quick Install

If you don’t have PostgreSQL already, use Lantern with Docker to get started quickly:

docker run --pull=always --rm -p 5432:5432 -e "POSTGRES_USER=$USER" -e "POSTGRES_PASSWORD=postgres" -v ./lantern_data:/var/lib/postgresql/data lanterndata/lantern:latest-pg15

Then, you can connect to the database via postgresql://$USER:postgres@localhost/postgres.

To install Lantern using homebrew:

brew tap lanterndata/lantern
brew install lantern && lantern_install

You can also install Lantern on top of PostgreSQL from our precompiled binaries via a single make install.

Alternatively, you can use Lantern in one click using Replit.

🔧 Build Lantern from source code on top of your existing PostgreSQL

Prerequisites:

cmake version: >=3.3
gcc && g++ version: >=11 when building portable binaries, >= 12 when building on new hardware or with CPU-specific vectorization
PostgreSQL 11, 12, 13, 14, 15 or 16
Corresponding development package for PostgreSQL (postgresql-server-dev-$version)

To build Lantern on new hardware or with CPU-specific vectorization:

git clone --recursive https://github.com/lanterndata/lantern.git
cd lantern
mkdir build
cd build
cmake -DMARCH_NATIVE=ON ..
make install

To build portable Lantern binaries:

git clone --recursive https://github.com/lanterndata/lantern.git
cd lantern
mkdir build
cd build
cmake -DMARCH_NATIVE=OFF ..
make install

📖 How to use Lantern

Lantern retains the standard PostgreSQL interface, so it is compatible with all of your favorite tools in the PostgreSQL ecosystem.

First, enable Lantern in SQL (e.g. via psql shell)

CREATE EXTENSION lantern;

Note: After running the above, lantern extension is only available on the current postgres DATABASE (single postgres instance may have multiple such DATABASES). When connecting to a different DATABASE, make sure to run the above command for the new one as well. For example:

CREATE DATABASE newdb;
\c newdb
CREATE EXTENSION lantern;

Create a table with a vector column and add your data

CREATE TABLE small_world (id integer, vector real[3]);
INSERT INTO small_world (id, vector) VALUES (0, '{0,0,0}'), (1, '{0,0,1}');

Create an hnsw index on the table via lantern_hnsw:

CREATE INDEX ON small_world USING lantern_hnsw (vector);

Customize lantern_hnsw index parameters depending on your vector data, such as the distance function (e.g., dist_l2sq_ops), index construction parameters, and index search parameters.

CREATE INDEX ON small_world USING lantern_hnsw (vector dist_l2sq_ops)
WITH (M=2, ef_construction=10, ef=4, dim=3);

Start querying data

SET enable_seqscan = false;
SELECT id, l2sq_dist(vector, ARRAY[0,0,0]) AS dist
FROM small_world ORDER BY vector <-> ARRAY[0,0,0] LIMIT 1;

A note on operators and operator classes

Lantern supports several distance functions in the index and it has 2 modes for operators:

  1. lantern.pgvector_compat=TRUE (default) In this mode there are 3 operators available <-> (l2sq), <=> (cosine), <+> (hamming).

    Note that in this mode, you need to use right operator in order to trigger an index scan.

  2. lantern.pgvector_compat=FALSE In this mode you only need to specify the distance function used for a column at index creation time. Lantern will automatically infer the distance function to use for search so you always use <?> operator in search queries.

    Note that in this mode, the operator <?> is intended exclusively for use with index lookups. If you expect to not use the index in a query, use the distance function directly (e.g. l2sq_dist(v1, v2))

To switch between modes set lantern.pgvector_compat variable to TRUE or FALSE.

There are four defined operator classes that can be employed during index creation:

Index Construction Parameters

The M, ef, and ef_construction parameters control the performance of the HNSW algorithm for your use case.

Miscellaneous

⭐️ Features

🏎️ Performance

Important takeaways:

<p> <img alt="Lantern throughput" src="https://storage.googleapis.com/lantern-blog/1/throughput.png" width="400" style="float: left;" /> <img alt="Lantern latency" src="https://storage.googleapis.com/lantern-blog/1/latency.png" width="400" style="float: left;" /> <img alt="Lantern index creation" src="https://storage.googleapis.com/lantern-blog/1/create.png" width="400" style="float: left;" /> </p>

🗺️ Roadmap

📚 Resources