Documentation
¶
Overview ¶
Package chroma exposes Chroma through the Core vector-store capability interfaces. Documents are stored as records inside a Chroma collection (`{id, document, embedding, metadata}`); retrieval runs the collection's nearest-neighbor query. Documents containing media are rejected before indexing I/O because this adapter persists document text and metadata only.
Metadata numbers use the SDK's integer representation when possible. The store verifies the SDK's final JSON encoding and rejects numbers it would round, including scalar decimals below its encoding precision.
Requirements: a reachable Chroma server (self-hosted or Chroma Cloud). The store uses the official Go client over HTTP.
Vector similarity functions: cosine / L2 / inner-product. The chosen value is recorded in the collection metadata at creation time and cannot be changed without rebuilding the collection.
Filter visitor produces Chroma's flat where-clause syntax — `{"$and": [...]}`, `{"author": {"$eq": "Alice"}}`, `{"$contains": "..."}` for LIKE. The result feeds the `where` field on the query call. Metadata fields are addressed at the top level (no `metadata.` prefix); Chroma stores metadata flat.
Write and delete evidence. Chroma answers an upsert with a status alone, so a batch is either accepted whole or reported as an error — there is no per-item result to reconcile. A delete carrying neither ids nor a where clause selects the entire collection, so DeleteWhere refuses a filter that compiles to nothing rather than sending an unfiltered request.
Null tests are refused. Chroma's where clause offers $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $contains and $not_contains, none of which asks whether a key is present, so an IS NULL filter fails rather than being approximated.
Lifecycle. The store implements vectorstore.Closer because it creates a resource of its own: construction resolves the collection through GetCollection or GetOrCreateCollection, and Close releases that collection rather than the caller's client. The client stays the caller's to close.
Existing collection. The space is verified on both paths, because the create option does not settle it: GetOrCreateCollection returns an existing collection as it is and ignores the space asked for, so InitializeSchema guarantees the collection exists and never that it matches. Search converts Chroma's distance into a Score using the configured metric, so a collection built with l2 while the config says cosine returned scores that were wrong rather than absent. A mismatch now fails construction with ErrIncompatibleCollection; an omitted hnsw:space reads as Chroma's own default of l2.
See https://docs.trychroma.com/ for the full API surface.
Index ¶
- Constants
- Variables
- type DistanceMetric
- type Store
- func (s *Store) Close() error
- func (s *Store) DeleteIDs(ctx context.Context, ids []string) (err error)
- func (s *Store) DeleteWhere(ctx context.Context, expr filter.Predicate) (err error)
- func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
- func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
- type StoreConfig
Constants ¶
const Provider = "Chroma"
Provider is the stable backend name for host-side attribution.
Variables ¶
var ( ErrMissingClient = errors.New("chroma: Client is required") ErrIncompatibleCollection = errors.New("chroma: existing collection is incompatible") ErrMissingCollectionName = errors.New("chroma: CollectionName is required") ErrMissingEmbeddingModel = errors.New("chroma: EmbeddingModel is required") ErrMissingDocumentBatcher = errors.New("chroma: DocumentBatcher is required") )
Functions ¶
This section is empty.
Types ¶
type DistanceMetric ¶
type DistanceMetric string
DistanceMetric defines the distance function used by the HNSW index.
const ( // DistanceCosine uses cosine distance (1 - cosine_similarity). // Returned distances are in [0, 2]; lower means more similar. DistanceCosine DistanceMetric = "cosine" // DistanceL2 uses squared L2 (Euclidean) distance. // Returned distances are in [0, ∞); lower means more similar. DistanceL2 DistanceMetric = "l2" // DistanceIP uses inner product (dot product) distance. // Returned values are in (-∞, ∞); higher means more similar. DistanceIP DistanceMetric = "ip" )
func (DistanceMetric) String ¶
func (d DistanceMetric) String() string
func (DistanceMetric) Valid ¶
func (d DistanceMetric) Valid() bool
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a Chroma-backed implementation of vectorstore capability interfaces.
func NewStore ¶
func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
NewStore performs schema setup during construction, which is why it takes a context: a store returned before its collection exists would fail on the first index rather than at wiring, where the misconfiguration actually is.
func (*Store) DeleteIDs ¶
DeleteIDs removes documents from the collection by their Chroma IDs. An empty slice is a no-op; unknown ids are silently ignored. Implements vectorstore.IDDeleter.
func (*Store) DeleteWhere ¶
func (*Store) Index ¶
func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
Index embeds the documents and upserts them into Chroma.
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
Search embeds the query, searches Chroma, and returns matching documents.
type StoreConfig ¶
type StoreConfig struct {
// Client is the Chroma HTTP client.
// Required: must be provided, otherwise initialization will fail.
Client v2.Client
// CollectionName is the name of the Chroma collection to use.
// Required: must be a non-empty string.
CollectionName string
// InitializeSchema indicates whether to automatically create the collection
// if it does not exist. When true, GetOrCreateCollection is used; otherwise
// the collection must already exist.
// Optional: defaults to false.
InitializeSchema bool
// DistanceMetric is the HNSW distance function applied when the collection
// is created via InitializeSchema. Has no effect on an existing collection.
// Optional: defaults to DistanceCosine.
DistanceMetric DistanceMetric
// EmbeddingModel is the model used to generate vector embeddings from text.
// Required: must be provided.
EmbeddingModel embedding.Model
// DocumentBatcher is responsible for batching documents before insertion.
// Required: must be provided.
DocumentBatcher vectorstore.Batcher
}
StoreConfig contains configuration options for the Chroma vector store.
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files