Documentation
¶
Overview ¶
Package s3vectors stores precomputed vectors in an explicitly bound Amazon S3 vector index. Provision it using NonFilterableKeys(space). Key, dimensions, metric and coordinate-space schema are verified; an existing index without the exact marker must be rebuilt. The Host owns credentials and index lifecycle.
Query ranks native results without listing any records. The metadata payload preserves Core JSON exactly but is not searchable by equivalent native predicates. Use Scan only when the caller is authorized to read the entire index. Scan is bounded and complete on success but pagination is not a snapshot.
Writes preflight the complete batch, including float32 narrowing and native request limits, before the first put. A failed group reports acknowledgments, unconfirmed submissions and unattempted keys separately. A successful write does not imply immediate search visibility.
Index ¶
- Constants
- Variables
- func NonFilterableKeys(space vectorstore.SpaceID) []string
- 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, opts vectorstore.SearchOptions) 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
- type VectorClient
Examples ¶
Constants ¶
const ( Provider = "S3Vectors" MaxTopK = 10_000 MaxResultsPerQueryPage = 100 MaxVectorsPerWrite = 500 )
Variables ¶
var ErrIncompatibleIndex = errors.New("s3vectors: index is incompatible")
Functions ¶
func NonFilterableKeys ¶ added in v0.59.0
func NonFilterableKeys(space vectorstore.SpaceID) []string
NonFilterableKeys returns the exact immutable metadata schema to provision when creating an index in this space. The marker binds a table even while empty.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
func NewStore ¶
func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
Example ¶
package main
import (
"context"
"net/http"
"time"
awsconfig "github.com/aws/aws-sdk-go-v2/config"
awss3 "github.com/aws/aws-sdk-go-v2/service/s3vectors"
"github.com/Tangerg/scope/core/document"
"github.com/Tangerg/scope/core/vectorstore"
"github.com/Tangerg/scope/vectorstores/s3vectors"
)
func main() {
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
configuration, err := awsconfig.LoadDefaultConfig(ctx, awsconfig.WithRegion("us-east-1"))
if err != nil {
panic(err)
}
transport := http.DefaultTransport.(*http.Transport).Clone()
defer transport.CloseIdleConnections()
configuration.HTTPClient = &http.Client{Transport: transport, Timeout: 30 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
client := awss3.NewFromConfig(configuration)
const space vectorstore.SpaceID = "encoder-v1"
store, err := s3vectors.NewStore(ctx, s3vectors.StoreConfig{Client: client, VectorBucketName: "example-bucket", IndexName: "documents", Space: space})
if err != nil {
panic(err)
}
if err = store.Upsert(ctx, &vectorstore.Batch{Space: space, Records: []vectorstore.Record{{Document: &document.Document{ID: "one", Text: "example"}, Values: []float64{1, 0}}}}); err != nil {
panic(err)
}
if _, err = store.Query(ctx, &vectorstore.Query{Space: space, Values: []float64{1, 0}}); err != nil {
panic(err)
}
if err = store.DeleteIDs(ctx, []string{"one"}); err != nil {
panic(err)
}
}
Output:
func (*Store) CheckDocuments ¶ added in v0.59.0
func (s *Store) CheckDocuments(ctx context.Context, space vectorstore.SpaceID, docs []*document.Document) error
CheckDocuments verifies metadata budgets, media support and the physical index binding before a composition requests remote embeddings.
func (*Store) CheckQuery ¶ added in v0.59.0
func (s *Store) CheckQuery(ctx context.Context, space vectorstore.SpaceID, opts 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 evaluates predicate over pages the caller is authorized to enumerate. MaxBytes counts returned key, encoded metadata and float32 coordinates; service pagination provides no snapshot isolation. No partial result is returned.
type StoreConfig ¶
type StoreConfig struct {
Client VectorClient
VectorBucketName string
IndexName string
Space vectorstore.SpaceID
}
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
type VectorClient ¶ added in v0.16.0
type VectorClient interface {
GetIndex(context.Context, *awss3.GetIndexInput, ...func(*awss3.Options)) (*awss3.GetIndexOutput, error)
PutVectors(context.Context, *awss3.PutVectorsInput, ...func(*awss3.Options)) (*awss3.PutVectorsOutput, error)
QueryVectors(context.Context, *awss3.QueryVectorsInput, ...func(*awss3.Options)) (*awss3.QueryVectorsOutput, error)
ListVectors(context.Context, *awss3.ListVectorsInput, ...func(*awss3.Options)) (*awss3.ListVectorsOutput, error)
DeleteVectors(context.Context, *awss3.DeleteVectorsInput, ...func(*awss3.Options)) (*awss3.DeleteVectorsOutput, error)
}
Source Files