weaviate-ruby 0.9.2 → 0.10.0

data/lib/weaviate/backups.rb

@@ -4,17 +4,29 @@ module Weaviate
   class Backups < Base
     PATH = "backups"
 
+    # List backups on a backend.
+    # @param order [String] "asc" or "desc" (default) by start time
+    def list(backend:, order: nil)
+      response = client.connection.get("#{PATH}/#{backend}") do |req|
+        req.params["order"] = order unless order.nil?
+      end
+      response.body
+    end
+
+    # @param config [Hash] Backup configuration, e.g. { Bucket: "my-bucket", Path: "backups", CPUPercentage: 80 }
     def create(
       backend:,
       id:,
       include: nil,
-      exclude: nil
+      exclude: nil,
+      config: nil
     )
       response = client.connection.post("#{PATH}/#{backend}") do |req|
         req.body = {}
         req.body["id"] = id
         req.body["include"] = include if include
         req.body["exclude"] = exclude if exclude
+        req.body["config"] = config if config
       end
 
       response.body
@@ -22,22 +34,41 @@ module Weaviate
 
     def get(
       backend:,
-      id:
+      id:,
+      bucket: nil,
+      path: nil
     )
-      response = client.connection.get("#{PATH}/#{backend}/#{id}")
+      response = client.connection.get("#{PATH}/#{backend}/#{id}") do |req|
+        location_params(req, bucket, path)
+      end
       response.body
     end
 
+    # Cancel a backup that is in progress.
+    def cancel(
+      backend:,
+      id:,
+      bucket: nil,
+      path: nil
+    )
+      response = client.connection.delete("#{PATH}/#{backend}/#{id}") do |req|
+        location_params(req, bucket, path)
+      end
+      response.success?
+    end
+
     def restore(
       backend:,
       id:,
       include: nil,
-      exclude: nil
+      exclude: nil,
+      config: nil
     )
       response = client.connection.post("#{PATH}/#{backend}/#{id}/restore") do |req|
         req.body = {}
         req.body["include"] = include if include
         req.body["exclude"] = exclude if exclude
+        req.body["config"] = config if config
       end
 
       response.body
@@ -45,10 +76,34 @@ module Weaviate
 
     def restore_status(
       backend:,
-      id:
+      id:,
+      bucket: nil,
+      path: nil
     )
-      response = client.connection.get("#{PATH}/#{backend}/#{id}/restore")
+      response = client.connection.get("#{PATH}/#{backend}/#{id}/restore") do |req|
+        location_params(req, bucket, path)
+      end
       response.body
     end
+
+    # Cancel a restore that is in progress.
+    def cancel_restore(
+      backend:,
+      id:,
+      bucket: nil,
+      path: nil
+    )
+      response = client.connection.delete("#{PATH}/#{backend}/#{id}/restore") do |req|
+        location_params(req, bucket, path)
+      end
+      response.success?
+    end
+
+    private
+
+    def location_params(req, bucket, path)
+      req.params["bucket"] = bucket unless bucket.nil?
+      req.params["path"] = path unless path.nil?
+    end
   end
 end

data/lib/weaviate/classifications.rb

@@ -27,9 +27,7 @@ module Weaviate
         req.body["filters"] = filters if filters
       end
 
-      if response.success?
-        response.body
-      end
+      response.body
     end
   end
 end

data/lib/weaviate/client.rb

@@ -1,47 +1,91 @@
 # frozen_string_literal: true
 
-require "faraday"
-require "graphlient"
+require "logger"
 
 module Weaviate
   class Client
-    attr_reader :url, :api_key, :model_service, :model_service_api_key, :adapter, :logger
+    attr_reader :url, :api_key, :model_service, :model_service_api_key, :headers, :proxy, :logger,
+      :open_timeout, :read_timeout, :write_timeout
 
     API_VERSION = "v1"
 
+    # Headers Weaviate reads model provider API keys from. Providers that need more than one
+    # header (e.g. AWS) or a custom base URL can be configured with the `headers:` option.
     API_KEY_HEADERS = {
-      ollama: "X-Ollama-Not-Used",
-      openai: "X-OpenAI-Api-Key",
+      anthropic: "X-Anthropic-Api-Key",
+      anyscale: "X-Anyscale-Api-Key",
       azure_openai: "X-Azure-Api-Key",
       cohere: "X-Cohere-Api-Key",
+      contextualai: "X-ContextualAI-Api-Key",
+      databricks: "X-Databricks-Token",
+      deepseek: "X-Deepseek-Api-Key",
+      digitalocean: "X-Digitalocean-Api-Key",
+      friendliai: "X-Friendli-Token",
+      google: "X-Goog-Api-Key",
+      google_palm: "X-Palm-Api-Key",
+      google_studio: "X-Goog-Studio-Api-Key",
+      google_vertex: "X-Goog-Vertex-Api-Key",
       huggingface: "X-HuggingFace-Api-Key",
-      google_palm: "X-Palm-Api-Key"
+      jinaai: "X-JinaAI-Api-Key",
+      mistral: "X-Mistral-Api-Key",
+      nvidia: "X-Nvidia-Api-Key",
+      ollama: "X-Ollama-Not-Used",
+      openai: "X-OpenAI-Api-Key",
+      twelvelabs: "X-Twelvelabs-Api-Key",
+      voyageai: "X-VoyageAI-Api-Key",
+      xai: "X-Xai-Api-Key"
     }
 
+    # @param url [String] The Weaviate instance URL
+    # @param api_key [String] The Weaviate API key
+    # @param model_service [Symbol] The service used to generate vectors, one of the API_KEY_HEADERS keys
+    # @param model_service_api_key [String] The API key for the model service
+    # @param headers [Hash] Additional headers sent with every request, e.g. { "X-Aws-Access-Key" => "...", "X-Aws-Secret-Key" => "..." }
+    # @param proxy [String] Proxy URL, e.g. "http://user:pass@localhost:8888". Defaults to the http_proxy/https_proxy env vars.
+    # @param logger [Logger] Logger for requests and responses
+    # @param open_timeout [Numeric] Seconds to wait for a connection to open. Defaults to Net::HTTP's 60 seconds.
+    # @param read_timeout [Numeric] Seconds to wait for a response. Defaults to Net::HTTP's 60 seconds.
+    # @param write_timeout [Numeric] Seconds to wait for a request to be written. Defaults to Net::HTTP's 60 seconds.
+    # @param adapter [Object] Deprecated and ignored, Faraday is no longer used
     def initialize(
       url:,
       api_key: nil,
       model_service: nil,
       model_service_api_key: nil,
-      adapter: Faraday.default_adapter,
-      logger: nil
+      headers: {},
+      proxy: nil,
+      logger: nil,
+      open_timeout: nil,
+      read_timeout: nil,
+      write_timeout: nil,
+      adapter: nil
     )
       validate_model_service!(model_service) unless model_service.nil?
+      warn "[weaviate-ruby] The `adapter:` option is deprecated and ignored, Faraday is no longer used." unless adapter.nil?
 
       @url = url
       @api_key = api_key
       @model_service = model_service
       @model_service_api_key = model_service_api_key
-      @adapter = adapter
+      @headers = headers
+      @proxy = proxy
       @logger = logger || Logger.new($stdout)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @write_timeout = write_timeout
     end
 
     def oidc
       Weaviate::OIDC.new(client: self).get
     end
 
+    def collections
+      @collections ||= Weaviate::Collections.new(client: self)
+    end
+
+    # @deprecated Weaviate now refers to schema classes as collections. Use {#collections} instead.
     def schema
-      @schema ||= Weaviate::Schema.new(client: self)
+      collections
     end
 
     def meta
@@ -49,9 +93,10 @@ module Weaviate
       @meta.get
     end
 
-    def nodes
+    # @see Weaviate::Nodes#list
+    def nodes(**options)
       @nodes ||= Weaviate::Nodes.new(client: self)
-      @nodes.list
+      @nodes.list(**options)
     end
 
     def live?
@@ -80,44 +125,47 @@ module Weaviate
       @query ||= Weaviate::Query.new(client: self)
     end
 
-    def graphql
-      headers = {}
+    def aliases
+      @aliases ||= Weaviate::Aliases.new(client: self)
+    end
 
-      if model_service && model_service_api_key
-        headers[API_KEY_HEADERS[model_service]] = model_service_api_key
-      end
+    def users
+      @users ||= Weaviate::Users.new(client: self)
+    end
 
-      if api_key
-        headers["Authorization"] = "Bearer #{api_key}"
-      end
+    def roles
+      @roles ||= Weaviate::Roles.new(client: self)
+    end
 
-      @graphql ||= Graphlient::Client.new(
-        "#{url}/#{API_VERSION}/graphql",
-        headers: headers,
-        http_options: {
-          read_timeout: 20,
-          write_timeout: 30
-        }
-      )
+    def groups
+      @groups ||= Weaviate::Groups.new(client: self)
+    end
+
+    def graphql
+      @graphql ||= Weaviate::GraphQL.new(client: self)
     end
 
     def connection
-      @connection ||= Faraday.new(url: "#{url}/#{API_VERSION}/") do |faraday|
-        if api_key
-          faraday.request :authorization, :Bearer, api_key
-        end
-        faraday.request :json
-        faraday.response :logger, logger, {headers: true, bodies: true, errors: true}
-        faraday.response :json, content_type: /\bjson$/
-        faraday.response :raise_error
-        faraday.adapter adapter
-
-        faraday.headers[API_KEY_HEADERS[model_service]] = model_service_api_key if model_service && model_service_api_key
-      end
+      @connection ||= Weaviate::Connection.new(
+        url: "#{url}/#{API_VERSION}",
+        headers: default_headers.merge(headers),
+        logger: logger,
+        proxy: proxy,
+        open_timeout: open_timeout,
+        read_timeout: read_timeout,
+        write_timeout: write_timeout
+      )
     end
 
     private
 
+    def default_headers
+      headers = {"User-Agent" => "weaviate-ruby/#{Weaviate::VERSION}"}
+      headers["Authorization"] = "Bearer #{api_key}" if api_key
+      headers[API_KEY_HEADERS[model_service]] = model_service_api_key if model_service && model_service_api_key
+      headers
+    end
+
     def validate_model_service!(model_service)
       unless API_KEY_HEADERS.key?(model_service)
         raise ArgumentError, "Invalid model service: #{model_service}. Acceptable values are: #{API_KEY_HEADERS.keys.join(", ")}"

data/lib/weaviate/{schema.rb → collections.rb}

@@ -1,27 +1,25 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Weaviate
-  class Schema < Base
+  # Manage collections (formerly known as "classes" in the Weaviate schema).
+  class Collections < Base
     PATH = "schema"
 
-    # Dumps the current Weaviate schema. The result contains an array of objects.
+    # Lists all collections in the Weaviate schema.
     def list
       response = client.connection.get(PATH)
       response.body
     end
 
-    # Get a single class from the schema
+    # Get a single collection
     def get(class_name:)
       response = client.connection.get("#{PATH}/#{class_name}")
-
-      if response.success?
-        response.body
-      elsif response.status == 404
-        response.reason_phrase
-      end
+      response.body
     end
 
-    # Create a new data object class in the schema.
+    # Create a new collection.
     def create(
       class_name:,
       description: nil,
@@ -34,7 +32,8 @@ module Weaviate
       vectorizer: nil,
       module_config: nil,
       inverted_index_config: nil,
-      replication_config: nil
+      replication_config: nil,
+      vector_config: nil
     )
       response = client.connection.post(PATH) do |req|
         req.body = {}
@@ -56,26 +55,21 @@ module Weaviate
 
         req.body["invertedIndexConfig"] = inverted_index_config unless inverted_index_config.nil?
         req.body["replicationConfig"] = replication_config unless replication_config.nil?
+        req.body["vectorConfig"] = vector_config unless vector_config.nil?
       end
 
       response.body
     end
 
-    # Remove a class (and all data in the instances) from the schema.
+    # Remove a collection (and all data in the instances).
     def delete(class_name:)
       response = client.connection.delete("#{PATH}/#{class_name}")
-
-      if response.success?
-        response.body.empty?
-      else
-        response.body
-      end
+      response.body.empty?
     end
 
-    # Update settings of an existing schema class.
-    # TODO: Fix it.
-    # This endpoint keeps returning the following error:
-    # => {"error"=>[{"message"=>"properties cannot be updated through updating the class. Use the add property feature (e.g. \"POST /v1/schema/{className}/properties\") to add additional properties"}]}
+    # Update settings of an existing collection.
+    # Weaviate replaces the whole collection definition on update, so the provided settings are merged
+    # into the current definition. Immutable settings and existing properties cannot be changed.
     def update(
       class_name:,
       description: nil,
@@ -85,45 +79,73 @@ module Weaviate
       module_config: nil,
       properties: nil,
       inverted_index_config: nil,
-      replication_config: nil
+      replication_config: nil,
+      vector_config: nil
     )
+      changes = {
+        "description" => description,
+        "vectorIndexType" => vector_index_type,
+        "vectorIndexConfig" => vector_index_config,
+        "vectorizer" => vectorizer,
+        "moduleConfig" => module_config,
+        "properties" => properties,
+        "invertedIndexConfig" => inverted_index_config,
+        "replicationConfig" => replication_config,
+        "vectorConfig" => vector_config
+      }.compact
+
       response = client.connection.put("#{PATH}/#{class_name}") do |req|
-        req.body = {}
-        req.body["class"] = class_name unless class_name.nil?
-        req.body["description"] = description unless description.nil?
-        req.body["vectorIndexType"] = vector_index_type unless vector_index_type.nil?
-        req.body["vectorIndexConfig"] = vector_index_config unless vector_index_config.nil?
-        req.body["vectorizer"] = vectorizer unless vectorizer.nil?
-        req.body["moduleConfig"] = module_config unless module_config.nil?
-        req.body["properties"] = properties unless properties.nil?
-        req.body["invertedIndexConfig"] = inverted_index_config unless inverted_index_config.nil?
-        req.body["replicationConfig"] = replication_config unless replication_config.nil?
+        req.body = deep_merge(get(class_name: class_name), JSON.parse(changes.to_json))
       end
 
-      if response.success?
-      end
       response.body
     end
 
-    # Adds one or more tenants to a class.
+    # Adds one or more tenants to a collection.
+    # @param tenants [Array<String, Hash>] Tenant names, or hashes such as { name: "a", activityStatus: "COLD" }
     def add_tenants(
       class_name:,
       tenants:
     )
       response = client.connection.post("#{PATH}/#{class_name}/tenants") do |req|
-        tenants_str = tenants.map { |t| %({"name": "#{t}"}) }.join(", ")
-        req.body = "[#{tenants_str}]"
+        req.body = tenants_body(tenants)
+      end
+      response.body
+    end
+
+    # Update the activity status of one or more tenants.
+    # @param tenants [Array<Hash>] e.g. [{ name: "a", activityStatus: "COLD" }]
+    def update_tenants(
+      class_name:,
+      tenants:
+    )
+      response = client.connection.put("#{PATH}/#{class_name}/tenants") do |req|
+        req.body = tenants_body(tenants)
       end
       response.body
     end
 
-    # List tenants of a class.
+    # Get a single tenant of a collection.
+    def get_tenant(class_name:, tenant:)
+      response = client.connection.get("#{PATH}/#{class_name}/tenants/#{tenant}")
+      response.body
+    end
+
+    # Check if a tenant exists.
+    def tenant_exists?(class_name:, tenant:)
+      response = client.connection.head("#{PATH}/#{class_name}/tenants/#{tenant}")
+      response.success?
+    rescue Weaviate::ResourceNotFound
+      false
+    end
+
+    # List tenants of a collection.
     def list_tenants(class_name:)
       response = client.connection.get("#{PATH}/#{class_name}/tenants")
       response.body
     end
 
-    # Remove one or more tenants from a class.
+    # Remove one or more tenants from a collection.
     def remove_tenants(
       class_name:,
       tenants:
@@ -132,13 +154,10 @@ module Weaviate
         req.body = tenants
       end
 
-      if response.success?
-      end
-
       response.body
     end
 
-    # Add a property to an existing schema class.
+    # Add a property to an existing collection.
     def add_property(
       class_name:,
       property:
@@ -147,15 +166,15 @@ module Weaviate
         req.body = property
       end
 
-      if response.success?
-      end
       response.body
     end
 
-    # Inspect the shards of a class
-    def shards(class_name:)
-      response = client.connection.get("#{PATH}/#{class_name}/shards")
-      response.body if response.success?
+    # Inspect the shards of a collection
+    def shards(class_name:, tenant: nil)
+      response = client.connection.get("#{PATH}/#{class_name}/shards") do |req|
+        req.params["tenant"] = tenant unless tenant.nil?
+      end
+      response.body
     end
 
     # Update shard status
@@ -166,15 +185,29 @@ module Weaviate
         req.body = {}
         req.body["status"] = status
       end
-      response.body if response.success?
+
+      response.body
     end
 
     private
 
+    def tenants_body(tenants)
+      Array(tenants).map { |tenant| tenant.is_a?(Hash) ? tenant : {name: tenant.to_s} }
+    end
+
+    def deep_merge(current, changes)
+      current.merge(changes) do |_key, current_value, new_value|
+        (current_value.is_a?(Hash) && new_value.is_a?(Hash)) ? deep_merge(current_value, new_value) : new_value
+      end
+    end
+
     def validate_status!(status)
       unless %w[READONLY READY].include?(status.to_s.upcase)
         raise ArgumentError, 'status must be either "READONLY" or "READY"'
       end
     end
   end
+
+  # @deprecated Weaviate now refers to schema classes as collections. Use {Collections} instead.
+  Schema = Collections
 end

data/lib/weaviate/connection.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Weaviate
+  # A minimal HTTP client built on Net::HTTP
+  class Connection
+    Request = Struct.new(:params, :headers, :body)
+
+    Response = Struct.new(:status, :reason_phrase, :headers, :body, keyword_init: true) do
+      def success?
+        (200..299).cover?(status)
+      end
+    end
+
+    METHODS = {
+      get: Net::HTTP::Get,
+      head: Net::HTTP::Head,
+      post: Net::HTTP::Post,
+      put: Net::HTTP::Put,
+      patch: Net::HTTP::Patch,
+      delete: Net::HTTP::Delete
+    }
+
+    ERRORS = {
+      400 => BadRequestError,
+      401 => UnauthorizedError,
+      403 => ForbiddenError,
+      404 => ResourceNotFound,
+      409 => ConflictError,
+      422 => UnprocessableEntityError
+    }
+
+    FILTERED_HEADERS = /authorization|api-key|token|secret|access-key/i
+
+    attr_reader :url, :headers, :logger, :proxy, :timeouts
+
+    def initialize(url:, headers: {}, logger: nil, proxy: nil, open_timeout: nil, read_timeout: nil, write_timeout: nil)
+      @url = url.chomp("/")
+      @headers = headers
+      @logger = logger
+      @proxy = proxy && URI(proxy)
+      @timeouts = {open_timeout: open_timeout, read_timeout: read_timeout, write_timeout: write_timeout}.compact
+    end
+
+    METHODS.each_key do |method|
+      define_method(method) do |path, &block|
+        request(method, path, &block)
+      end
+    end
+
+    private
+
+    def request(method, path)
+      req = Request.new({}, {}, nil)
+      yield req if block_given?
+
+      uri = URI("#{url}/#{path}")
+      uri.query = URI.encode_www_form(req.params) unless req.params.nil? || req.params.empty?
+
+      http_request = METHODS.fetch(method).new(uri)
+      headers.merge(req.headers).each { |k, v| http_request[k] = v }
+
+      unless req.body.nil?
+        http_request["Content-Type"] = "application/json"
+        http_request.body = req.body.is_a?(String) ? req.body : req.body.to_json
+      end
+
+      log_request(http_request, uri)
+
+      http_response = perform(uri, http_request)
+      response = build_response(http_response)
+
+      log_response(response, http_response)
+
+      raise_error!(response) unless response.success?
+
+      response
+    end
+
+    def perform(uri, http_request)
+      Net::HTTP.start(
+        uri.host,
+        uri.port,
+        proxy ? proxy.host : :ENV,
+        proxy&.port,
+        proxy&.user,
+        proxy&.password,
+        use_ssl: uri.scheme == "https",
+        **timeouts
+      ) do |http|
+        http.request(http_request)
+      end
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+      raise Weaviate::TimeoutError, e.message
+    rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+      raise Weaviate::ConnectionFailed, e.message
+    end
+
+    def build_response(http_response)
+      body = http_response.body.to_s
+
+      if http_response["Content-Type"].to_s.match?(/\bjson\b/) && !body.empty?
+        body = JSON.parse(body)
+      end
+
+      Response.new(
+        status: http_response.code.to_i,
+        reason_phrase: http_response.message,
+        headers: http_response.to_hash,
+        body: body
+      )
+    end
+
+    def raise_error!(response)
+      error_class = ERRORS.fetch(response.status) do
+        (response.status >= 500) ? ServerError : ClientError
+      end
+
+      raise error_class.new(response: response)
+    end
+
+    def log_request(http_request, uri)
+      return if logger.nil?
+
+      logger.info("request") { "#{http_request.method} #{uri}" }
+      logger.info("request") { format_headers(http_request.each_header.to_h) }
+      logger.info("request") { http_request.body } unless http_request.body.nil?
+    end
+
+    def log_response(response, http_response)
+      return if logger.nil?
+
+      logger.info("response") { "Status #{response.status}" }
+      logger.info("response") { format_headers(http_response.each_header.to_h) }
+      logger.info("response") { http_response.body } unless http_response.body.to_s.empty?
+    end
+
+    def format_headers(headers)
+      headers.map do |k, v|
+        "#{k}: #{k.match?(FILTERED_HEADERS) ? "[FILTERED]" : v.inspect}"
+      end.join("\n")
+    end
+  end
+end