Collections APIs

While each Modus SDK offers similar capabilities, the APIs and usage may vary between languages.

Modus Collections APIs documentation is available on the following pages:

AssemblyScript Collections APIs
Go Collections APIs (this page)

The Modus Collection APIs allow you to add vector search within your functions.

Import

To begin, import the collections package from the SDK:

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

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

We’re constantly introducing new APIs through ongoing development with early users. Please 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.

func Upsert(
  collection string,
  key *string,
  text string,
  labels []string,
  opts ...NamespaceOption
) (*CollectionMutationResult, error)

collection

string

required

Name of the collection, as defined in the manifest.

key

*string

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

text

string

required

The text of the item to add to the collection.

labels

[]string

An optional slice of labels to associate with the item.

opts

...NamespaceOption

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

Pass collections.WithNamespace("namespace") to specify a namespace.

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.

func UpsertBatch(
  collection string,
  keys []string,
  texts []string,
  labelsArr [][]string,
  opts ...NamespaceOption
) (*CollectionMutationResult, error)

collection

string

required

Name of the collection, as defined in the manifest.

keys

[]string

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

texts

[]string

required

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

labelsArr

[][]string

An optional slice of slices of labels to associate with the items.

opts

...NamespaceOption

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

Pass collections.WithNamespace("namespace") to specify a namespace.

Remove

Removes an item from the collection.

func Remove(
  collection string,
  key string,
  opts ...NamespaceOption
) (*CollectionMutationResult, error)

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.

opts

...NamespaceOption

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

Pass collections.WithNamespace("namespace") to specify a namespace.

Search and Retrieval Functions

ComputeDistance

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

func ComputeDistance(
  collection string,
  searchMethod string,
  key1 string,
  key2 string,
  opts ...NamespaceOption
) (*CollectionSearchResultObject, error)

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.

opts

...NamespaceOption

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

Pass collections.WithNamespace("namespace") to specify a namespace.

NnClassify

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

func NnClassify(
  collection string,
  searchMethod string,
  text string,
  opts ...NamespaceOption
) (*CollectionClassificationResult, error)

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.

opts

...NamespaceOption

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

Pass collections.WithNamespace("namespace") to specify a namespace.

GetLabels

Get the labels for an item in a collection.

func GetLabels(
  collection string,
  key string,
  opts ...NamespaceOption
) ([]string, error)

collection

string

required

Name of the collection, as defined in the manifest.

key

string

required

The key of the item to retrieve.

opts

...NamespaceOption

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

Pass collections.WithNamespace("namespace") to specify a namespace.

GetNamespaces

Get all namespaces in a collection.

func GetNamespaces(collection string) ([]string, error)

collection

string

required

Name of the collection, as defined in the manifest.

GetText

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

func GetText(
  collection string,
  key string,
  opts ...NamespaceOption
) (string, error)

collection

string

required

Name of the collection, as defined in the manifest.

key

string

required

The key of the item to retrieve.

opts

...NamespaceOption

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

Pass collections.WithNamespace("namespace") to specify a namespace.

GetTexts

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

func GetTexts(
  collection string,
  opts ...NamespaceOption
) (map[string]string, error)

collection

string

required

Name of the collection, as defined in the manifest.

opts

...NamespaceOption

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

Pass collections.WithNamespace("namespace") to specify a namespace.

GetVector

Get the vector for an item in a collection.

func GetVector(
  collection string,
  searchMethod string,
  key string,
  opts ...NamespaceOption
) ([]float32, error)

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.

opts

...NamespaceOption

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

Pass collections.WithNamespace("namespace") to specify a namespace.

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.

func Search(
  collection string,
  searchMethod string,
  text string,
  opts ...SearchOption
) (*CollectionSearchResult, error)

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.

opts

...SearchOption

Additional options for the search:

collections.WithLimit(limit int): The number of result objects to return.
collections.WithReturnText(returnText bool): A flag to return the texts in the response.
collections.WithNamespaces(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.

func SearchByVector(
  collection string,
  searchMethod string,
  vector []float32,
  opts ...SearchOption
) (*CollectionSearchResult, error)

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

[]float32

required

The vector to compute search on.

opts

...SearchOption

Additional options for the search:

collections.WithLimit(limit int): The number of result objects to return.
collections.WithReturnText(returnText bool): A flag to return the texts in the response.
collections.WithNamespaces(namespaces []string): A list of namespaces to search 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.

func RecomputeSearchMethod(
  collection string,
  searchMethod string,
  opts ...NamespaceOption
) (*SearchMethodMutationResult, error)

collection

string

required

Name of the collection, as defined in the manifest.

searchMethod

string

required

The search method to recompute embeddings for.

opts

...NamespaceOption

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

Pass collections.WithNamespace("namespace") to specify a namespace.

Types

CollectionClassificationLabelObject

Represents a classification label.

type CollectionClassificationLabelObject struct {
  Label string
  Confidence float64
}

Label

string

The classification label.

Confidence

float64

The confidence score of the classification label.

CollectionClassificationResult

Represents the result of a classification operation on a collection.

type CollectionClassificationResult struct {
  Collection string
  Status string
  Error string
  SearchMethod string
  LabelsResult []*CollectionClassificationLabelObject
  Cluster []*CollectionClassificationResultObject
}

Collection

string

Name of the collection.

Status

string

The status of the operation.

Error

string

Error message, if any.

SearchMethod

string

The search method used in the operation.

LabelsResult

[]*CollectionClassificationLabelObject

The classification labels.

Cluster

[]*CollectionClassificationResultObject

The classification results.

CollectionClassificationResultObject

Represents an object in the classification results.

type CollectionClassificationResultObject struct {
  Key string
  Labels []string
  Distance float64
  Score float64
}

Key

string

The key of the item classified.

Labels

[]string

The classification labels.

Distance

float64

The distance of the item from the classification labels.

Score

float64

The similarity score of the item classified.

CollectionMutationResult

Represents the result of a mutation operation on a collection.

type CollectionMutationResult struct {
  Collection string
  Status string
  Error string
  Operation string
  Keys []string
}

Collection

string

Name of the collection.

Status

string

The status of the operation.

Error

string

Error message, if any.

Operation

string

The operation performed.

Keys

[]string

The keys of the items affected by the operation.

CollectionSearchResult

Represents the result of a search operation on a collection.

type CollectionSearchResult struct {
  Collection string
  Status string
  Error string
  SearchMethod string
  Objects []*CollectionSearchResultObject
}

Collection

string

Name of the collection.

Status

string

The status of the operation.

Error

string

Error message, if any.

SearchMethod

string

The search method used in the operation.

Objects

[]*CollectionSearchResultObject

The search results.

CollectionSearchResultObject

Represents an object in the search results.

type CollectionSearchResultObject struct {
  Namespace string
  Key string
  Text string
  Labels []string
  Distance float64
  Score float64
}

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

float64

The distance of the item from the search text.

Score

float64

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

CollectionStatus

The status of a collection operation.

type CollectionStatus = string

const (
  Success CollectionStatus = "success"
  Error   CollectionStatus = "error"
)

Success

The operation was successful.

Error

The operation encountered an error.

SearchMethodMutationResult

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

type SearchMethodMutationResult struct {
  Collection string
  Status string
  Error string
  Operation string
  SearchMethod string
}

Collection

string

Name of the collection.

Status

string

The status of the operation.

Error

string

Error message, if any.

Operation

string

The operation performed.

SearchMethod

string

The search method affected by the operation.

Getting Started

Building Your App

How-To Guides

SDK Reference

Tools

Resources

Collections APIs

Import