pgvector-cpp

pgvector support for C++

Supports libpqxx

Installation

Add the headers to your project (supports C++17 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.2.2)
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>

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

auto embedding = pgvector::Vector({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

auto 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<float>

auto vec = pgvector::Vector({1, 2, 3});

Convert to a std::vector<float>

auto float_vec = static_cast<std::vector<float>>(vec);

Half Vectors

Create a half vector from a std::vector<float>

auto vec = pgvector::HalfVector({1, 2, 3});

Convert to a std::vector<float>

auto float_vec = static_cast<std::vector<float>>(vec);

Sparse Vectors

Create a sparse vector from a std::vector<float>

auto vec = pgvector::SparseVector({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}};
auto vec = pgvector::SparseVector(map, 6);

Get the number of dimensions

int dim = vec.dimensions();

Get the indices of non-zero elements

auto indices = vec.indices();

Get the values of non-zero elements

auto 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