query

README

query

Query-time intelligence: parsing, rewriting, expansion, and adaptive retrieval strategies that run before search.

Parsing & filtering

• QueryParser / DefaultParser — parse a query into a ParsedQuery (intent, entities, filters); NewDefaultParser(g) uses the knowledge graph for entity resolution.
• Filter / TermFilter — convert parsed constraints into index.Filters.

Rewrite strategies (LLM-backed)

Strategy	Constructor	Effect
Rewriter	NewRewriter(backend)	cleans/clarifies the raw query
HyDE	NewHyDE(backend)	hypothetical document embeddings (retrieves against a generated answer)
StepBack	NewStepBack(backend)	abstract to the broader question first
SubQueryDecomposer	NewSubQueryDecomposer()	split a compound question into sub-queries
Multilingual	NewMultilingual(translator, targets...)	translate the query across languages (Translator, LLMTranslator, DetectLanguage)

Expansion & adaptive retrieval

• Expander / GraphExpander — expand a query with graph-derived related terms/entities.
• AdaptiveRetriever (NewAdaptiveRetriever(store, parser, expander)) — parses the query, picks a strategy, expands, and retrieves in one call.

Documentation

Overview

Package query provides advanced query processing capabilities including intent detection, entity extraction, and query expansion.

Index

• type AdaptiveRetriever
  • func NewAdaptiveRetriever(s store.Store, p QueryParser, e Expander) *AdaptiveRetriever
  • func (r *AdaptiveRetriever) Retrieve(ctx context.Context, query string, topK int) ([]index.SearchResult, error)
• type DefaultParser
  • func NewDefaultParser(g *graph.KnowledgeGraph) *DefaultParser
  • func (p *DefaultParser) Parse(ctx context.Context, query string) (*ParsedQuery, error)
• type ExpandedQuery
• type Expander
• type ExtractedEntity
• type ExtractedRelation
• type Filter
• type GraphExpander
  • func NewGraphExpander(g *graph.KnowledgeGraph) *GraphExpander
  • func (e *GraphExpander) Expand(ctx context.Context, parsed *ParsedQuery) (*ParsedQuery, error)
• type HyDE
  • func NewHyDE(b llm.Backend) *HyDE
  • func (h *HyDE) Generate(ctx context.Context, query string) (string, error)
• type Intent
  • func (i Intent) String() string
• type LLMTranslator
  • func (t *LLMTranslator) Translate(ctx context.Context, text string, target Language) (string, error)
• type Language
  • func DetectLanguage(text string) Language
  • func (l Language) Name() string
• type Multilingual
  • func NewMultilingual(tr Translator, targets ...Language) *Multilingual
  • func (m *Multilingual) Expand(ctx context.Context, query string) ([]ExpandedQuery, error)
• type ParsedQuery
• type QueryParser
• type Rewriter
  • func NewRewriter(b llm.Backend) *Rewriter
  • func (r *Rewriter) Rewrite(ctx context.Context, query string) (string, error)
• type StepBack
  • func NewStepBack(b llm.Backend) *StepBack
  • func (s *StepBack) Generate(ctx context.Context, query string) (string, error)
• type SubQueryDecomposer
  • func NewSubQueryDecomposer() *SubQueryDecomposer
  • func (d *SubQueryDecomposer) Decompose(ctx context.Context, query string) ([]string, error)
  • func (d *SubQueryDecomposer) WithBackend(b llm.Backend) *SubQueryDecomposer
• type TermFilter
  • func (f *TermFilter) Match(chunk *core.Chunk) bool
• type Translator

Types

type AdaptiveRetriever

type AdaptiveRetriever struct {
	// contains filtered or unexported fields
}

AdaptiveRetriever adjusts retrieval strategies based on query characteristics.

func NewAdaptiveRetriever

func NewAdaptiveRetriever(s store.Store, p QueryParser, e Expander) *AdaptiveRetriever

NewAdaptiveRetriever creates a new AdaptiveRetriever.

func (*AdaptiveRetriever) Retrieve

func (r *AdaptiveRetriever) Retrieve(ctx context.Context, query string, topK int) ([]index.SearchResult, error)

Retrieve performs adaptive retrieval based on query characteristics.

type DefaultParser

type DefaultParser struct {
	// Graph is an optional knowledge graph for entity disambiguation.
	Graph *graph.KnowledgeGraph

	// Stopwords are words to ignore during parsing.
	Stopwords map[string]bool

	// TemporalKeywords are words that indicate temporal queries.
	TemporalKeywords []string

	// CausalKeywords are words that indicate causal queries.
	CausalKeywords []string

	// ComparativeKeywords are words that indicate comparative queries.
	ComparativeKeywords []string

	// ProceduralKeywords are words that indicate procedural queries.
	ProceduralKeywords []string
}

DefaultParser is the default query parser with intent detection and entity extraction.

func NewDefaultParser

func NewDefaultParser(g *graph.KnowledgeGraph) *DefaultParser

NewDefaultParser creates a new DefaultParser with sensible defaults.

func (*DefaultParser) Parse

func (p *DefaultParser) Parse(ctx context.Context, query string) (*ParsedQuery, error)

Parse analyzes a query and returns a ParsedQuery.

type ExpandedQuery

type ExpandedQuery struct {
	// Language is the variant's language.
	Language Language

	// Text is the query in that language.
	Text string
}

ExpandedQuery is one language variant of a query used for multilingual (multi-query) retrieval.

type Expander

type Expander interface {
	// Expand takes a parsed query and returns an expanded version.
	Expand(ctx context.Context, parsed *ParsedQuery) (*ParsedQuery, error)
}

Expander defines the interface for expanding queries.

type ExtractedEntity

type ExtractedEntity struct {
	// Text is the original text span.
	Text string

	// Type is the entity type (person, location, organization, etc.).
	Type string

	// Confidence is the confidence score (0.0 to 1.0).
	Confidence float64
}

ExtractedEntity represents an entity extracted from a query.

type ExtractedRelation

type ExtractedRelation struct {
	// From is the source entity text.
	From string

	// To is the target entity text.
	To string

	// Type is the relation type.
	Type string

	// Confidence is the confidence score (0.0 to 1.0).
	Confidence float64
}

ExtractedRelation represents a relation extracted from a query.

type Filter

type Filter struct {
	// Key is the filter attribute name.
	Key string

	// Op is the comparison operator (eq, ne, gt, lt, gte, lte, in, contains).
	Op string

	// Value is the filter value.
	Value interface{}
}

Filter represents a structured filter for retrieval.

type GraphExpander

type GraphExpander struct {
	Graph *graph.KnowledgeGraph

	// Synonyms maps entity text to alternative representations.
	Synonyms map[string][]string

	// MaxExpansions limits the number of expansions per entity.
	MaxExpansions int
}

GraphExpander expands queries using knowledge graph relations and synonyms.

func NewGraphExpander

func NewGraphExpander(g *graph.KnowledgeGraph) *GraphExpander

NewGraphExpander creates a new GraphExpander.

func (*GraphExpander) Expand

func (e *GraphExpander) Expand(ctx context.Context, parsed *ParsedQuery) (*ParsedQuery, error)

Expand expands a parsed query using knowledge graph relations.

type HyDE

type HyDE struct {
	// Backend is the LLM that drafts the hypothetical document. Required.
	Backend llm.Backend

	// SystemPrompt overrides the default HyDE instructions.
	SystemPrompt string
}

HyDE implements Hypothetical Document Embeddings: instead of embedding the short (often ambiguous) query, an LLM drafts a plausible answer paragraph, and that paragraph is embedded for retrieval. Documents similar to the hypothetical answer tend to be the ones actually answering the question, which closes the query-document lexical gap.

func NewHyDE

func NewHyDE(b llm.Backend) *HyDE

NewHyDE creates a HyDE generator backed by the given LLM.

func (*HyDE) Generate

func (h *HyDE) Generate(ctx context.Context, query string) (string, error)

Generate returns a hypothetical answer document for the query. The caller embeds the returned text and searches with that embedding.

type Intent

type Intent string

Intent represents the type of query being asked.

const (
	IntentFactual     Intent = "factual"     // "What is X?"
	IntentComparative Intent = "comparative" // "How does X compare to Y?"
	IntentTemporal    Intent = "temporal"    // "What happened in 2020?"
	IntentCausal      Intent = "causal"      // "Why did X happen?"
	IntentProcedural  Intent = "procedural"  // "How do I do X?"
	IntentExistential Intent = "existential" // "Does X exist?"
	IntentUnknown     Intent = "unknown"
)

func (Intent) String

func (i Intent) String() string

String returns the string representation of the intent.

type LLMTranslator

type LLMTranslator struct {
	Backend llm.Backend
}

LLMTranslator implements Translator using an LLM backend.

func (*LLMTranslator) Translate

func (t *LLMTranslator) Translate(ctx context.Context, text string, target Language) (string, error)

Translate translates text into the target language via the LLM.

type Language

type Language string

Language identifies a supported query language.

const (
	LanguageEnglish  Language = "en"
	LanguageChinese  Language = "zh"
	LanguageJapanese Language = "ja"
	LanguageKorean   Language = "ko"
	LanguageRussian  Language = "ru"
	LanguageArabic   Language = "ar"
	LanguageHindi    Language = "hi"
	LanguageHebrew   Language = "he"
	LanguageGreek    Language = "el"
	LanguageThai     Language = "th"
	LanguageUnknown  Language = "unknown"
)

Supported languages. Unknown text maps to LanguageUnknown.

func DetectLanguage

func DetectLanguage(text string) Language

DetectLanguage makes a fast, dependency-free language guess from the dominant writing system of the text. Latin script maps to English (the default corpus language); callers wanting finer Latin-script distinction should use an LLM-backed detector.

func (Language) Name

func (l Language) Name() string

Name returns the display name for the language, used when building prompts.

type Multilingual

type Multilingual struct {
	// Translator renders the variants. Required.
	Translator Translator

	// TargetLanguages to expand into. The original language is always
	// included first even if listed here.
	TargetLanguages []Language
}

Multilingual expands a query into the target languages for multi-query retrieval: each variant is searched independently and the result lists are merged upstream (e.g. via fuse or union-top-k).

func NewMultilingual

func NewMultilingual(tr Translator, targets ...Language) *Multilingual

NewMultilingual creates a Multilingual expander with the given translator and target languages.

func (*Multilingual) Expand

func (m *Multilingual) Expand(ctx context.Context, query string) ([]ExpandedQuery, error)

Expand returns the query variants: the original (in its detected language) followed by one translation per target language, with duplicates (target == original language) dropped.

type ParsedQuery

type ParsedQuery struct {
	// Original is the raw query string.
	Original string

	// Intent is the detected query intent.
	Intent Intent

	// Entities are the extracted entities with confidence scores.
	Entities []ExtractedEntity

	// Relations are the extracted relations.
	Relations []ExtractedRelation

	// SubQueries are decomposed sub-queries for complex questions.
	SubQueries []string

	// Filters are structured filters to apply during retrieval.
	Filters []Filter

	// Confidence is the overall confidence in the parsing (0.0 to 1.0).
	Confidence float64
}

ParsedQuery represents a parsed and analyzed query.

type QueryParser

type QueryParser interface {
	// Parse analyzes a query and returns a ParsedQuery.
	Parse(ctx context.Context, query string) (*ParsedQuery, error)
}

QueryParser defines the interface for parsing and analyzing queries.

type Rewriter

type Rewriter struct {
	// Backend is the LLM used for rewriting. Required.
	Backend llm.Backend

	// SystemPrompt overrides the default rewriting instructions.
	SystemPrompt string
}

Rewriter performs LLM-powered query rewriting: it turns a raw user question into a retrieval-optimized query — expanded acronyms, removed filler, key terms made explicit — improving match rates against indexed content.

func NewRewriter

func NewRewriter(b llm.Backend) *Rewriter

NewRewriter creates a Rewriter backed by the given LLM.

func (*Rewriter) Rewrite

func (r *Rewriter) Rewrite(ctx context.Context, query string) (string, error)

Rewrite returns the retrieval-optimized form of the query.

type StepBack

type StepBack struct {
	// Backend is the LLM that derives the step-back question. Required.
	Backend llm.Backend

	// SystemPrompt overrides the default step-back instructions.
	SystemPrompt string
}

StepBack implements step-back prompting: the LLM first answers "what is the more general concept or question behind this query?", producing a higher-level query that retrieves the foundational context. Retrieval can then use both the step-back query and the original, which improves recall for questions that depend on background knowledge.

func NewStepBack

func NewStepBack(b llm.Backend) *StepBack

NewStepBack creates a StepBack generator backed by the given LLM.

func (*StepBack) Generate

func (s *StepBack) Generate(ctx context.Context, query string) (string, error)

Generate returns the step-back (more abstract) question for the query.

type SubQueryDecomposer

type SubQueryDecomposer struct {
	// Backend optionally decomposes via LLM. Nil = heuristic only.
	Backend llm.Backend

	// MaxSubQueries caps the number of sub-queries. Default 5.
	MaxSubQueries int
}

SubQueryDecomposer decomposes a complex question into independent sub-queries for retrieval. Heuristic decomposition (conjunctions, multiple question marks) is always available; when an LLM backend is configured it is tried first and the heuristic result is used as a fallback.

func NewSubQueryDecomposer

func NewSubQueryDecomposer() *SubQueryDecomposer

NewSubQueryDecomposer creates a heuristic-only decomposer.

func (*SubQueryDecomposer) Decompose

func (d *SubQueryDecomposer) Decompose(ctx context.Context, query string) ([]string, error)

Decompose returns the sub-queries for the input. The result is non-empty whenever the input is non-empty.

func (*SubQueryDecomposer) WithBackend

func (d *SubQueryDecomposer) WithBackend(b llm.Backend) *SubQueryDecomposer

WithBackend enables LLM-based decomposition with the given backend.

type TermFilter

type TermFilter struct {
	Key   string
	Op    string
	Value interface{}
}

TermFilter implements index.Filter for structured filter support.

func (*TermFilter) Match

func (f *TermFilter) Match(chunk *core.Chunk) bool

Match returns true if the chunk's metadata matches this filter.

type Translator

type Translator interface {
	// Translate returns text rendered into target.
	Translate(ctx context.Context, text string, target Language) (string, error)
}

Translator translates text into a target language.