Documentation
¶
Overview ¶
Package chroma adapts a Host-owned Chroma collection to vectorstore.Upserter, vectorstore.Querier and vectorstore.IDDeleter. It does not encode text, open collections, create schemas, install metadata or close the borrowed SDK handle.
The Host exclusively provisions an encoder pairing in collection metadata under SpaceMetadataKey and establishes the native dimension before handing the adapter a freshly resolved collection. Chroma reports dimension zero until the first vector is inserted. NewStore rejects an unbound width, a missing or mismatching space marker, or an unsupported native metric. Collection.Metadata, Dimension and Schema describe the SDK handle; they are not a live schema lock. No administrative changes are permitted behind the bound handle. Reopen after administrative changes. Equal dimensions alone do not make embedding spaces compatible.
A batch is fully validated and narrowed to finite float32 coordinates before its one native Upsert. An acknowledgment does not guarantee search visibility; a failed attempted RPC reports its IDs as unconfirmed without retrying. A document retains its original ID, text and exact metadata JSON in a single scope_metadata string. Native media storage is unsupported.
Query is native semantic ANN only. It never enumerates the source and never evaluates an opaque metadata predicate after truncating to top-K. A predicate returns vectorstore.ErrUnsupportedFilter before either Get or Query. Returned records, dimensions and native scores are fully validated before MinScore is applied. Native distances rank rows even when normalized Core scores tie.
Scan explicitly authorizes Get pagination with finite record, observed-byte and time budgets. It evaluates Core metadata semantics over every observed source record and returns no partial result if a limit, validation or transport error occurs. For a stable collection this enumerates all records; offset pagination is not transactionally consistent with concurrent writes. The Host must quiesce writers for repeatable membership. Chroma cannot atomically delete by an arbitrary Core predicate; Store intentionally does not implement vectorstore.FilterDeleter.
Index ¶
- Constants
- type Collection
- type Store
- func (s *Store) CheckDocuments(ctx context.Context, space vectorstore.SpaceID, docs []*document.Document) error
- func (s *Store) CheckQuery(ctx context.Context, space vectorstore.SpaceID, ...) error
- func (s *Store) DeleteIDs(ctx context.Context, ids []string) error
- func (s *Store) Query(ctx context.Context, request *vectorstore.Query) (response *vectorstore.SearchResponse, err error)
- func (s *Store) Scan(ctx context.Context, request vectorstore.ScanRequest) ([]*document.Document, error)
- func (s *Store) Upsert(ctx context.Context, batch *vectorstore.Batch) error
- type StoreConfig
Examples ¶
Constants ¶
const Provider = "Chroma"
const SpaceMetadataKey = "scope.vector_space"
SpaceMetadataKey identifies the Host-provisioned encoder pairing in the physical collection. The native dimension alone cannot establish this identity.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Collection ¶ added in v0.43.0
type Collection interface {
Schema() *v2.Schema
Metadata() v2.CollectionMetadata
Dimension() int
Upsert(context.Context, ...v2.AddOption) error
Get(context.Context, ...v2.GetOption) (v2.GetResult, error)
Query(context.Context, ...v2.QueryOption) (v2.QueryResult, error)
Delete(context.Context, ...v2.DeleteOption) error
}
Collection supplies native operations and the actual embedding schema. The host owns collection creation, index configuration and the SDK's lifecycle.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store borrows a single collection handle, pinned to a native metric, dimension and Host-provisioned encoder space. It owns no encoder or transport.
func NewStore ¶
func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
Example ¶
package main
import (
"context"
"time"
v2 "github.com/amikos-tech/chroma-go/pkg/api/v2"
"github.com/Tangerg/scope/core/document"
"github.com/Tangerg/scope/core/vectorstore"
"github.com/Tangerg/scope/vectorstores/chroma"
)
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
client, err := v2.NewHTTPClient(v2.WithBaseURL("http://localhost:8000"))
if err != nil {
panic(err)
}
defer client.Close()
// The host already set scope.vector_space and fixed the native dimension.
collection, err := client.GetCollection(ctx, "documents")
if err != nil {
panic(err)
}
defer collection.Close()
store, err := chroma.NewStore(ctx, chroma.StoreConfig{Collection: collection, Space: "example-v1"})
if err != nil {
panic(err)
}
if err = store.Upsert(ctx, &vectorstore.Batch{Space: "example-v1", Records: []vectorstore.Record{{Document: &document.Document{ID: "1", Text: "example"}, Values: []float64{1, 0}}}}); err != nil {
panic(err)
}
if _, err = store.Query(ctx, &vectorstore.Query{Space: "example-v1", Values: []float64{1, 0}}); err != nil {
panic(err)
}
}
Output:
func (*Store) CheckDocuments ¶ added in v0.59.0
func (*Store) CheckQuery ¶ added in v0.59.0
func (s *Store) CheckQuery(ctx context.Context, space vectorstore.SpaceID, options vectorstore.SearchOptions) error
func (*Store) Query ¶ added in v0.59.0
func (s *Store) Query(ctx context.Context, request *vectorstore.Query) (response *vectorstore.SearchResponse, err error)
func (*Store) Scan ¶ added in v0.59.0
func (s *Store) Scan(ctx context.Context, request vectorstore.ScanRequest) ([]*document.Document, error)
Scan returns the matching documents from observed pages, sorted by ID. Counted bytes are ID, document text, stored Core metadata JSON and four bytes per coordinate. The SDK has already materialized the current page: the byte budget is not a transport frame limit. Offset pagination is not a snapshot.
type StoreConfig ¶
type StoreConfig struct {
Collection Collection
Space vectorstore.SpaceID
}
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files