Collections
Add basic storage and search capabilities to your functions.
Hypermode Collections provide a built-in key-value storage mechanism that supports vector embeddings, that you can use from your functions. After defining collections in your project’s manifest, you can use the following APIs to interact with the data.
Example project
For your reference, A complete example for using the Collections APIs is available on GitHub in the
hypermodeinc/functions-as repository, at /examples/collection.
Import from the SDK
To begin, import the collections namespace from the SDK:
Collections APIs
The APIs in the collections namespace are below, organized by category.
New APIs are constantly introduced through ongoing development with build partners. Please contact us at [email protected] about what would make the Functions SDK even more powerful for your next use case.
Mutation Functions
upsert
Inserts or updates an item into a collection.
If an item with the same key already exists, the original text is overwritten with the new text.
collections.upsert(
collection: string,
key: string | null,
text: string,
labels: string[] = [],
namespace: string = "",
): CollectionMutationResult
Name of the collection, as defined in the manifest.
An optional key for the item. If null, Hypermode assigns a new UUID as the
key for the item.
The text of the item to add to the collection.
An optional array of labels to associate with the item.
An optional namespace to associate with the item.
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
Name of the collection, as defined in the manifest.
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.
An optional namespace to associate with the items.
remove
Removes an item from the collection.
collections.remove(
collection: string,
key: string,
namespace: string = "",
): CollectionMutationResult
Name of the collection, as defined in the manifest.
The key of the item to delete from the collection.
An optional namespace to associate with the item.
Search and Retrieval Functions
search
Search for an item in the collection by using natural language search.
Hypermode 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
Name of the collection, as defined in the manifest.
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.
An optional array of namespaces to search within.
searchByVector
Search for an item in the collection by using a vector.
Hypermode 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
Name of the collection, as defined in the manifest.
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
Name of the collection, as defined in the manifest.
The search method used to calculate embedding for text & search against.
The text to compute natural language search on.
An optional namespace to associate with the item.
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
Name of the collection, as defined in the manifest.
The search method used to calculate embedding for key’s texts.
Keys to compute similarity on.
An optional namespace to associate with the item.
getText
Gets an item’s text from a collection, give the item’s key.
collections.getText(
collection: string,
key: string,
namespace: string = "",
): string
Name of the collection, as defined in the manifest.
The key of the item to retrieve.
An optional namespace to associate with the item.
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>
Name of the collection, as defined in the manifest.
An optional namespace to associate with the item.
getNamespaces
Get all namespaces in a collection.
collections.getNamespaces(
collection: string,
): string[]
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[]
Name of the collection, as defined in the manifest.
The search method used to calculate embedding for key’s texts.
The key of the item to retrieve.
An optional namespace to associate with the item.
getLabels
Get the labels for an item in a collection.
collections.getLabels(
collection: string,
key: string,
namespace: string = "",
): string[]
Name of the collection, as defined in the manifest.
The key of the item to retrieve.
An optional namespace to associate with the item.
Maintenance Functions
recomputeSearchMethod
Recomputes the embeddings for all texts in a collection, for a specific search method.
collections.recomputeSearchMethod(
collection: string,
searchMethod: string,
namespace: string = "",
): collections.SearchMethodMutationResult
Name of the collection, as defined in the manifest.
The search method to recompute embeddings for.
An optional namespace to associate with the item.
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.
Name of the collection.
The status of the operation.
Error message, if any.
Whether the operation was successful.
The operation performed.
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.
Name of the collection.
The status of the operation.
Error message, if any.
Whether the operation was successful.
The search method used in the operation.
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.
Name of the collection.
The status of the operation.
Error message, if any.
Whether the operation was successful.
The search method used in the operation.
The classification labels.
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.
Name of the collection.
The status of the operation.
Error message, if any.
Whether the operation was successful.
The operation performed.
The search method affected by the operation.