Class: Chroma::Resources::Collection

Inherits:
Object
  • Object
show all
Includes:
APIOperations::Request
Defined in:
lib/chroma/resources/collection.rb

Overview

A Collection class represents a store for your embeddings, documents, and any additional metadata. This class can be instantiated by receiving the collection’s name and metadata hash.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from APIOperations::Request

included

Constructor Details

#initialize(id:, name:, metadata: nil) ⇒ Collection

Returns a new instance of Collection.



16
17
18
19
20
 
# File 'lib/chroma/resources/collection.rb', line 16

def initialize(id:, name:, metadata: nil)
  @id = id
  @name = name
  @metadata = metadata
end

Instance Attribute Details

#id ⇒ Object (readonly)

Returns the value of attribute id.



12
13
14
 
# File 'lib/chroma/resources/collection.rb', line 12

def id
  @id
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata.



14
15
16
 
# File 'lib/chroma/resources/collection.rb', line 14

def metadata
  @metadata
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



13
14
15
 
# File 'lib/chroma/resources/collection.rb', line 13

def name
  @name
end

Class Method Details

.create(name, metadata = nil) ⇒ Object

Create a new collection on the database.

name - The name of the collection. Name needs to be between 3-63 characters, starts and ends

with an alphanumeric character, contains only alphanumeric characters, underscores or hyphens (-), and
contains no two consecutive periods

metadata - A hash of additional metadata associated with the collection.

Examples

collection = Chorma::Resources::Collection.create("ruby-documentation", {source: "Ruby lang website"})

Returns the created collection object.



252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/chroma/resources/collection.rb', line 252

def self.create(name, metadata = nil)
  payload = {name:, metadata:, get_or_create: false}

  result = execute_request(:post, "#{Chroma.api_url}/collections", payload)

  if result.success?
    data = result.success.body
    new(id: data["id"], name: data["name"], metadata: data["metadata"])
  else
    raise_failure_error(result)
  end
end

.delete(name) ⇒ Object

Deletes a collection from the database.

name - The name of the collection to delete.

Examples

Chroma::Resources::Collection.delete("ruby-documentation")

Returns true if the collection was successfully deleted, raise Chroma::InvalidRequestError otherwise.



337
338
339
340
341
342
343
 
# File 'lib/chroma/resources/collection.rb', line 337

def self.delete(name)
  result = execute_request(:delete, "#{Chroma.api_url}/collections/#{name}")

  return true if result.success?

  raise_failure_error(result)
end

.get(name) ⇒ Object

Retrieves a collection from the database.

name - The name of the collection to retrieve.

Examples

collection = Chroma::Resources::Colection.get("ruby-documentation")

Returns The retrieved collection object. Raises Chroma::InvalidRequestError if not found.



274
275
276
277
278
279
280
281
282
283
 
# File 'lib/chroma/resources/collection.rb', line 274

def self.get(name)
  result = execute_request(:get, "#{Chroma.api_url}/collections/#{name}")

  if result.success?
    data = result.success.body
    new(id: data["id"], name: data["name"], metadata: data["metadata"])
  else
    raise_failure_error(result)
  end
end

.get_or_create(name, metadata = nil) ⇒ Object

Get or create a collection on the database.

name - The name of the collection. Name needs to be between 3-63 characters, starts and ends

with an alphanumeric character, contains only alphanumeric characters, underscores or hyphens (-), and
contains no two consecutive periods

metadata - A hash of additional metadata associated with the collection, this is used if collection is created.

Examples

collection = Chorma::Resources::Collection.get_or_create("ruby-documentation", {source: "Ruby lang website"})

Returns the created collection object.



297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/chroma/resources/collection.rb', line 297

def self.get_or_create(name, metadata = nil)
  payload = {name:, metadata:, get_or_create: true}

  result = execute_request(:post, "#{Chroma.api_url}/collections", payload)

  if result.success?
    data = result.success.body
    new(id: data["id"], name: data["name"], metadata: data["metadata"])
  else
    raise_failure_error(result)
  end
end

.list ⇒ Object

Retrieves all collections in the database.

Examples

collections = Chroma::Resources::Collection.list

Returns An array of all collections in the database.



317
318
319
320
321
322
323
324
325
326
 
# File 'lib/chroma/resources/collection.rb', line 317

def self.list
  result = execute_request(:get, "#{Chroma.api_url}/collections")

  if result.success?
    data = result.success.body
    data.map { |item| new(id: item["id"], name: item["name"], metadata: item["metadata"]) }
  else
    raise_failure_error(result)
  end
end

.raise_failure_error(result) ⇒ Object 



345
346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/chroma/resources/collection.rb', line 345

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
  else
    raise Chroma::APIError.new(result.failure.body, status: result.failure.status, body: result.failure.body)
  end
end

Instance Method Details

#add(embeddings = []) ⇒ Object

Add one or many embeddings to the collection.

embeddings - An Array of Embeddings or one Embedding to add.

Examples

collection = Chroma::Resource::Collection.get("ruby-documentation")
collection.add(Embedding.new(id: "Array#fetch", embeddings[9.8, 2.3, 2.9], metadata: {url: "https://..."}))

Returns true with success or raises a Chroma::Error on failure.



109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/chroma/resources/collection.rb', line 109

def add(embeddings = [])
  embeddings_array = Array(embeddings)
  return false if embeddings_array.size == 0

  payload = build_embeddings_payload(embeddings_array)

  result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/add", payload)

  return true if result.success?

  self.class.raise_failure_error(result)
end

#count ⇒ Object

Count the number of embeddings in a collection.

Examples

collection = Chroma::Resource::Collection.get("ruby-documentation")
collection.count

Returns the count of embeddings in the collection.



207
208
209
210
211
212
213
 
# File 'lib/chroma/resources/collection.rb', line 207

def count
  result = self.class.execute_request(:get, "#{Chroma.api_url}/collections/#{id}/count")

  return result.success.body if result.success?

  self.class.raise_failure_error(result)
end

#delete(ids: nil, where: {}, where_document: {}) ⇒ Object

Delete embeddings from the collection.

ids [Array<Integer>, nil] The specific embedding IDs to delete (optional). where [Hash] Additional conditions to filter the embeddings to delete (optional). where_document [Hash] Additional conditions to filter the associated documents (optional).

Examples

collection = Chroma::Resource::Collection.get("ruby-documentation")
collection.delete(["Array#fetch", "Array#sort"])

Returns an Array of deleted global ids.



134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/chroma/resources/collection.rb', line 134

def delete(ids: nil, where: {}, where_document: {})
  payload = {
    ids:,
    where:,
    where_document:
  }

  result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/delete", payload)

  return result.success.body if result.success?

  self.class.raise_failure_error(result)
end

#get(ids: nil, where: {}, sort: nil, limit: nil, offset: nil, page: nil, page_size: nil, where_document: {}, include: %w[metadatas documents])) ⇒ Object

Get embeddings from the collection.

ids - An Array of the specific embedding IDs to retrieve (optional). where - A Hash of additional conditions to filter the query results (optional). sort - The sorting criteria for the query results (optional). limit - The maximum number of embeddings to retrieve (optional). offset - The offset for pagination (optional). page - The page number for pagination (optional). page_size - The page size for pagination (optional). where_document - A Hash of additional conditions to filter the associated documents (optional). include - An Array of the additional information to include in the query results (optional). Metadatas,

and documents by default.

Examples

collection = Chroma::Resource::Collection.get("ruby-documentation")
embeddings = collection.get([Array#sort, "Array#each"])

Returns an Array of Embeddings



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/chroma/resources/collection.rb', line 74

def get(ids: nil, where: {}, sort: nil, limit: nil, offset: nil, page: nil, page_size: nil, where_document: {}, include: %w[metadatas documents])
  if !page.nil? && !page_size.nil?
    offset = (page - 1) * page_size
    limit = page_size
  end

  payload = {
    ids:,
    where:,
    sort:,
    limit:,
    offset:,
    where_document:,
    include:
  }

  result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/get", payload)

  if result.success?
    build_embeddings_response(result.success.body)
  else
    self.class.raise_failure_error(result)
  end
end

#modify(new_name, new_metadata: {}) ⇒ Object

Modify the name and metadata of the current collection.

new_name - The new name for the collection. new_metadata - The new metadata hash for the collection.

Examples:

collection = Chroma::Resource::Collection.get("ruby-documentation")
collection.modify("ruby-3.2-documentation")

Returns nothing.



226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/chroma/resources/collection.rb', line 226

def modify(new_name, new_metadata: {})
  payload = {new_name:}
  payload[:new_metadata] = new_metadata if new_metadata.any?

  result = self.class.execute_request(:put, "#{Chroma.api_url}/collections/#{id}", payload)

  if result.success?
    @name = new_name
    @metadata = new_metadata
  else
    self.class.raise_failure_error(result)
  end
end

#query(query_embeddings:, results: 10, where: {}, where_document: {}, include: %w[metadatas documents distances])) ⇒ Object

Query the collection and return an array of embeddings.

query_embeddings - An array of the embeddings to use for querying the collection. results - The maximum number of results to return. 10 by default. where - A Hash of additional conditions to filter the query results (optional). where_document - A Hash of additional conditions to filter the associated documents (optional). include - An Array of the additional information to include in the query results (optional). Metadatas,

documents, and distances by default.

Examples

collection = Chroma::Resource::Collection.get("ruby-documentation")
embeddings = collection.query(query_embeddings: [[1.5, 2.9, 3.3]], results: 5)

Return an Array of Embedding with query results.



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/chroma/resources/collection.rb', line 37

def query(query_embeddings:, results: 10, where: {}, where_document: {}, include: %w[metadatas documents distances])
  payload = {
    query_embeddings:,
    n_results: results,
    where:,
    where_document:,
    include:
  }

  result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/query", payload)

  if result.success?
    build_embeddings_response(result.success.body)
  else
    self.class.raise_failure_error(result)
  end
end

#update(embeddings = []) ⇒ Object

Update one or many embeddings to the collection.

embeddings - An Array of Embeddings or one Embedding to add.

Examples

collection = Chroma::Resource::Collection.get("ruby-documentation")
collection.update(Embedding.new(id: "Array#fetch", embeddings[9.8, 2.3, 2.9], metadata: {url: "https://..."}))

Returns true with success or raises a Chroma::Error on failure.



158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/chroma/resources/collection.rb', line 158

def update(embeddings = [])
  embeddings_array = Array(embeddings)
  return false if embeddings_array.size == 0

  payload = build_embeddings_payload(embeddings_array)
  payload.delete(:increment_index)

  result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/update", payload)

  return true if result.success?

  self.class.raise_failure_error(result)
end

#upsert(embeddings = []) ⇒ Object

Upsert (insert or update) one or many embeddings to the collection.

embeddings - An Array of Embeddings or one Embedding to add.

Examples

collection = Chroma::Resource::Collection.get("ruby-documentation")
embeddings = [
  Embedding.new(id: "Array#fetch", embeddings: [9.8, 2.3, 2.9], metadata: {url: "https://..."}),
  Embedding.new(id: "Array#select", embeddings: [5.6, 3.1, 4.7], metadata: {url: "https://..."})
]
collection.upsert(embeddings)

Returns true with success or raises a Chroma::Error on failure.



186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/chroma/resources/collection.rb', line 186

def upsert(embeddings = [])
  embeddings_array = Array(embeddings)
  return false if embeddings_array.size == 0

  payload = build_embeddings_payload(embeddings_array)

  result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/upsert", payload)

  return true if result.success?

  self.class.raise_failure_error(result)
end