Collections

Add storage and vector search capabilities to your functions.

The Modus Collection API allows you to add vector search within your functions.

Import

To begin, import the collections namespace from the SDK:

Go

import github.com/hypermodeinc/modus/sdk/go/pkg/collections

Collections APIs

The APIs in the collections namespace are below, organized by category.

We’re constantly introducing new APIs through ongoing development with early users. Open an issue if you have ideas on what would make Modus even more powerful for your next app!

Mutation Functions

upsert

Inserts or updates an item in a collection.

If the item already exists, the function overwrites the previous value. If not, it creates a new one.

collections.upsert(
  collection: string,
  key: string | null,
  text: string,
  labels: string[] = [],
  namespace: string = "",
): CollectionMutationResult

collection · string · required

Name of the collection, as defined in the manifest.

key · string

The unique identifier for the item in the namespace. If null, the function generates a unique identifier.

text · string · required

The text of the item to add to the collection.

labels · string[]

An optional array of labels to associate with the item.

namespace · string

Associates the item with a specific namespace. Defaults to an empty namespace if not provided.

upsertBatch

Inserts or updates a batch of items into a collection.

If an item with the same key already exists, the original text is overwritten with the new text.

collections.upsertBatch(
  collection: string,
  keys: string[] | null,
  texts: string[],
  labelsArr: string[][] = [],
  namespace: string = "",
): CollectionMutationResult

collection · string · required

Name of the collection, as defined in the manifest.

keys · string[]

Array of keys for the item to add to the collection. If you pass null for any key, Hypermode assigns a new UUID as the key for the item.

texts · string[] · required

Array of texts for the items to add to the collection.

labelsArr · string[][]

An optional array of arrays of labels to associate with the items.

namespace · string

Associates the item with a specific namespace. Defaults to an empty namespace if not provided.

remove

Removes an item from the collection.

collections.remove(
  collection: string,
  key: string,
  namespace: string = "",
): CollectionMutationResult

collection · string · required

Name of the collection, as defined in the manifest.

key · string · required

The key of the item to delete from the collection.

namespace · string

The namespace to remove the item from. Defaults to the default namespace if not provided.

Search and Retrieval Functions

search

Perform a natural language search on items within a collection. This method is useful for finding items that match a search query based on semantic meaning.

Modus uses the same embedder for both inserting text into the collection, and for the text used when searching the collection.

collections.search(
  collection: string,
  searchMethod: string,
  text: string,
  limit: i32,
  returnText: bool = false,
  namespaces: string[] = [],
): CollectionSearchResult

collection · string · required

Name of the collection, as defined in the manifest.

searchMethod · string · required

The search method used to calculate embedding for text & search against.

text · string · required

The text to compute natural language search on.

limit · i32 · required

The number of result objects to return.

returnText · bool

A flag to return the texts in the response.

namespaces · string[]

A list of namespaces to search the item from. Defaults to the default namespace if not provided.

searchByVector

Perform a vector-based search on a collection, which is helpful for scenarios requiring precise similarity calculations between pre-computed embeddings.

Modus uses the same embedder for both inserting text into the collection, and for the vector used when searching the collection.

collections.searchByVector(
  collection: string,
  searchMethod: string,
  vector: f64[],
  limit: i32,
  returnText: bool = false,
  namespaces: string[] = [],
): CollectionSearchResult

collection · string · required

Name of the collection, as defined in the manifest.

searchMethod · string · required

The search method used to calculate embedding for vector & search against.

vector · f64[] · required

The vector to compute search on.

limit · i32 · required

The number of result objects to return.

returnText · bool

A flag to return the texts in the response.

namespaces · string[]

An optional array of namespaces to search within.

nnClassify

Classify an item in the collection using previous vectors’ labels.

  collections.nnClassify(
  collection: string,
  searchMethod: string,
  text: string,
  namespace: string = "",
): CollectionClassificationResult

collection · string · required

Name of the collection, as defined in the manifest.

searchMethod · string · required

The search method used to calculate embedding for text & search against.

text · string · required

The text to compute natural language search on.

namespace · string

The namespace to search the items from. Defaults to the default namespace if not provided.

computeDistance

Computes distance between two keys in a collection using a search method’s embedder.

collections.computeDistance(
  collection: string,
  searchMethod: string,
  key1: string,
  key2: string,
  namespace: string = "",
): CollectionSearchResultObject

collection · string · required

Name of the collection, as defined in the manifest.

searchMethod · string · required

The search method used to calculate embedding for key’s texts.

key1, key2 · string · required

Keys to compute similarity on.

namespace · string

The namespace to search the items from. Defaults to the default namespace if not provided.

getText

Gets an item’s text from a collection, give the item’s key.

collections.getText(
  collection: string,
  key: string,
  namespace: string = "",
): string

collection · string · required

Name of the collection, as defined in the manifest.

key · string · required

The key of the item to retrieve.

namespace · string

The namespace to get the item from. Defaults to the default namespace if not provided.

getTexts

Get all items from a collection. The result is a map of key to text for all items in the collection.

collections.getTexts(
  collection: string,
  namespace: string = "",
): Map<string, string>

collection · string · required

Name of the collection, as defined in the manifest.

namespace · string

The namespace to get the items from. Defaults to the default namespace if not provided.

getNamespaces

Get all namespaces in a collection.

collections.getNamespaces(
  collection: string,
): string[]

collection · string · required

Name of the collection, as defined in the manifest.

getVector

Get the vector for an item in a collection.

collections.getVector(
  collection: string,
  searchMethod: string,
  key: string,
  namespace: string = "",
): f64[]

collection · string · required

Name of the collection, as defined in the manifest.

searchMethod · string · required

The search method used to calculate embedding for key’s texts.

key · string · required

The key of the item to retrieve.

namespace · string

The namespace to get the item from. Defaults to the default namespace if not provided.

getLabels

Get the labels for an item in a collection.

collections.getLabels(
  collection: string,
  key: string,
  namespace: string = "",
): string[]

collection · string · required

Name of the collection, as defined in the manifest.

key · string · required

The key of the item to retrieve.

namespace · string

The namespace to get the item from. Defaults to the default namespace if not provided.

Maintenance Functions

recomputeSearchMethod

Recalculates the embeddings for all items in a collection. It can be resource-intensive, use it when necessary, for example after you have updated the method for embedding calculation and want to re-compute the embeddings for existing data in the collection.

collections.recomputeSearchMethod(
  collection: string,
  searchMethod: string,
  namespace: string = "",
): collections.SearchMethodMutationResult

collection · string · required

Name of the collection, as defined in the manifest.

searchMethod · string · required

The search method to recompute embeddings for.

namespace · string

The namespace to use. Defaults to the default namespace if not provided.

Objects

CollectionMutationResult

class CollectionMutationResult {
  collection: string;
  status: CollectionStatus;
  error: string;
  isSuccessful: bool;
  operation: string;
  keys: string[];
}

Represents the result of a mutation operation on a collection.

collection · string

Name of the collection.

status · CollectionStatus

The status of the operation.

error · string

Error message, if any.

isSuccessful · bool

A boolean indicating whether the operation completed successfully. Use this to confirm success before handling the result.

operation · string

The operation performed.

keys · string[]

The keys of the items affected by the operation.

CollectionSearchResult

class CollectionSearchResult {
  collection: string;
  status: CollectionStatus;
  error: string;
  isSuccessful: bool;
  searchMethod: string;
  objects: CollectionSearchResultObject[];
}

Represents the result of a search operation on a collection.

collection · string

Name of the collection.

status · CollectionStatus

The status of the operation.

error · string

Error message, if any.

isSuccessful · bool

A boolean indicating whether the operation completed successfully. Use this to confirm success before handling the result.

searchMethod · string

The search method used in the operation.

objects · CollectionSearchResultObject[]

The search results.

CollectionSearchResultObject

class CollectionSearchResultObject {
  namespace: string;
  key: string;
  text: string;
  labels: string[];
  distance: f64;
  score: f64;
}

Represents an object in the search results.

namespace · string

The namespace of the item found as part of the search.

key · string

The key of the item found as part of the search.

text · string

The text of the item found as part of the search.

distance · f64

The distance of the item from the search text.

score · f64

The similarity score of the item found, as it pertains to the search.

CollectionClassificationResult

class CollectionClassificationResult {
  collection: string;
  status: CollectionStatus;
  error: string;
  isSuccessful: bool;
  searchMethod: string;
  labelsResult: CollectionClassificationLabelObject[];
  cluster: CollectionClassificationResultObject[];
}

Represents the result of a classification operation on a collection.

collection · string

Name of the collection.

status · CollectionStatus

The status of the operation.

error · string

Error message, if any.

isSuccessful · bool

A boolean indicating whether the operation completed successfully. Use this to confirm success before handling the result.

searchMethod · string

The search method used in the operation.

labelsResult · CollectionClassificationLabelObject[]

The classification labels.

cluster · CollectionClassificationResultObject[]

The classification results.

CollectionClassificationLabelObject

class CollectionClassificationLabelObject {
  label: string;
  confidence: f64;
}

Represents a classification label.

label · string

The classification label.

confidence · f64

The confidence score of the classification label.

CollectionClassificationResultObject

class CollectionClassificationResultObject {
  key: string;
  labels: string[];
  distance: f64;
  score: f64;
}

Represents an object in the classification results.

key · string

The key of the item classified.

labels · string[]

The classification labels.

distance · f64

The distance of the item from the classification labels.

score · f64

The similarity score of the item classified.

CollectionStatus

enum CollectionStatus {
  Success = "success";
  Error = "error";
}

The status of a collection operation.

Success · string

The operation was successful.

Error · string

The operation encountered an error.

SearchMethodMutationResult

class SearchMethodMutationResult {
  collection: string;
  status: CollectionStatus;
  error: string;
  isSuccessful: bool;
  operation: string;
  searchMethod: string;
}

Represents the result of a mutation operation on a search method.

collection · string

Name of the collection.

status · CollectionStatus

The status of the operation.

error · string

Error message, if any.

isSuccessful · bool

A boolean indicating whether the operation completed successfully. Use this to confirm success before handling the result.

operation · string

The operation performed.

searchMethod · string

The search method affected by the operation.