chroma-db 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a4fc64ab9c97c9630f0f438467d4a126c7665a33992ad0f357ca9ddfaab7eeb
-  data.tar.gz: d5b48661b75917eaf8923dd7d2125230f9701144d3cffb18a5addeb8e90419e6
+  metadata.gz: 22e02f3e43fda5efcba180824acf3dd334c483750e06aa9f8ad6d326c19fafb4
+  data.tar.gz: 659ea81895f326b248f488682dfddb0c4ecf7f2058c6b48566b43fb5c71167cb
 SHA512:
-  metadata.gz: 986a2f8366a22ebca4b8f7aa831aa4bd04ef373768f62d7811b7f0f45d45dcc58d6fbe2758dc1af85ea2a8111d3aeee8185930b4639af412fb912d8067f5c970
-  data.tar.gz: ddbf174e31dd7999a6dd0462f9fe03b3e0a439a71bb0cb7487d1d09f558ebd6a67aa6f543e28babd432d5f9fb24804c52ad322a8f53e5737a396ba9c09222274
+  metadata.gz: 69c153e50ce71e7cf2c720b805d280700fcea66cbbda1e0135f0eebe57b6b01b021e43b1cb45d6f8441c70dbbcd739c5de9af7141eb84634029a38e558ac78b5
+  data.tar.gz: 4555bdb0f7bb65444a76cc0d0842d9b17597e170b8c6a519c8350ffe795c222c5262536fc42b17a126aad663a68142814c51dc56fd55e0ad898cba2a877fd972

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.9.0] 2026-06-11
+
+- Support Chroma v2 API.
+
+## 0.8.2 2024-10-16
+
+- Fixes API change in Collection#query method. Parameters `where` and `where_document` are now optional.
+
 ## 0.8.1 2024-10-16
 
 - Adds support for Chroma hosted service. See README for more details how to set your `api_key`, `tenant`, and `database`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    chroma-db (0.8.1)
+    chroma-db (0.9.0)
       dry-monads (~> 1.6)
       ruby-next (~> 1.0, >= 1.0.3)
       zeitwerk (~> 2.6.0)
@@ -103,6 +103,7 @@ PLATFORMS
   arm64-darwin-22
   arm64-darwin-24
   x86_64-darwin-22
+  x86_64-darwin-23
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -55,8 +55,9 @@ Chroma.database = "my_database" # Optional
 ## Requirements
 
 - Ruby 3.1.4 or newer
-- Chroma Database 0.4.24 or later running as a client/server model.
+- Chroma Database 0.6.3 or later running as a client/server model with Chroma v2 API.
 
+For Chroma database 0.6.2 or older (Chroma v1 API), please use version 0.8.2 of this gem.
 For Chroma database 0.3.22 or older, please use version 0.3.0 of this gem.
 
 ## Installation

data/lib/chroma/api_operations/request.rb

@@ -124,6 +124,21 @@ module Chroma
           request["X-Chroma-Token"] = api_key unless api_key.nil?
           request
         end
+
+        private def raise_failure_error(result)
+          case result.failure.error
+          in Exception => exception
+            raise Chroma::APIConnectionError.new(exception.message)
+          in Net::HTTPInternalServerError => response
+            if response.body.is_a?(String) && (response.body.include?("ValueError") || response.body.include?("IndexError") || response.body.include?("TypeError"))
+              raise Chroma::InvalidRequestError.new(result.failure.body, status: result.failure.status, body: result.failure.body)
+            else
+              raise Chroma::APIConnectionError.new(result.failure.body, status: result.failure.status, body: result.failure.body)
+            end
+          else
+            raise Chroma::APIError.new(result.failure.body, status: result.failure.status, body: result.failure.body)
+          end
+        end
       end
 
       def self.included(base)

data/lib/chroma/chroma_configuration.rb

@@ -94,7 +94,7 @@ module Chroma
 
     def initialize
       @api_base = "api"
-      @api_version = "v1"
+      @api_version = "v2"
 
       @log_level = Chroma::LEVEL_INFO
 

data/lib/chroma/resources/collection.rb

@@ -34,7 +34,7 @@ module Chroma
       #   embeddings = collection.query(query_embeddings: [[1.5, 2.9, 3.3]], results: 5)
       #
       # Return an Array of Embedding with query results.
-      def query(query_embeddings:, results: 10, where: {}, where_document: {}, include: %w[metadatas documents distances])
+      def query(query_embeddings:, results: 10, where: nil, where_document: nil, include: %w[metadatas documents distances])
         payload = {
           query_embeddings:,
           n_results: results,
@@ -43,7 +43,9 @@ module Chroma
           include:
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/query", payload)
+        payload.delete_if { |_key, value| value.nil? }
+
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{id}/query", payload)
 
         if result.success?
           build_embeddings_response(result.success.body)
@@ -87,7 +89,7 @@ module Chroma
           include:
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/get", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{id}/get", payload)
 
         if result.success?
           build_embeddings_response(result.success.body)
@@ -112,7 +114,7 @@ module Chroma
 
         payload = build_embeddings_payload(embeddings_array)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/add", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{id}/add", payload)
 
         return true if result.success?
 
@@ -138,13 +140,36 @@ module Chroma
           where_document:
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/delete", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{id}/delete", payload)
 
         return result.success.body if result.success?
 
         self.class.raise_failure_error(result)
       end
 
+      # Fork an existing collection.
+      #
+      # new_name [String] The new name of the collection (optional).
+      #
+      # Examples
+      #
+      #   collection = Chroma::Resource::Collection.get("ruby-documentation")
+      #   new_collection = collection.fork("new_collection_name")
+      #
+      # Returns a new collection with the specified name and containing identical data to the current collection.
+      def fork(new_name)
+        payload = {new_name: new_name}
+
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{id}/fork", payload)
+
+        if result.success?
+          data = result.success.body
+          self.class.new(id: data["id"], name: new_name, metadata: data["metadata"])
+        else
+          self.class.raise_failure_error(result)
+        end
+      end
+
       # Update one or many embeddings to the collection.
       #
       # embeddings - An Array of Embeddings or one Embedding to add.
@@ -162,7 +187,7 @@ module Chroma
         payload = build_embeddings_payload(embeddings_array)
         payload.delete(:increment_index)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/update", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{id}/update", payload)
 
         return true if result.success?
 
@@ -189,7 +214,7 @@ module Chroma
 
         payload = build_embeddings_payload(embeddings_array)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/upsert", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{id}/upsert", payload)
 
         return true if result.success?
 
@@ -205,7 +230,7 @@ module Chroma
       #
       # Returns the count of embeddings in the collection.
       def count
-        result = self.class.execute_request(:get, "#{Chroma.api_url}/collections/#{id}/count")
+        result = self.class.execute_request(:get, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{id}/count")
 
         return result.success.body if result.success?
 
@@ -227,7 +252,7 @@ module Chroma
         payload = {new_name:}
         payload[:new_metadata] = new_metadata if new_metadata.any?
 
-        result = self.class.execute_request(:put, "#{Chroma.api_url}/collections/#{id}", payload)
+        result = self.class.execute_request(:put, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{id}", payload)
 
         if result.success?
           @name = new_name
@@ -252,7 +277,7 @@ module Chroma
       def self.create(name, metadata = nil)
         payload = {name:, metadata:, get_or_create: false}
 
-        result = execute_request(:post, "#{Chroma.api_url}/collections", payload)
+        result = execute_request(:post, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections", payload)
 
         if result.success?
           data = result.success.body
@@ -272,7 +297,7 @@ module Chroma
       #
       # Returns The retrieved collection object. Raises Chroma::InvalidRequestError if not found.
       def self.get(name)
-        result = execute_request(:get, "#{Chroma.api_url}/collections/#{name}")
+        result = execute_request(:get, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{name}")
 
         if result.success?
           data = result.success.body
@@ -297,7 +322,7 @@ module Chroma
       def self.get_or_create(name, metadata = nil)
         payload = {name:, metadata:, get_or_create: true}
 
-        result = execute_request(:post, "#{Chroma.api_url}/collections", payload)
+        result = execute_request(:post, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections", payload)
 
         if result.success?
           data = result.success.body
@@ -315,7 +340,7 @@ module Chroma
       #
       # Returns An array of all collections in the database.
       def self.list
-        result = execute_request(:get, "#{Chroma.api_url}/collections")
+        result = execute_request(:get, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections")
 
         if result.success?
           data = result.success.body
@@ -335,14 +360,29 @@ module Chroma
       #
       # Returns true if the collection was successfully deleted, raise Chroma::InvalidRequestError otherwise.
       def self.delete(name)
-        result = execute_request(:delete, "#{Chroma.api_url}/collections/#{name}")
+        result = execute_request(:delete, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections/#{name}")
 
         return true if result.success?
 
         raise_failure_error(result)
       end
 
-      def self.raise_failure_error(result)
+      # Count the total number of collections in a given database.
+      #
+      # Examples
+      #
+      #   Chroma::Resource::Collection.collections_count
+      #
+      # Returns the count of collections in the database.
+      def self.collections_count
+        result = execute_request(:get, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{Chroma.database}/collections_count")
+
+        return result.success.body if result.success?
+
+        raise_failure_error(result)
+      end
+
+      def self.raise_failure_error1(result)
         case result.failure.error
         in Exception => exception
           raise Chroma::APIConnectionError.new(exception.message)

data/lib/chroma/resources/database.rb

@@ -7,6 +7,28 @@ module Chroma
       using RubyNext
 
       include Chroma::APIOperations::Request
+
+      attr_reader :id
+      attr_reader :name
+      attr_reader :tenant
+
+      def initialize(id:, name:, tenant:)
+        @id = id
+        @name = name
+        @tenant = tenant
+      end
+
+      # Get the current user's identity, tenant, and databases of the Chroma database server.
+      #
+      # Returns the current user's identity, tenant, and databases of the Chroma database server.
+      def self.auth_identity
+        result = execute_request(:get, "#{Chroma.api_url}/auth/identity")
+
+        return result.success.body if result.success?
+
+        raise_failure_error(result)
+      end
+
       # Get the version of the Chroma database server.
       #
       # Returns the version of the Chroma database server.
@@ -29,6 +51,17 @@ module Chroma
         raise_failure_error(result)
       end
 
+      # Check the hearlthcheck of the Chroma database server.
+      #
+      # Return a Hash with a boolean.
+      def self.healthcheck
+        result = execute_request(:get, "#{Chroma.api_url}/healthcheck")
+
+        return result.success.body if result.success?
+
+        raise_failure_error(result)
+      end
+
       # Check the heartbeat of the Chroma database server.
       #
       # Return a Hash with a timestamp.
@@ -40,21 +73,106 @@ module Chroma
         raise_failure_error(result)
       end
 
-      def self.raise_failure_error(result)
-        case result.failure.error
-        in Exception => exception
-          raise Chroma::APIConnectionError.new(exception.message)
-        in Net::HTTPInternalServerError => response
-          if response.body.is_a?(String) && (response.body.include?("ValueError") || response.body.include?("IndexError") || response.body.include?("TypeError"))
-            raise Chroma::InvalidRequestError.new(result.failure.body, status: result.failure.status, body: result.failure.body)
-          else
-            raise Chroma::APIConnectionError.new(result.failure.body, status: result.failure.status, body: result.failure.body)
-          end
+      # Check the pre-flight checks of the Chroma database server.
+      #
+      # Return a Hash with a timestamp.
+      def self.pre_flight_checks
+        result = execute_request(:get, "#{Chroma.api_url}/pre-flight-checks")
+
+        return result.success.body if result.success?
+
+        raise_failure_error(result)
+      end
+
+      # Lists all databases from the tenant.
+      #
+      # Examples
+      #
+      #   Chroma::Resources::Database.list
+      #
+      # Returns an array of all databases in the tenant.
+      def self.list
+        result = execute_request(:get, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases")
+
+        if result.success?
+          data = result.success.body
+          data.map { |item| new(id: item["id"], name: item["name"], tenant: item["tenant"]) }
+        else
+          raise_failure_error(result)
+        end
+      end
+
+      # Create a new database on the tenant.
+      #
+      # name - The name of the database.
+      #
+      # Examples
+      #
+      #   database = Chorma::Resources::Database.create("database-name")
+      #
+      # Returns true if the database was successfully created, raises Chroma::APIError otherwise.
+      def self.create(name)
+        payload = {name: name}
+
+        result = execute_request(:post, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases", payload)
+
+        return true if result.success?
+
+        raise_failure_error(result)
+      end
+
+      # Retrieves a database from the tenant.
+      #
+      # database_name - The name of the database to retrieve.
+      #
+      # Examples
+      #
+      #   Chroma::Resources::Database.get("database-name")
+      #
+      # Returns The retrieved database object. Raises Chroma::APIError if not found.
+      def self.get(database_name)
+        result = execute_request(:get, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{database_name}")
+
+        if result.success?
+          data = result.success.body
+          new(id: data["id"], name: data["name"], tenant: data["tenant"])
         else
-          raise Chroma::APIError.new(result.failure.body, status: result.failure.status, body: result.failure.body)
+          raise_failure_error(result)
         end
       end
-      private_class_method :raise_failure_error
+
+      # Deletes a database from the tenant.
+      #
+      # database_name - The name of the database to retrieve.
+      #
+      # Examples
+      #
+      #   Chroma::Resources::Database.delete("database-name")
+      #
+      # Returns true if the database was successfully deleted, raises Chroma::APIError otherwise.
+      def self.delete(database_name)
+        result = execute_request(:delete, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{database_name}")
+
+        return true if result.success?
+
+        raise_failure_error(result)
+      end
+
+      # Count the total number of collections in the database object.
+      #
+      # Examples
+      #
+      #   database = Chroma::Resources::Database.get("database-name")
+      #   database.collections_count
+      #
+      # Returns the count of collections in the database.
+      def collections_count
+        result = self.class.execute_request(:get, "#{Chroma.api_url}/tenants/#{Chroma.tenant}/databases/#{name}/collections_count")
+
+        return result.success.body if result.success?
+
+        self.class.raise_failure_error(result)
+      end
     end
   end
 end

data/lib/chroma/resources/tenant.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Chroma
+  module Resources
+    # A Tenant class represents a tenant  by its ID and name.
+    class Tenant
+      include Chroma::APIOperations::Request
+
+      attr_reader :id
+      attr_reader :name
+
+      def initialize(id:, name:)
+        @id = id
+        @name = name
+      end
+
+      # Create a new tenant.
+      #
+      # name - The name of the tenant.
+      #
+      # Examples
+      #
+      #   tenant = Chorma::Resources::Tenant.create("tenant-name")
+      #
+      # Returns true if the tenant was successfully created, raises Chroma::APIError otherwise.
+      def self.create(name)
+        payload = {name: name}
+
+        result = execute_request(:post, "#{Chroma.api_url}/tenants", payload)
+
+        return true if result.success?
+
+        raise_failure_error(result)
+      end
+
+      # Retrieves a tenant.
+      #
+      # tenant_name - The name of the tenant to retrieve.
+      #
+      # Examples
+      #
+      #   Chroma::Resources::Tenant.get("tenant-name")
+      #
+      # Returns The retrieved tenant object. Raises Chroma::APIError if not found.
+      def self.get(tenant_name)
+        result = execute_request(:get, "#{Chroma.api_url}/tenants/#{tenant_name}")
+
+        if result.success?
+          data = result.success.body
+          new(id: data["id"], name: data["name"])
+        else
+          raise_failure_error(result)
+        end
+      end
+    end
+  end
+end

data/lib/chroma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chroma
-  VERSION = "0.8.1"
+  VERSION = "0.9.0"
 end

data/lib/chroma-db.rb

@@ -20,3 +20,4 @@ require "chroma/errors"
 require "chroma/resources/embedding"
 require "chroma/resources/collection"
 require "chroma/resources/database"
+require "chroma/resources/tenant"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chroma-db
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Mario Alberto Chávez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-16 00:00:00.000000000 Z
+date: 2026-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-monads
@@ -103,6 +103,7 @@ files:
 - lib/chroma/resources/collection.rb
 - lib/chroma/resources/database.rb
 - lib/chroma/resources/embedding.rb
+- lib/chroma/resources/tenant.rb
 - lib/chroma/util.rb
 - lib/chroma/version.rb
 - sig/chroma.rbs
@@ -128,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Ruby client for Chroma DB.