pgvector-cpp

pgvector support for C++

Supports libpqxx

Installation

Add the headers to your project (supports C++20 and greater).

There is also support for CMake and FetchContent:

include(FetchContent)

FetchContent_Declare(pgvector GIT_REPOSITORY https://github.com/pgvector/pgvector-cpp.git GIT_TAG v0.3.0)
FetchContent_MakeAvailable(pgvector)

target_link_libraries(app PRIVATE pgvector::pgvector)

Getting Started

Follow the instructions for your database library:

• libpqxx

Or check out some examples:

• Embeddings with OpenAI
• Binary embeddings with Cohere
• Hybrid search with llama.cpp (Reciprocal Rank Fusion)
• Sparse search with Text Embeddings Inference
• Morgan fingerprints with RDKit
• Recommendations with Disco
• Horizontal scaling with Citus
• Bulk loading with COPY

libpqxx

Include the header

#include <pgvector/pqxx.hpp>

The latest version works libpqxx 8. For libpqxx 7, use version 0.2.4 and this readme.

Enable the extension

tx.exec("CREATE EXTENSION IF NOT EXISTS vector");

Create a table

tx.exec("CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3))");

Insert a vector

pgvector::Vector embedding{{1, 2, 3}};
tx.exec("INSERT INTO items (embedding) VALUES (\$1)", {embedding});

Get the nearest neighbors

pqxx::result r = tx.exec("SELECT * FROM items ORDER BY embedding <-> \$1 LIMIT 5", {embedding});

Retrieve a vector

pqxx::row row = tx.exec("SELECT embedding FROM items LIMIT 1").one_row();
auto embedding = row[0].as<pgvector::Vector>();

Use std::optional<pgvector::Vector> if the value could be NULL

Reference

Vectors

Create a vector from a std::vector

pgvector::Vector vec{std::vector<float>{1, 2, 3}};

Or a span

pgvector::Vector vec{std::span<const float>{{1, 2, 3}}};

Get a std::vector

const std::vector<float>& values = vec.values();

Half Vectors

Create a half vector from a std::vector

pgvector::HalfVector vec{std::vector<pgvector::Half>{1, 2, 3}};

Note: pgvector::Half is std::float16_t or _Float16 when available, or float otherwise

Or a span

pgvector::HalfVector vec{std::span<const pgvector::Half>{{1, 2, 3}}};

Get a std::vector

const std::vector<pgvector::Half>& values = vec.values();

Sparse Vectors

Create a sparse vector from a std::vector

pgvector::SparseVector vec{std::vector<float>{1, 0, 2, 0, 3, 0}};

Or a span

pgvector::SparseVector vec{std::span<const float>{{1, 0, 2, 0, 3, 0}}};

Or a map of non-zero elements

std::unordered_map<int, float> map{{0, 1}, {2, 2}, {4, 3}};
pgvector::SparseVector vec{map, 6};

Note: Indices start at 0

Get the number of dimensions

int dim = vec.dimensions();

Get the indices of non-zero elements

const std::vector<int>& indices = vec.indices();

Get the values of non-zero elements

const std::vector<float>& values = vec.values();

History

View the changelog

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

To get started with development:

git clone https://github.com/pgvector/pgvector-cpp.git
cd pgvector-cpp
createdb pgvector_cpp_test
cmake -S . -B build -DBUILD_TESTING=ON
cmake --build build
build/test

To run an example:

cd examples/loading
createdb pgvector_example
cmake -S . -B build
cmake --build build
build/example