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.



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

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.



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

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.



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

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.



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

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.



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

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 



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

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.



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

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.



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

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.



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

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



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

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.



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

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: nil, where_document: nil, 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
54
55
 
# File 'lib/chroma/resources/collection.rb', line 37

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

  payload.delete_if { |_key, value| value.nil? }

  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.



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

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.



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

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