pgvector-php

After setting up migrations, define your schema and model to support vector operations.

Migration:

$table->vector('embedding', 3);

Model:

use Pgvector\Laravel\Vector;
use Pgvector\Laravel\HasNeighbors;

class Item extends Model
{
    use HasNeighbors;

    protected $casts = ['embedding' => Vector::class];
}

Operations:

• Insert: Assign an array to the property: $item->embedding = [1, 2, 3];
• Nearest Neighbors (from record): $item->nearestNeighbors('embedding', Distance::L2)->take(5)->get();
• Nearest Neighbors (from vector): Item::query()->nearestNeighbors('embedding', [1, 2, 3], Distance::L2)->take(5)->get();
• Distance functions: Supports L2, InnerProduct, Cosine, L1, Hamming, and Jaccard via Pgvector\Laravel\Distance.

// Insert a vector
$item = new Item();
$item->embedding = [1, 2, 3];
$item->save();

// Get the nearest neighbors to a record
use Pgvector\Laravel\Distance;
$neighbors = $item->nearestNeighbors('embedding', Distance::L2)->take(5)->get();

// Get the nearest neighbors to a vector
$neighbors = Item::query()->nearestNeighbors('embedding', [1, 2, 3], Distance::L2)->take(5)->get();

// Get the distances
$neighbors->pluck('neighbor_distance');

Install the package via Composer and register the vector types and distance functions in your Doctrine configuration (config/packages/doctrine.yaml).

Configuration: Register vector, halfvec, bit, and sparsevec under dbal.types. Register distance functions like l2_distance, cosine_distance, etc., under orm.dql.numeric_functions.

Extension Setup: Generate a migration and add CREATE EXTENSION vector; to the up() method, then run the migration.

Entity Usage: Use Pgvector\Vector as the type for your column.

doctrine:
    dbal:
        types:
            vector: Pgvector\Doctrine\VectorType
            halfvec: Pgvector\Doctrine\HalfVectorType
            bit: Pgvector\Doctrine\BitType
            sparsevec: Pgvector\Doctrine\SparseVectorType
    orm:
        dql:
            numeric_functions:
                l2_distance: Pgvector\Doctrine\L2Distance
                max_inner_product: Pgvector\Doctrine\MaxInnerProduct
                cosine_distance: Pgvector\Doctrine\CosineDistance
                l1_distance: Pgvector\Doctrine\L1Distance
                hamming_distance: Pgvector\Doctrine\HammingDistance
                jaccard_distance: Pgvector\Doctrine\JaccardDistance

For direct use with PHP's pgsql extension, ensure the vector extension is enabled. You can use Pgvector\Vector objects directly with pg_query_params to insert or query vectors.

Example Operations:

• Insert: pg_query_params($db, 'INSERT INTO items (embedding) VALUES ($1)', [$embedding]);
• Search: pg_query_params($db, 'SELECT * FROM items ORDER BY embedding <-> $1 LIMIT 5', [$embedding]); (Note: <-> is the L2 distance operator).
• Indexing: Use CREATE INDEX ... USING hnsw or ivfflat with appropriate operator classes like vector_l2_ops, vector_ip_ops, or vector_cosine_ops.

use Pgvector\Vector;

// Enable extension
pg_query($db, 'CREATE EXTENSION IF NOT EXISTS vector');

// Create table
pg_query($db, 'CREATE TABLE items (embedding vector(3))');

// Insert
$embedding = new Vector([1, 2, 3]);
pg_query_params($db, 'INSERT INTO items (embedding) VALUES ($1)', [$embedding]);

// Search
$embedding = new Vector([1, 2, 3]);
$result = pg_query_params($db, 'SELECT * FROM items ORDER BY embedding <-> $1 LIMIT 5', [$embedding]);

// Indexing
pg_query($db, 'CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)');

The library provides classes to handle different pgvector types.

Vectors

Create a standard vector from an array.

$vec = new Vector([1, 2, 3]);
$arr = $vec->toArray();

Half Vectors

Create a half vector from an array.

$vec = new HalfVector([1, 2, 3]);
$arr = $vec->toArray();

Sparse Vectors

Create a sparse vector using either an indexed array or an associative array of non-zero elements. Indices start at 0.

// From indexed array
$vec = new SparseVector([1, 0, 2, 0, 3, 0]);

// From associative array (non-zero elements)
$elements = [0 => 1, 2 => 2, 4 => 3];
$vec = new SparseVector($elements, 6);

// Methods
$dim = $vec->dimensions();     // Number of dimensions
$indices = $vec->indices();     // Indices of non-zero elements
$values = $vec->values();       // Values of non-zero elements
$arr = $vec->toArray();        // Get array representation

// Vector
$vec = new Vector([1, 2, 3]);
$arr = $vec->toArray();

// HalfVector
$vec = new HalfVector([1, 2, 3]);
$arr = $vec->toArray();

// SparseVector
$vec = new SparseVector([1, 0, 2, 0, 3, 0]);
$elements = [0 => 1, 2 => 2, 4 => 3];
$vec = new SparseVector($elements, 6);
$dim = $vec->dimensions();
$indices = $vec->indices();
$values = $vec->values();
$arr = $vec->toArray();