API Reference

Client Initialization

client = Vectra::Client.new(
  provider: :pinecone,        # Required: :pinecone, :qdrant, :weaviate, :pgvector, :memory
  api_key: 'your-api-key',    # Required for cloud providers
  index: 'my-index',          # Optional default index
  namespace: 'tenant-1'       # Optional default namespace
)

In Rails, if you use the vectra:index generator and config/vectra.yml contains exactly one entry, a plain Vectra::Client.new will automatically pick that entry’s index (and namespace if present) as defaults.

Core Methods

upsert(vectors:)

Upsert vectors into the index. If a vector with the same ID exists, it will be updated.

Parameters:

Vector Hash:

{
  id: 'unique-id',                    # Required
  values: [0.1, 0.2, 0.3],           # Required
  metadata: { key: 'value' }         # Optional
}

Example:

client.upsert(
  vectors: [
    { id: '1', values: [0.1, 0.2], metadata: { category: 'news' } }
  ]
)

query(vector:, top_k:, include_metadata:)

Search for similar vectors.

Parameters:

Returns:

Vectra::QueryResult {
  matches: [
    { id: '1', score: 0.95, metadata: {...} },
    ...
  ],
  namespace: 'default'
}

Example:

results = client.query(vector: [0.1, 0.2], top_k: 5)

delete(ids:)

Delete vectors by IDs.

Parameters:

Example:

client.delete(ids: ['vec-1', 'vec-2'])

fetch(ids:)

Fetch vectors by IDs.

Parameters:

Returns:

{
  'vec-1' => { values: [...], metadata: {...} },
  ...
}

stats

Get index statistics.

Returns:

{
  'dimension' => 1536,
  'vector_count' => 1000,
  'index_fullness' => 0.8
}

hybrid_search(index:, vector:, text:, alpha:, top_k:)

Combine semantic (vector) and keyword (text) search.

Parameters:

Example:

results = client.hybrid_search(
  index: 'docs',
  vector: embedding,
  text: 'ruby programming',
  alpha: 0.7  # 70% semantic, 30% keyword
)

Provider Support: Qdrant ✅, Weaviate ✅, pgvector ✅, Pinecone ⚠️

text_search(index:, text:, top_k:)

Text-only search (keyword search without requiring embeddings).

Parameters:

Example:

results = client.text_search(
  index: 'products',
  text: 'iPhone 15 Pro',
  top_k: 10,
  filter: { category: 'electronics' }
)

Provider Support: Qdrant ✅ (BM25), Weaviate ✅ (BM25), pgvector ✅ (PostgreSQL full-text), Memory ✅, Pinecone ❌

healthy?

Quick health check - returns true if provider connection is healthy.

Returns: Boolean

Example:

if client.healthy?
  client.upsert(...)
end

You can also run faster checks with a temporary timeout:

fast_ok = client.with_timeout(0.5) { |c| c.healthy? }

ping

Ping provider and get connection health status with latency.

Returns:

{
  healthy: true,
  provider: :pinecone,
  latency_ms: 45.23
}

Example:

status = client.ping
puts "Latency: #{status[:latency_ms]}ms"

Vector.normalize(vector, type: :l2)

Normalize a vector array (non-mutating).

Parameters:

Returns: Array of normalized values

Example:

embedding = openai_response['data'][0]['embedding']
normalized = Vectra::Vector.normalize(embedding)
client.upsert(vectors: [{ id: 'doc-1', values: normalized }])

vector.normalize!(type: :l2)

Normalize vector in-place (mutates the vector).

Parameters:

Returns: Self (for method chaining)

Example:

vector = Vectra::Vector.new(id: 'doc-1', values: embedding)
vector.normalize!  # L2 normalization
client.upsert(vectors: [vector])

Error Handling

begin
  client.query(vector: [0.1, 0.2])
rescue Vectra::Error => e
  puts "Vectra error: #{e.message}"
rescue => e
  puts "Unexpected error: #{e.message}"
end

See Complete API Methods Reference for detailed method documentation.

Next Steps