query

Documentation

Overview

Package query is the heuristic English-to-types.Request parser used by the pulse.Ask facade and the `pulse api ask` CLI leaf.

The parser accepts a constrained natural-language string ("average revenue by region", "count sessions over time month") together with a .pulse schema, and emits a *types.Request whose Field slots resolve against schema columns via direct or Levenshtein-near match. Operator Type is filled where the verb is unambiguous; otherwise it is left empty so descriptor.ResolveDefaults can infer it from the field's schema type (the smart-defaults safety net).

Structural ban: this package imports only types/, encoding/, and errors/. It MUST NOT import service/, processing/, or descriptor/ — the facade resolves the request, predict validates it, the runtime executes it. The parser stays inert. The Levenshtein helper is duplicated here (see descriptor.predict_suggestions.levenshtein) so the dependency graph stays minimal.

Index

• type Issue
• type ParseOptions
• type Result
  • func Parse(query string, schema *encoding.Schema, opts ParseOptions) *Result

Types

type Issue

type Issue struct {
	Code    errors.Code
	Message string
	Details map[string]any
}

Issue mirrors descriptor.EnvelopeEntry minus the json package dependency. The caller converts each issue into an envelope entry.

type ParseOptions

type ParseOptions struct {
	// File is the cohort filename to attach to the synthesized
	// Request.Cohort. When empty the request carries no cohort and the
	// caller is expected to set one.
	File string
}

ParseOptions modulates parse behavior.

type Result

type Result struct {
	// Request is the synthesized request. Cohort is filled when the
	// caller passes a non-empty File argument to Parse. Slots whose
	// Type the parser could not pin down are left empty so the smart-
	// defaults pass (descriptor.ResolveDefaults) can fill them at
	// validation time.
	Request *types.Request

	// MatchedFields lists every schema field name the parser
	// successfully resolved against. Order: appearance in the request
	// (aggregation, then groups, then filters, then windows).
	MatchedFields []string

	// Confidence is the aggregate parser confidence in [0, 1].
	Confidence float64

	// Issues are warnings or errors emitted during parsing. The
	// envelope-level errors and warnings lists are derived from this
	// slice by the caller (service.Ask).
	Issues []Issue
}

Result is the parser output. Request is always non-nil; when the input is unparseable the request is a stub with the supplied cohort and Issues contains a PULSE_QUERY_UNRESOLVED error.

func Parse

func Parse(query string, schema *encoding.Schema, opts ParseOptions) *Result

Parse translates query against schema into a *types.Request. The returned Result is always non-nil; check Result.Issues for PULSE_QUERY_* codes to detect parse problems.