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

​
Import

To begin, import the collections namespace from the SDK:

​
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

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.

Was this page helpful?

Error HandlingConsole