querytable

type AggCompileResult ¶

type AggCompileResult struct {
	SelectExprs []string
	GroupBySQL  string
}

AggCompileResult holds the SQL fragments for one metric's GROUP BY query. The caller splices them into its own FROM/JOIN, sharing the rows query's WHERE so the metric covers the same filtered set (scope = whole set, no paging):

SELECT <SelectExprs joined by ", ">
FROM   <caller FROM/JOIN>
[WHERE <Compile(WireQuery{Where: req.Where}, …).WhereSQL>]
[GROUP BY <GroupBySQL>]

SelectExprs is, in order: one `expr AS "g0"/"g1"/…` per group field, then the aggregate `AS "value"`, then `COUNT(*) AS "count"`. GroupBySQL lists the same group expressions (empty string ⇒ a single grand-total row, no GROUP BY).

func CompileAggregation(spec AggSpec, schema Schema) (AggCompileResult, error)

type AggSpec ¶

type AggSpec struct {
	ID      string   `json:"id"`
	Op      string   `json:"op"`
	Field   string   `json:"field,omitempty"`
	GroupBy []string `json:"groupBy,omitempty"`
}

AggSpec mirrors @pythia-software/query-table-core AggregationClause: one aggregate op over one measure column (Field; empty ⇒ COUNT(*)), broken down by zero or more group columns. Compiled by CompileAggregation; the metric panel runs one per spec over the WHERE-filtered set (no paging).

type CompileResult ¶

type CompileResult struct {
	// WhereSQL is "" when no filters apply, else "(c1) AND (c2) ...". Never
	// includes the WHERE keyword, so callers AND it into their own predicates.
	WhereSQL string
	// OrderSQL is "" to use the schema default, else
	// "expr DIR NULLS x, expr2 DIR2 NULLS y, <tiebreak...>".
	OrderSQL string
	// SelectExprs are "<expr> AS <safe_alias>" for each requested backend field.
	SelectExprs []string
	// Args are the $N bound values, in placeholder order starting at startIdx.
	Args []any
}

CompileResult holds the SQL fragments plus their ordered bound args.

func Compile(q WireQuery, schema Schema, startIdx int) (CompileResult, int, error)

type ComputedColumn ¶

type ComputedColumn struct {
	ID         string             `json:"id"`
	Label      string             `json:"label"`
	Expression ComputedExpression `json:"expression"`
	Revision   string             `json:"revision"`
}

type ComputedColumnRepository ¶

type ComputedColumnRepository interface {
	List(ctx context.Context, scope, dataset string) ([]ComputedColumn, error)
	Save(ctx context.Context, scope, dataset string, request SaveComputedColumnRequest) (ComputedColumn, error)
}

type ComputedExpression ¶

type ComputedExpression struct {
	Language string `json:"language"`
	Version  int    `json:"version"`
	Source   string `json:"source"`
}

type DistinctCompile ¶

type DistinctCompile struct {
	Expr      string
	SearchSQL string // "" when search is empty
	Args      []any
}

DistinctCompile holds the fragments for an autocomplete distinct-values query. The caller assembles them into its own FROM/JOIN tree:

SELECT DISTINCT <Expr> AS v FROM ... WHERE <Expr> IS NOT NULL [AND <SearchSQL>]
ORDER BY v LIMIT <n+1>   -- fetch one extra to compute hasMore

func CompileDistinct(field, search string, schema Schema, startIdx int) (DistinctCompile, int, error)

type DistinctHasNullCompile ¶

type DistinctHasNullCompile struct {
	IsNullExpr string
}

func CompileDistinctHasNull(field string, schema Schema) (DistinctHasNullCompile, error)

type FieldKind ¶

type FieldKind int

FieldKind picks the value-coercion + operator-validation path.

const (
	FieldText FieldKind = iota
	FieldNumber
	FieldDatetime
	FieldBool
	FieldEnum
	FieldTextArray
)

type FieldSpec ¶

type FieldSpec struct {
	Name         string
	Kind         FieldKind
	Expr         string
	Synthetic    bool
	ServerFilter bool // false → field is client-only; Compile rejects filters on it
	// ArrayCaseSensitive preserves exact text-array membership keys. Default false.
	ArrayCaseSensitive bool
	// FilterOps is nil for the type's default matrix; a non-nil slice is the
	// field's explicit operator allowlist. An empty slice disables every op.
	FilterOps []string
	Sortable  bool
	SortExpr  string // expr to ORDER BY when it differs from Expr (FieldDef.sort.field → that field's Expr)
}

FieldSpec is one field's server binding. Expr is the server-defined SQL expression (from the document's bindings.postgres.expr) and is the injection boundary: it is never built from request input.

type OrderBy ¶

type OrderBy struct {
	Field   string        `json:"field"`
	Dir     string        `json:"dir"`             // "asc" | "desc"
	Nulls   string        `json:"nulls,omitempty"` // "first" | "last" | "" (default last)
	Extract *RegexExtract `json:"extract,omitempty"`
}

OrderBy mirrors @pythia-software/query-table-core OrderByClause.

type OrderBys ¶

type OrderBys []OrderBy

OrderBys is a slice of OrderBy that also accepts a single object on decode (legacy compatibility) and a base64url `c`/`s` is handled at the WireQuery level via DecodeWireQuery.

func (o *OrderBys) UnmarshalJSON(b []byte) error

type RegexExtract ¶

type RegexExtract struct {
	Regex string `json:"regex"`
}

RegexExtract transforms a sort value before comparison. PostgreSQL's substring(text FROM regex) returns the first capture group when present and the whole match otherwise; a non-match is NULL.

type SQLComputedColumnStore ¶

type SQLComputedColumnStore struct{ DB *sql.DB }

func (s SQLComputedColumnStore) List(ctx context.Context, scope, dataset string) ([]ComputedColumn, error)

func (s SQLComputedColumnStore) Save(ctx context.Context, scope, dataset string, request SaveComputedColumnRequest) (ComputedColumn, error)

type SaveComputedColumnRequest ¶

type SaveComputedColumnRequest struct {
	Column           ComputedColumn `json:"column"`
	ExpectedRevision *string        `json:"expectedRevision"`
}

type Schema ¶

type Schema struct {
	Name         string
	IDField      string
	Fields       map[string]FieldSpec
	DefaultSort  []OrderBy
	TiebreakSort []OrderBy
}

Schema is the compiled, server-side field allowlist for one dataset.

func LoadSchema(doc []byte) (Schema, error)

type WhereClause ¶

type WhereClause struct {
	Field   string `json:"field"`
	Op      string `json:"op"`
	Value   string `json:"value"`
	Negated bool   `json:"negated,omitempty"`
}

WhereClause mirrors @pythia-software/query-table-core WhereClause. Negated wraps the predicate in a null-exclusive NOT; it is set only for ops without a complementary operator (contains/starts_with/ends_with/includes), matching the frontend's negateClause.

type WhereTerm ¶

type WhereTerm struct {
	Field   string        `json:"field,omitempty"`
	Op      string        `json:"op,omitempty"`
	Value   string        `json:"value,omitempty"`
	Negated bool          `json:"negated,omitempty"`
	Any     []WhereClause `json:"any,omitempty"`
}

WhereTerm is one conjunct of the WHERE (mirrors the TS WhereTerm = WhereClause | OrGroup). It is either a single predicate (Field/Op/Value set, Any nil) or an OR group (Any set). The two shapes are disjoint on the wire — a literal carries "field", a group carries "any" — so the default JSON (un)marshaling distinguishes them with no custom code. WHERE is the AND of these terms, i.e. conjunctive normal form.

func (t WhereTerm) IsGroup() bool

func (t WhereTerm) Literal() WhereClause

func (t WhereTerm) Predicates() []WhereClause

type WireQuery ¶

type WireQuery struct {
	Select       []string    `json:"select,omitempty"`
	Where        []WhereTerm `json:"w,omitempty"`
	OrderBy      OrderBys    `json:"o,omitempty"`
	Limit        int         `json:"l,omitempty"`
	Offset       int         `json:"f,omitempty"`
	Aggregations []AggSpec   `json:"g,omitempty"`
}

WireQuery is the server-bound subset of QueryState (the TS ServerQuery / the {s,w,o,...} `?q=` payload). View-only state (column widths) never arrives.

OrderBy unmarshals from BOTH the new array form and the legacy single-object form, so legacy links keep compiling.

func DecodeWireQuery(token string) (WireQuery, error)

func (q *WireQuery) UnmarshalJSON(data []byte) error

func (q WireQuery) Validate() error