Vectra
A unified Ruby client for vector databases. Write once, switch providers seamlessly.
📖 Documentation: vectra-docs.netlify.app
Supported Providers
| Provider | Type | Status |
|---|---|---|
| Pinecone | Managed Cloud | ✅ Supported |
| Qdrant | Open Source | ✅ Supported |
| Weaviate | Open Source | ✅ Supported |
| pgvector | PostgreSQL | ✅ Supported |
Installation
gem 'vectra-client'bundle installQuick Start
require 'vectra'
# Initialize client (works with any provider)
client = Vectra::Client.new(
provider: :pinecone,
api_key: ENV['PINECONE_API_KEY'],
environment: 'us-west-4'
)
# Upsert vectors
client.upsert(
vectors: [
{ id: 'doc-1', values: [0.1, 0.2, 0.3], metadata: { title: 'Hello' } },
{ id: 'doc-2', values: [0.4, 0.5, 0.6], metadata: { title: 'World' } }
]
)
# Search
results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
results.each { |match| puts "#{match.id}: #{match.score}" }
# Delete
client.delete(ids: ['doc-1', 'doc-2'])Provider Examples
# Pinecone
client = Vectra.pinecone(api_key: ENV['PINECONE_API_KEY'], environment: 'us-west-4')
# Qdrant (local)
client = Vectra.qdrant(host: 'http://localhost:6333')
# Qdrant (cloud)
client = Vectra.qdrant(host: 'https://your-cluster.qdrant.io', api_key: ENV['QDRANT_API_KEY'])
# Weaviate
client = Vectra.weaviate(host: 'http://localhost:8080', api_key: ENV['WEAVIATE_API_KEY'])
# pgvector (PostgreSQL)
client = Vectra.pgvector(connection_url: 'postgres://user:pass@localhost/mydb')Features
- Provider Agnostic - Switch providers with one line change
- Production Ready - Ruby 3.2+, 95%+ test coverage
- Resilient - Retry logic with exponential backoff
- Observable - Datadog & New Relic instrumentation
-
Rails Ready - ActiveRecord integration with
has_vectorDSL
Rails Integration
class Document < ApplicationRecord
include Vectra::ActiveRecord
has_vector :embedding,
provider: :qdrant,
index: 'documents',
dimension: 1536
end
# Auto-indexes on save
doc = Document.create!(title: 'Hello', embedding: [0.1, 0.2, ...])
# Search
Document.vector_search(embedding: query_vector, limit: 10)Development
git clone https://github.com/stokry/vectra.git
cd vectra
bundle install
bundle exec rspec
bundle exec rubocopContributing
Bug reports and pull requests welcome at github.com/stokry/vectra.
License
MIT License - see LICENSE file.