The Modus Collection API allows you to add vector search within your functions.
Import
To begin, import the collections
namespace from the SDK:
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
The unique identifier for the item in the namespace. If null, the function
generates a unique identifier.
The text of the item to add to the collection.
An optional array of labels to associate with the item.
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
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.
Array of texts for the items to add to the collection.
An optional array of arrays of labels to associate with the items.
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
The key of the item to delete from the collection.
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
The search method used to calculate embedding for text & search against.
The text to compute natural language search on.
The number of result objects to return.
A flag to return the texts in the response.
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
The search method used to calculate embedding for vector & search against.
The vector to compute search on.
The number of result objects to return.
A flag to return the texts in the response.
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
The search method used to calculate embedding for text & search against.
The text to compute natural language search on.
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
The search method used to calculate embedding for key’s texts.
Keys to compute similarity on.
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
The key of the item to retrieve.
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>
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[]
getVector
Get the vector for an item in a collection.
collections.getVector(
collection: string,
searchMethod: string,
key: string,
namespace: string = "",
): f64[]
The search method used to calculate embedding for key’s texts.
The key of the item to retrieve.
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[]
The key of the item to retrieve.
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
The search method to recompute embeddings for.
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.
The status of the operation.
A boolean indicating whether the operation completed successfully. Use this to
confirm success before handling the result.
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.
The status of the operation.
A boolean indicating whether the operation completed successfully. Use this to
confirm success before handling the result.
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.
The namespace of the item found as part of the search.
The key of the item found as part of the search.
The text of the item found as part of the search.
The distance of the item from the search text.
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.
The status of the operation.
A boolean indicating whether the operation completed successfully. Use this to
confirm success before handling the result.
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.
The classification label.
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.
The key of the item classified.
The classification labels.
The distance of the item from the classification labels.
The similarity score of the item classified.
CollectionStatus
enum CollectionStatus {
Success = "success";
Error = "error";
}
The status of a collection operation.
The operation was successful.
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.
The status of the operation.
A boolean indicating whether the operation completed successfully. Use this to
confirm success before handling the result.
The search method affected by the operation.