Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DistancerContainer ¶
type DistancerContainer struct {
D mathx.Distancer
// TODO: Check performance. As of now, each call to Distancer() method does
// a time.Now() call; the alternative is to have a bool in addition, as that
// is cheaper. But that would also require a sync.RWMutes due to how this
// will be used concurrently in the knnc pkg.
Expires time.Time
}
DistancerContainer implements knnc.DistancerContainer.
func (*DistancerContainer) Distancer ¶
func (d *DistancerContainer) Distancer() mathx.Distancer
Distancer returns the internal mathx.Distancer if the Expiration field is set and after time.Now().
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle is the main way of interacting with this pkg. It handles data storage, KNN requests, info retrieval, etc.
func NewHandle ¶
func NewHandle(args NewHandleArgs) (*Handle, bool)
NewHandleArgs attempts to set up a new Handle. Returns (nil, false) if args.Ok returns false. For more details, see doc for T Handle and T NewHandleArgs.
func (*Handle) AddData ¶
func (h *Handle) AddData(ns string, d DistancerContainer, data []byte) bool
AddData adds data to a namespace, using a DistancerContainer(.Distancer()) as an index. A new namespace will be created if one does not already exist. Returns false on either of the following conditions:
- ctx used when creating the Handle (NewHandle(...)) signalled done.
- DistancerContainer.D == nil.
- the knnc.SearchSpaces instance used for this namespace returns false on the method AddSearchable(d).
TODO: currently, only the Distancer is stored, as any other means of persisting data is not yet implemented.
func (*Handle) Info ¶
func (h *Handle) Info() *info
Info is used as namespacing for methods related to metadata / general info. Single-use is encouraged to prevent leaks, as the returned "info" instance contains a ptr to the Handle instance. So call h.Info().Xyz() directly, instead of something like "x := h.Info()".
func (*Handle) KNN ¶
func (h *Handle) KNN(args KNNArgs) (KNNEnqueueResult, bool)
KNN attempts to enqueue a KNN request, see docs for KNNEnqueueResult for more details. Returns a false bool on the following conditions: - args.Ok() == false - ctx used when creating the Handle (NewHandle(...)) signalled done. - args.Namespace is unknown / not yet created with Handle.AddData(...). - args.TTL is lower than the estimated queue+query time.
type KNNArgs ¶
type KNNArgs struct {
// Namespace is used to group search spaces together, based on logical
// meaning, but also for having uniform vector dimensions.
Namespace string
// Priority specifies how important a KNN query is -- higher is better.
// It influences the number of goroutines used, though not necessarily
// a one-to-one mapping. Must be > 0.
Priority int
// QueryVec is used for similarity searching. Must not be nil, with a
// length of > 0. Also, make sure the dimension is appropriate for the
// KNNArgs.namespace field.
QueryVec []float64
// KNNMethod specifies the distance function used for the query.
// KNNMethod.Ok() must return true.
KNNMethod KNNMethod
// Ascending plays a role with ordering _and_ the meaning is dependent
// somewhat on the KNNArgs.KNNMethod field.
//
// Euclidean distance, for instance, works on the principle that lower
// is better, so then it would make sense to have Ascending=true for
// KNN. For K-furthest-neighs, Ascending=false has to be used, as that
// would reverse the order. The exact opposite is true for Cosine simi.
Ascending bool
// K is the K in KNN. However, the actual result might be less than this
// number, for multiple reasons. One of them is that there simply might
// not be enough data to search. Another reason is that the underlying
// knn pkg uses a few optimization tricks to trade accuracy for speed,
// the reamainding fields below give more documentation.
K int
// Extent specifies the extent of a search, in a range (0, 1]. For
// example, 0.5 will search half the search space. This is used to
// trade accuracy for speed.
Extent float64
// Accept is another optimization trick; the search will be aborted
// when there are KNNArgs.K results with better than KNNArgs.Accept
// accuracy.
Accept float64
// Reject is another optimization trick; the knn search pipeline will
// drop all values worse than this fairly early on, such that the
// load on downstream processes/pipes gets alleviated. Do note that
// this is evaluated before KNNArgs.Accept, so Accept can be cancelled
// out by Reject.
Reject float64
// TTL specifies the deadline for a knn request. The pipeline will
// start shutting down for this request after the deadline, but it
// is a good idea to cancel it manually. After this duration, the
// best-found results are given. Must be > 0.
TTL time.Duration
// Monitor true will register the KNN request (and results).
Monitor bool
}
KNNArgs are used as arguments for making KNN requests. Check if all the requirements are met with calling KNNArgs.Ok().
type KNNEnqueueResult ¶
type KNNEnqueueResult struct {
// Pipe is the destination of a KNN request/query.
Pipe chan knnc.ScoreItems
// Cancel can be used to cancel a request. This is done automatically
// with KNNArgs.TTL when making a query, but the cancel func should
// be called nontheless.
Cancel context.CancelFunc
}
KNNEnqueueResult is used to receive the results of a KNN request/query.
type KNNMonItemAvg ¶
type KNNMonItemAvg struct {
Created time.Time // Start of recording.
Span time.Duration // Recording duration.
N int // Number of recorded requests (including fails).
NFailed int // Number of (completely) failed requests.
AvgLatency time.Duration // Average latency of all requests.
AvgScore float64 // Average score for all requests.
AvgScoreNoFails float64 // Same as AvgScore but without fails.
AvgSatisfaction float64 // Success ratio (got n / want n).
// contains filtered or unexported fields
}
KNNMonItemAvg captures stats for a group of KNN requests over a period.
type NewHandleArgs ¶
type NewHandleArgs struct {
// NewSearchSpaceArgs keeps instructions for how to create new search spaces.
// This is done 'occasionally' on Handle.AddData(...). For more details, see
// documentation for the knnc pkg (particularly for T SearchSpaces).
NewSearchSpaceArgs knnc.NewSearchSpacesArgs
// NewLatencyTrackerArgs keeps instructions for how to create new latency
// trackers. This is used for the KNN request queue in T Handle, as well as
// for each new namespaced (KNN) search space.
NewLatencyTrackerArgs timex.EventTrackerConfig
// KNNQueueBuf specifies the buffer for the KNN request queue in T Handle.
KNNQueueBuf int
// KNNQueueMaxConcurrent specifies the max number of _parent_ goroutines
// available for the KNN request queue in T Handle. In other words, it
// specifies how many KNN requests can be processed concurrently -- though
// each KNN request can use multiple goroutines individually.
KNNQueueMaxConcurrent int
// Ctx is used to stop the KNN request queue. It will also be used to stop
// the maintanence loop for each namespaced (KNN) search space (for more
// info about this, see docs for T SearchSpaces of pkg/knnc).
Ctx context.Context
// NewKNNMonitorArgs keeps instructions for how to make a new monitor.
// This includes same args as timex.NewLatencyArgs, as the internal
// data structure works the same way.
NewKNNMonitorArgs timex.EventTrackerConfig
}
NewHandleArgs is intended as args for func NewHandle.
func (*NewHandleArgs) Ok ¶
func (args *NewHandleArgs) Ok() bool
Ok returns true if the configuration kn NewHandleArgs is acceptable. Specifically: - NewHandleArgs.NewSearchSpaceArgs.Ok() == true - NewHandleArgs.NewLatencyTrackerArgs.Ok() == true - NewHandleArgs.KNNQueueBuf >= 0 - NewHandleArgs.KNNQueueMaxConcurrent > 0 - NewHandleArgs.Ctx != nil - NewKNNMonitorArgs.Ok == true
Source Files