index

type CacheType interface {
	Get(key []byte) (rval []byte, rerr error)
	Ts() uint64
	Find(prefix []byte, filter func(val []byte) bool) (uint64, error)
}

type IndexFactory[T c.Float] interface {
	// The Name returned represents the name of the factory rather than the
	// name of any particular index.
	Name() string

	// Fetch the string of all the options being used
	GetOptions(o opts.Options) string

	// Specifies the set of allowed options and a corresponding means to
	// parse a string version of those options.
	AllowedOptions() opts.AllowedOptions

	// Create is expected to create a VectorIndex, or generate an error
	// if the name already has a corresponding VectorIndex or other problems.
	// The name will be associated with with the generated VectorIndex
	// such that if we Create an index with the name "foo", then later
	// attempt to find the index with name "foo", it will refer to the
	// same object.
	// The set of vectors to use in the index process is defined by
	// source.
	Create(name string, o opts.Options, floatBits int) (VectorIndex[T], error)

	// Find is expected to retrieve the VectorIndex corresponding with the
	// name. If it attempts to find a name that does not exist, the VectorIndex
	// will return as a nil value. It should throw an error in persistent storage
	// issues when accessing information.
	Find(name string) (VectorIndex[T], error)

	// Remove is expected to delete the VectorIndex corresponding with the name.
	// If removing a name that doesn't exist, nothing will happen and no errors
	// are thrown. An error should only be thrown if there is issues accessing
	// persistent storage information.
	Remove(name string) error

	// CreateOrReplace will create a new index -- as defined by the Create
	// function -- if it does not yet exist, otherwise, it will replace any
	// index with the given name.
	CreateOrReplace(name string, o opts.Options, floatBits int) (VectorIndex[T], error)
}

type KeyValue struct {
	// Entity is the uid of the key to be built
	Entity uint64 `protobuf:"fixed64,1,opt,name=entity,proto3" json:"entity,omitempty"`
	// Attr is the attribute of the key to be built
	Attr string `protobuf:"bytes,2,opt,name=attr,proto3" json:"attr,omitempty"`
	// Value is the value corresponding to the key built from entity & attr
	Value []byte `protobuf:"bytes,3,opt,name=value,proto3" json:"value,omitempty"`
}

type LocalCache interface {
	// Get uses a []byte key to return the Value corresponding to the key
	Get(key []byte) (rval []byte, rerr error)
	// GetWithLockHeld uses a []byte key to return the Value corresponding to the key with a mutex lock held
	GetWithLockHeld(key []byte) (rval []byte, rerr error)
	Find(prefix []byte, filter func(val []byte) bool) (uint64, error)
}

type OptionalIndexSupport[T c.Float] interface {
	// SearchWithPath(ctx, c, query, maxResults, filter) is similar to
	// Search(ctx, c, query, maxResults, filter), but returns an extended
	// set of content in the search results.
	// The full contents returned are indicated by the SearchPathResult.
	// See the description there for more info.
	SearchWithPath(
		ctx context.Context,
		c CacheType,
		query []T,
		maxResults int,
		filter SearchFilter[T]) (*SearchPathResult, error)
}

type Posting_ValType int32

type SearchFilter[T c.Float] func(query, resultVal []T, resultUID uint64) bool

type SearchPathResult struct {
	// The collection of nearest-neighbors in sorted order after filtlering
	// out neighbors that fail any Filter criteria.
	Neighbors []uint64
	// The path from the start of search to the closest neighbor vector.
	Path []uint64
	// A collection of captured named counters that occurred for the
	// particular search.
	Metrics map[string]uint64
}

type Txn interface {
	// StartTs gets the exact time that the transaction started, returned in uint64 format
	StartTs() uint64
	// Get uses a []byte key to return the Value corresponding to the key
	Get(key []byte) (rval []byte, rerr error)
	// GetWithLockHeld uses a []byte key to return the Value corresponding to the key with a mutex lock held
	GetWithLockHeld(key []byte) (rval []byte, rerr error)
	Find(prefix []byte, filter func(val []byte) bool) (uint64, error)
	// Adds a mutation operation on a index.Txn interface, where the mutation
	// is represented in the form of an index.DirectedEdge
	AddMutation(ctx context.Context, key []byte, t *KeyValue) error
	// Same as AddMutation but with a mutex lock held
	AddMutationWithLockHeld(ctx context.Context, key []byte, t *KeyValue) error
	// mutex lock
	LockKey(key []byte)
	// mutex unlock
	UnlockKey(key []byte)
}

type TypeID Posting_ValType

type VectorIndex[T c.Float] interface {
	OptionalIndexSupport[T]

	MergeResults(ctx context.Context, c CacheType, list []uint64, query []T, maxResults int,
		filter SearchFilter[T]) ([]uint64, error)

	// Search will find the uids for a given set of vectors based on the
	// input query, limiting to the specified maximum number of results.
	// The filter parameter indicates that we might discard certain parameters
	// based on some input criteria. The maxResults count is counted *after*
	// being filtered. In other words, we only count those results that had not
	// been filtered out.
	Search(ctx context.Context, c CacheType, query []T,
		maxResults int,
		filter SearchFilter[T]) ([]uint64, error)

	// SearchWithUid will find the uids for a given set of vectors based on the
	// input queryUid, limiting to the specified maximum number of results.
	// The filter parameter indicates that we might discard certain parameters
	// based on some input criteria. The maxResults count is counted *after*
	// being filtered. In other words, we only count those results that had not
	// been filtered out.
	SearchWithUid(ctx context.Context, c CacheType, queryUid uint64,
		maxResults int,
		filter SearchFilter[T]) ([]uint64, error)

	// Insert will add a vector and uuid into the existing VectorIndex. If
	// uuid already exists, it should throw an error to not insert duplicate uuids
	Insert(ctx context.Context, c CacheType, uuid uint64, vec []T) ([]*KeyValue, error)

	BuildInsert(ctx context.Context, uuid uint64, vec []T) error
	AddSeedVector(vec []T)
	NumBuildPasses() int
	NumIndexPasses() int
	NumSeedVectors() int
	StartBuild(caches []CacheType)
	EndBuild() []int
	NumThreads() int
}

type VectorPartitionStrat[T c.Float] interface {
	FindIndexForSearch(vec []T) ([]int, error)
	FindIndexForInsert(vec []T) (int, error)
	NumPasses() int
	NumSeedVectors() int
	StartBuildPass()
	EndBuildPass()
	AddSeedVector(vec []T)
	AddVector(vec []T) error
}