search

type Candidate struct {
	contentref.ContentRef
	Language string
	Score    float32
}

type DirtyMark struct {
	DocumentKey
	Deleted bool
	Reason  string
}

type DocumentKey struct {
	contentref.ContentRef
	Language string
}

type Eligibility struct {
	SQL  string
	Args map[string]any
}

type Executor interface {
	Exec(context.Context, string, ...any) (pgconn.CommandTag, error)
}

type Hit struct {
	contentref.ContentRef
	Language string
	// Priority orders same-item documents at equal match; lower is preferred.
	Priority int32
	Score    float32
}

type KeywordDocument struct {
	DocumentKey
	Title    string
	Aliases  []string
	Keywords []string
}

type Options struct {
	Schema   string
	Tenant   string
	Language string
	// ContentKinds limits the kinds searched; empty means every kind.
	ContentKinds []string
	Limit        int

	// Eligibility binds pgx '@name' placeholders other than the reserved
	// tenant, language, q, prefix, limit, kinds and candidates.
	Eligibility *Eligibility
}

type RRFContribution struct {
	ListIndex    int     `json:"list_index"` // zero-based source-list index
	Rank         int     `json:"rank"`       // one-based rank within the source list
	Weight       float32 `json:"weight"`
	Contribution float32 `json:"contribution"`
}

type RRFHit struct {
	RRFKey
	Score float32
}

type RRFKey struct {
	contentref.ContentKey
	Language string
}

type RRFOptions struct {
	// K is the stabilizer constant; higher K flattens rank differences.
	// Defaults to 60 when <= 0.
	K int
	// Finite weights apply to each list; missing weights default to 1.
	// Zero excludes a list. Negative weights subtract its contributions.
	Weights []float32
}

type RRFTraceHit struct {
	Hit           RRFHit            `json:"-"`
	Key           RRFTraceKey       `json:"key"`
	Score         float32           `json:"score"`
	Contributions []RRFContribution `json:"contributions"`
}

type RRFTraceKey struct {
	TenantID         string `json:"tenant_id"`
	ContentKind      string `json:"content_kind"`
	ContentID        string `json:"content_id"`
	ContentVersionID string `json:"content_version_id,omitempty"`
	Language         string `json:"language"`
}

type Result struct {
	// Hits are documents ordered by score, content kind, content id and version.
	Hits []Hit
	// Truncated reports that a route filled its SQL window or that more scored
	// documents existed than Limit: documents beyond the window were never ranked.
	Truncated bool
}