vectra-client 1.0.6 → 1.0.8

data/lib/vectra/client.rb

@@ -36,10 +36,11 @@ module Vectra
   #     environment: 'us-east-1'
   #   )
   #
+  # rubocop:disable Metrics/ClassLength
   class Client
     include Vectra::HealthCheck
 
-    attr_reader :config, :provider
+    attr_reader :config, :provider, :default_index, :default_namespace
 
     # Initialize a new Client
     #
@@ -48,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
@@ -70,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)
 
@@ -129,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)
@@ -156,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)
 
@@ -181,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
@@ -195,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)
 
@@ -235,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
@@ -279,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
@@ -294,11 +312,80 @@ 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
 
+    # Create a new index
+    #
+    # @param name [String] the index name
+    # @param dimension [Integer] vector dimension
+    # @param metric [String] distance metric (default: "cosine")
+    # @param options [Hash] provider-specific options
+    # @return [Hash] index information
+    # @raise [NotImplementedError] if provider doesn't support index creation
+    #
+    # @example
+    #   client.create_index(name: 'documents', dimension: 384, metric: 'cosine')
+    #
+    def create_index(name:, dimension:, metric: "cosine", **options)
+      unless provider.respond_to?(:create_index)
+        raise NotImplementedError, "Provider #{provider_name} does not support index creation"
+      end
+
+      Instrumentation.instrument(
+        operation: :create_index,
+        provider: provider_name,
+        index: name,
+        metadata: { dimension: dimension, metric: metric }
+      ) do
+        provider.create_index(name: name, dimension: dimension, metric: metric, **options)
+      end
+    end
+
+    # Delete an index
+    #
+    # @param name [String] the index name
+    # @return [Hash] delete response
+    # @raise [NotImplementedError] if provider doesn't support index deletion
+    #
+    # @example
+    #   client.delete_index(name: 'documents')
+    #
+    def delete_index(name:)
+      unless provider.respond_to?(:delete_index)
+        raise NotImplementedError, "Provider #{provider_name} does not support index deletion"
+      end
+
+      Instrumentation.instrument(
+        operation: :delete_index,
+        provider: provider_name,
+        index: name
+      ) do
+        provider.delete_index(name: name)
+      end
+    end
+
+    # List all namespaces in an index
+    #
+    # @param index [String] the index name
+    # @return [Array<String>] list of namespace names
+    #
+    # @example
+    #   namespaces = client.list_namespaces(index: 'documents')
+    #   namespaces.each { |ns| puts "Namespace: #{ns}" }
+    #
+    def list_namespaces(index: nil)
+      index ||= default_index
+      validate_index!(index)
+      stats_data = provider.stats(index: index)
+      namespaces = stats_data[:namespaces] || {}
+      namespaces.keys.reject(&:empty?) # Exclude empty/default namespace
+    end
+
     # Hybrid search combining semantic (vector) and keyword (text) search
     #
     # Combines the best of both worlds: semantic understanding from vectors
@@ -341,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?
@@ -604,5 +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.6"
+  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.6
+  version: 1.0.8
 platform: ruby
 authors:
 - Mijo Kristo
@@ -251,6 +251,8 @@ files:
 - docs/_site/providers/weaviate/index.html
 - docs/_site/robots.txt
 - docs/_site/sitemap.xml
+- docs/api/cheatsheet.md
+- docs/api/methods.md
 - docs/api/overview.md
 - docs/assets/favicon.svg
 - docs/assets/logo.svg
@@ -263,23 +265,27 @@ files:
 - docs/examples/index.md
 - docs/examples/real-world.md
 - docs/grafana_final.png
+- docs/guides/faq.md
 - docs/guides/getting-started.md
 - docs/guides/installation.md
 - docs/guides/monitoring.md
 - docs/guides/performance.md
 - docs/guides/rails-integration.md
 - docs/guides/rails-troubleshooting.md
+- docs/guides/recipes.md
 - docs/guides/runbooks/cache-issues.md
 - docs/guides/runbooks/high-error-rate.md
 - docs/guides/runbooks/high-latency.md
 - docs/guides/runbooks/pool-exhausted.md
 - docs/guides/security.md
+- docs/guides/testing.md
 - docs/index.md
 - docs/providers/index.md
 - docs/providers/memory.md
 - docs/providers/pgvector.md
 - docs/providers/pinecone.md
 - docs/providers/qdrant.md
+- docs/providers/selection.md
 - docs/providers/weaviate.md
 - examples/GRAFANA_QUICKSTART.md
 - examples/README.md