vectra-client 1.0.7 → 1.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 316a75b282cab4d293dfdb3ab9f7b2220a58078008a6887e7e47e7caf6172211
-  data.tar.gz: d4a9c10c5e6862194e7fb028c254b19d63b0d2fb6fa5ef5f45b59b6a9da1a317
+  metadata.gz: '05778206f66d4e2ead830f5b7c5885f6336b46d36af696f3df5a56eb26163c5f'
+  data.tar.gz: 1ae5814cd10df006ecf5568f34e457400b072ecc8a06dbf85a4e4f5b94120fb9
 SHA512:
-  metadata.gz: ca06a9e2a961f6130aaa06cf42caafd900ef9fb38dc902e42c3bccb649962abe3d3cd64a50af84605df273682013f0ae90476c5096f4a3efee1ac67d3d1dc672
-  data.tar.gz: e1fb369da70479f0b3505be4c15d1b6ee7089d0f6c14bb6b58d1ae02c15b9cbb92bfb448e88697726a769d01d5ac7b9569f6085c04ee420e39e55b2ee754013c
+  metadata.gz: d25889a4626c9caa9edf7ccc285c849799de87cf38a8a7a6f56a49edb46da592b28bc0232960e2612fd0d9199e990c21bd5fe6b88f15351d8ff38c73bd7afc84
+  data.tar.gz: d4ef355089814ed4caf8c61e216b9554f23035df12be72a65c778b3230bd2a32f16ecf4c50de3bc33e40dc323f1aee83d7a891ad962bec105585c8bc6b30902b

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [v1.0.8](https://github.com/stokry/vectra/tree/v1.0.8) (2026-01-14)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.0.7...v1.0.8)
+
 ## [v1.0.7](https://github.com/stokry/vectra/tree/v1.0.7) (2026-01-14)
 
 [Full Changelog](https://github.com/stokry/vectra/compare/v1.0.6...v1.0.7)

data/docs/api/cheatsheet.md

@@ -34,6 +34,21 @@ client = Vectra.pgvector(connection_url: ENV['DATABASE_URL'])
 client = Vectra.memory # In-memory (testing only)
 ```
 
+You can also set a **default index and namespace**:
+
+```ruby
+client = Vectra::Client.new(
+  provider: :qdrant,
+  host: 'http://localhost:6333',
+  index: 'products',
+  namespace: 'tenant-1'
+)
+
+# Now index and namespace can be omitted
+client.upsert(vectors: [...])
+client.query(vector: query_embedding, top_k: 10)
+```
+
 ### Upsert
 
 ```ruby
@@ -225,6 +240,22 @@ vector.normalize! # Mutates values
 client.upsert(index: 'documents', vectors: [vector])
 ```
 
+### Embedding Cache Helper
+
+```ruby
+cache = Vectra::Cache.new(ttl: 600, max_size: 1000)
+
+embedding = Vectra::Embeddings.fetch(
+  cache: cache,
+  model_name: "Product",
+  id: product.id,
+  input: product.description,
+  field: :description
+) do
+  EmbeddingService.generate(product.description)
+end
+```
+
 ---
 
 ## Batch Operations
@@ -318,6 +349,18 @@ results.each do |doc|
 end
 ```
 
+### Reindex All Records
+
+```ruby
+# Reindex all documents that already have embeddings
+processed = Document.reindex_vectors(
+  scope: Document.where.not(embedding: nil),
+  batch_size: 500
+)
+
+puts "Reindexed #{processed} documents"
+```
+
 ---
 
 ## Error Handling

data/docs/api/methods.md

@@ -43,7 +43,7 @@ client = Vectra::Client.new(
 Upsert vectors into an index. If a vector with the same ID exists, it will be updated.
 
 **Parameters:**
-- `index` (String) - Index/collection name
+- `index` (String) - Index/collection name (uses client's default index when omitted)
 - `vectors` (Array<Hash, Vector>) - Array of vector hashes or Vector objects
 - `namespace` (String, optional) - Namespace
 
@@ -77,7 +77,7 @@ result = client.upsert(
 Search for similar vectors using cosine similarity.
 
 **Parameters:**
-- `index` (String) - Index/collection name
+- `index` (String) - Index/collection name (uses client's default index when omitted)
 - `vector` (Array<Float>) - Query vector
 - `top_k` (Integer) - Number of results (default: 10)
 - `namespace` (String, optional) - Namespace
@@ -152,7 +152,7 @@ results = client.hybrid_search(
 Fetch vectors by their IDs.
 
 **Parameters:**
-- `index` (String) - Index/collection name
+- `index` (String) - Index/collection name (uses client's default index when omitted)
 - `ids` (Array<String>) - Array of vector IDs
 - `namespace` (String, optional) - Namespace
 
@@ -176,7 +176,7 @@ vectors['doc-1'].metadata # => { 'title' => 'Hello' }
 Update a vector's metadata or values.
 
 **Parameters:**
-- `index` (String) - Index/collection name
+- `index` (String) - Index/collection name (uses client's default index when omitted)
 - `id` (String) - Vector ID
 - `metadata` (Hash, optional) - New metadata (merged with existing)
 - `values` (Array<Float>, optional) - New vector values
@@ -202,7 +202,7 @@ client.update(
 Delete vectors.
 
 **Parameters:**
-- `index` (String) - Index/collection name
+- `index` (String) - Index/collection name (uses client's default index when omitted)
 - `ids` (Array<String>, optional) - Vector IDs to delete
 - `namespace` (String, optional) - Namespace
 - `filter` (Hash, optional) - Delete by metadata filter
@@ -231,7 +231,7 @@ client.delete(index: 'documents', delete_all: true)
 Get index statistics.
 
 **Parameters:**
-- `index` (String) - Index/collection name
+- `index` (String) - Index/collection name (uses client's default index when omitted)
 - `namespace` (String, optional) - Namespace
 
 **Returns:** `Hash` with statistics:
@@ -571,6 +571,30 @@ end
 
 ---
 
+### `Model.reindex_vectors(scope: all, batch_size: 1000, on_progress: nil)`
+
+Reindex all records for a model into the configured vector index.
+
+**Parameters:**
+- `scope` (ActiveRecord::Relation) - Records to reindex (default: `Model.all`)
+- `batch_size` (Integer) - Number of records per batch (default: 1000)
+- `on_progress` (Proc, optional) - Progress callback, receives a hash with `:processed` and `:total`
+
+**Returns:** `Integer` - Number of records processed
+
+**Example:**
+```ruby
+# Reindex all products with embeddings
+processed = Product.reindex_vectors(
+  scope: Product.where.not(embedding: nil),
+  batch_size: 500
+)
+
+puts "Reindexed #{processed} products"
+```
+
+---
+
 ## Error Handling
 
 Vectra defines specific error types:

data/lib/vectra/active_record.rb

@@ -2,8 +2,9 @@
 
 require "active_support/concern"
 
-# Ensure Client and Providers are loaded (for Rails autoloading compatibility)
+# Ensure Client and supporting classes are loaded (for Rails autoloading compatibility)
 require_relative "client" unless defined?(Vectra::Client)
+require_relative "batch" unless defined?(Vectra::Batch)
 
 module Vectra
   # ActiveRecord integration for vector embeddings
@@ -26,6 +27,7 @@ module Vectra
   #   # Search similar documents
   #   results = Document.vector_search([0.1, 0.2, ...], limit: 10)
   #
+  # rubocop:disable Metrics/ModuleLength
   module ActiveRecord
     extend ActiveSupport::Concern
 
@@ -86,6 +88,54 @@ module Vectra
         end
       end
 
+      # Reindex all vectors for this model using current configuration.
+      #
+      # @param scope [ActiveRecord::Relation] records to reindex (default: all)
+      # @param batch_size [Integer] number of records per batch
+      # @param on_progress [Proc, nil] optional callback called after each batch
+      #   Receives a hash with :processed and :total keys (and any other stats from Batch)
+      #
+      # @return [Integer] number of records processed
+      def reindex_vectors(scope: all, batch_size: 1_000, on_progress: nil)
+        config = _vectra_config
+        client = vectra_client
+        batch = Vectra::Batch.new(client)
+
+        processed = 0
+
+        scope.in_batches(of: batch_size).each do |relation|
+          records = relation.to_a
+
+          vectors = records.map do |record|
+            vector = record.send(config[:attribute])
+            next if vector.nil?
+
+            metadata = config[:metadata_fields].each_with_object({}) do |field, hash|
+              hash[field.to_s] = record.send(field) if record.respond_to?(field)
+            end
+
+            {
+              id: "#{config[:index]}_#{record.id}",
+              values: vector,
+              metadata: metadata
+            }
+          end.compact
+
+          next if vectors.empty?
+
+          batch.upsert_async(
+            index: config[:index],
+            vectors: vectors,
+            namespace: nil,
+            on_progress: on_progress
+          )
+
+          processed += vectors.size
+        end
+
+        processed
+      end
+
       # Search vectors
       #
       # @api private
@@ -195,4 +245,5 @@ module Vectra
       "#{self.class._vectra_config[:index]}_#{id}"
     end
   end
+  # rubocop:enable Metrics/ModuleLength
 end

data/lib/vectra/cache.rb

@@ -258,4 +258,53 @@ module Vectra
       "#{index}:f:#{id}:#{namespace || 'default'}"
     end
   end
+
+  # Helper for caching embeddings based on model, record ID and input text.
+  #
+  # @example
+  #   cache = Vectra::Cache.new(ttl: 600, max_size: 1000)
+  #
+  #   embedding = Vectra::Embeddings.fetch(
+  #     cache: cache,
+  #     model_name: "Product",
+  #     id: product.id,
+  #     input: product.description,
+  #     field: :description
+  #   ) do
+  #     EmbeddingService.generate(product.description)
+  #   end
+  #
+  module Embeddings
+    module_function
+
+    # Build a stable cache key for an embedding.
+    #
+    # @param model_name [String] model class name (e.g. "Product")
+    # @param id [Integer, String] record ID
+    # @param input [String] raw input used for embedding
+    # @param field [Symbol, String, nil] optional field name
+    #
+    # @return [String] cache key
+    def cache_key(model_name:, id:, input:, field: nil)
+      field_part = field ? field.to_s : "default"
+      base = "#{model_name}:#{field_part}:#{id}:#{input}"
+      digest = Digest::SHA256.hexdigest(base)[0, 32]
+      "emb:#{model_name}:#{field_part}:#{digest}"
+    end
+
+    # Fetch an embedding from cache or compute and store it.
+    #
+    # @param cache [Vectra::Cache] cache instance
+    # @param model_name [String] model class name
+    # @param id [Integer, String] record ID
+    # @param input [String] input used for embedding
+    # @param field [Symbol, String, nil] optional field name
+    #
+    # @yield block that computes the embedding when not cached
+    # @return [Object] cached or computed embedding
+    def fetch(cache:, model_name:, id:, input:, field: nil, &block)
+      key = cache_key(model_name: model_name, id: id, input: input, field: field)
+      cache.fetch(key, &block)
+    end
+  end
 end

data/lib/vectra/client.rb

@@ -40,7 +40,7 @@ module Vectra
   class Client
     include Vectra::HealthCheck
 
-    attr_reader :config, :provider
+    attr_reader :config, :provider, :default_index, :default_namespace
 
     # Initialize a new Client
     #
@@ -49,17 +49,21 @@ module Vectra
     # @param environment [String, nil] environment/region
     # @param host [String, nil] custom host URL
     # @param options [Hash] additional options
+    # @option options [String] :index default index name
+    # @option options [String] :namespace default namespace
     def initialize(provider: nil, api_key: nil, environment: nil, host: nil, **options)
       @config = build_config(provider, api_key, environment, host, options)
       @config.validate!
       @provider = build_provider
+      @default_index = options[:index]
+      @default_namespace = options[:namespace]
     end
 
     # Upsert vectors into an index
     #
-    # @param index [String] the index/collection name
     # @param vectors [Array<Hash, Vector>] vectors to upsert
-    # @param namespace [String, nil] optional namespace (provider-specific)
+    # @param index [String, nil] the index/collection name (falls back to client's default)
+    # @param namespace [String, nil] optional namespace (provider-specific, falls back to client's default)
     # @return [Hash] upsert response with :upserted_count
     #
     # @example Upsert vectors
@@ -71,7 +75,9 @@ module Vectra
     #     ]
     #   )
     #
-    def upsert(index:, vectors:, namespace: nil)
+    def upsert(vectors:, index: nil, namespace: nil)
+      index ||= default_index
+      namespace ||= default_namespace
       validate_index!(index)
       validate_vectors!(vectors)
 
@@ -130,6 +136,10 @@ module Vectra
       # Handle positional argument for index in non-builder case
       index = index_arg if index_arg && index.nil?
 
+      # Fall back to default index/namespace when not provided
+      index ||= default_index
+      namespace ||= default_namespace
+
       # Backwards-compatible path: perform query immediately
       validate_index!(index)
       validate_query_vector!(vector)
@@ -157,16 +167,18 @@ module Vectra
 
     # Fetch vectors by IDs
     #
-    # @param index [String] the index/collection name
     # @param ids [Array<String>] vector IDs to fetch
-    # @param namespace [String, nil] optional namespace
+    # @param index [String, nil] the index/collection name (falls back to client's default)
+    # @param namespace [String, nil] optional namespace (falls back to client's default)
     # @return [Hash<String, Vector>] hash of ID to Vector
     #
     # @example Fetch vectors
     #   vectors = client.fetch(index: 'my-index', ids: ['vec1', 'vec2'])
     #   vectors['vec1'].values # => [0.1, 0.2, 0.3]
     #
-    def fetch(index:, ids:, namespace: nil)
+    def fetch(ids:, index: nil, namespace: nil)
+      index ||= default_index
+      namespace ||= default_namespace
       validate_index!(index)
       validate_ids!(ids)
 
@@ -182,8 +194,8 @@ module Vectra
 
     # Update a vector's metadata or values
     #
-    # @param index [String] the index/collection name
     # @param id [String] vector ID
+    # @param index [String, nil] the index/collection name (falls back to client's default)
     # @param metadata [Hash, nil] new metadata (merged with existing)
     # @param values [Array<Float>, nil] new vector values
     # @param namespace [String, nil] optional namespace
@@ -196,7 +208,9 @@ module Vectra
     #     metadata: { category: 'updated' }
     #   )
     #
-    def update(index:, id:, metadata: nil, values: nil, namespace: nil)
+    def update(id:, index: nil, metadata: nil, values: nil, namespace: nil)
+      index ||= default_index
+      namespace ||= default_namespace
       validate_index!(index)
       validate_id!(id)
 
@@ -236,7 +250,9 @@ module Vectra
     # @example Delete all
     #   client.delete(index: 'my-index', delete_all: true)
     #
-    def delete(index:, ids: nil, namespace: nil, filter: nil, delete_all: false)
+    def delete(index: nil, ids: nil, namespace: nil, filter: nil, delete_all: false)
+      index ||= default_index
+      namespace ||= default_namespace
       validate_index!(index)
 
       if ids.nil? && filter.nil? && !delete_all
@@ -280,7 +296,8 @@ module Vectra
     #   info = client.describe_index(index: 'my-index')
     #   puts info[:dimension]
     #
-    def describe_index(index:)
+    def describe_index(index: nil)
+      index ||= default_index
       validate_index!(index)
       provider.describe_index(index: index)
     end
@@ -295,7 +312,9 @@ module Vectra
     #   stats = client.stats(index: 'my-index')
     #   puts "Total vectors: #{stats[:total_vector_count]}"
     #
-    def stats(index:, namespace: nil)
+    def stats(index: nil, namespace: nil)
+      index ||= default_index
+      namespace ||= default_namespace
       validate_index!(index)
       provider.stats(index: index, namespace: namespace)
     end
@@ -359,7 +378,8 @@ module Vectra
     #   namespaces = client.list_namespaces(index: 'documents')
     #   namespaces.each { |ns| puts "Namespace: #{ns}" }
     #
-    def list_namespaces(index:)
+    def list_namespaces(index: nil)
+      index ||= default_index
       validate_index!(index)
       stats_data = provider.stats(index: index)
       namespaces = stats_data[:namespaces] || {}
@@ -408,6 +428,8 @@ module Vectra
     #
     def hybrid_search(index:, vector:, text:, alpha: 0.5, top_k: 10, namespace: nil,
                       filter: nil, include_values: false, include_metadata: true)
+      index ||= default_index
+      namespace ||= default_namespace
       validate_index!(index)
       validate_query_vector!(vector)
       raise ValidationError, "Text query cannot be nil or empty" if text.nil? || text.empty?
@@ -671,6 +693,48 @@ module Vectra
       config.logger.debug("[Vectra] #{message}")
       config.logger.debug("[Vectra] #{data.inspect}") if data
     end
+
+    # Temporarily override default index within a block.
+    #
+    # @param index [String] temporary index name
+    # @yield [Client] yields self with overridden index
+    # @return [Object] block result
+    def with_index(index)
+      previous = @default_index
+      @default_index = index
+      yield self
+    ensure
+      @default_index = previous
+    end
+
+    # Temporarily override default namespace within a block.
+    #
+    # @param namespace [String] temporary namespace
+    # @yield [Client] yields self with overridden namespace
+    # @return [Object] block result
+    def with_namespace(namespace)
+      previous = @default_namespace
+      @default_namespace = namespace
+      yield self
+    ensure
+      @default_namespace = previous
+    end
+
+    # Temporarily override both index and namespace within a block.
+    #
+    # @param index [String] temporary index name
+    # @param namespace [String] temporary namespace
+    # @yield [Client] yields self with overridden index and namespace
+    # @return [Object] block result
+    def with_index_and_namespace(index, namespace)
+      with_index(index) do
+        with_namespace(namespace) do
+          yield self
+        end
+      end
+    end
+
+    public :with_index, :with_namespace, :with_index_and_namespace
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/vectra/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vectra
-  VERSION = "1.0.7"
+  VERSION = "1.0.8"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 1.0.7
+  version: 1.0.8
 platform: ruby
 authors:
 - Mijo Kristo