Documentation
¶
Overview ¶
Package query is the query use-case layer: it checks a (dataset, AQL) request, turns it into SQL and runs it, by loading the repo's data sources and driving the sidecars via their clients. What an invalid query is, and the code it fails with, are its own. It depends on the clients (not the process managers), so it works equally against host-spawned or external sidecars. The CLI command and the future HTTP/MCP handler are thin shells over these functions.
Index ¶
- Constants
- Variables
- func Compile(ctx context.Context, node *anfranode.Client, src Source, dataset, aql string, ...) (anfranode.CompileToSQLResult, error)
- func CompileRequest(ctx context.Context, src Source, dataset, aql string) (anfranode.CompileToSQLRequest, error)
- func ExtractLimit(aql string) (string, int, error)
- func Stream(ctx context.Context, canal *canalquery.Client, sources datasource.DataSources, ...) error
- func StreamSQL(ctx context.Context, canal *canalquery.Client, ds datasource.DataSource, ...) error
- type QueryValidation
- type Run
- type RunResult
- type Source
Constants ¶
const NoLimit = -1
NoLimit is the row limit meaning "no truncation" (canal's truncate_rows uses a negative value for this).
Variables ¶
var QueryInvalid = apperr.DefinePublicCodeWith[QueryValidation](errcode.NS, "query_invalid", apperr.User, "The query is invalid.")
QueryInvalid is a query that cannot run or compile, with its diagnostics: the QueryValidation that says why. A command that judges the query answers the QueryValidation instead.
Functions ¶
func Compile ¶
func Compile(ctx context.Context, node *anfranode.Client, src Source, dataset, aql string, run Run) (anfranode.CompileToSQLResult, error)
Compile compiles an AQL query against a dataset into SQL plus the data source it targets (dialect + execution routing), without executing. Shared by --generate and the run path so both fail identically on a bad query: with QueryInvalid and its diagnostics when the query does not compile. A failure that is not the query's (an unknown dataset, a missing data source, the run's shaping refused) is not diagnostic-shaped, and is returned as it is. The result's AQL is the query with run's Query Input applied.
func CompileRequest ¶
func CompileRequest(ctx context.Context, src Source, dataset, aql string) (anfranode.CompileToSQLRequest, error)
CompileRequest builds the sidecar compile request for a (dataset, aql) against src, with its data sources' dialects and no connection. Shared by SQL generation and AQL validation (both feed the same {repo, datasetFqn, aql, dataSources} to the sidecar).
func ExtractLimit ¶
ExtractLimit pulls an anfra-level `limit:` directive out of an AQL query and returns the query with the directive removed plus the row limit. The AQL engine does not support `limit`, so anfra strips it here and applies it at execution time via canal's truncate_rows. Returns NoLimit when no directive is present. TODO: remove this when AQL supports limit
func Stream ¶
func Stream(ctx context.Context, canal *canalquery.Client, sources datasource.DataSources, compiled anfranode.CompileToSQLResult, truncateRows int, h canalquery.Handler) error
Stream is Execute that hands the result to h as it arrives, its header first, holding none of it.
func StreamSQL ¶
func StreamSQL(ctx context.Context, canal *canalquery.Client, ds datasource.DataSource, sql string, h canalquery.Handler) error
StreamSQL is ExecuteSQL that hands the result to h as it arrives, its header first, holding none of it.
Types ¶
type QueryValidation ¶
type QueryValidation struct {
// Valid: no diagnostic has "error" severity.
Valid bool `json:"valid"`
Diagnostics []anfranode.AQLDiagnostic `json:"diagnostics"`
}
QueryValidation is the outcome of validating a query: its verdict, and the type-check diagnostics for a single AQL query.
type Run ¶
type Run struct {
Input *anfranode.QueryTransforms
Pagination *anfranode.Pagination
Timezone string
}
Run is what shapes one run of a query beyond its AQL: its Query Input, applied to the AQL before it compiles; a page of rows (nil: every row); and the time zone relative dates and date truncation use ("": anfra-node's default).
type RunResult ¶
type RunResult struct {
SQL string
canalquery.Header
Records []canalquery.Row
}
RunResult is the compiled SQL plus the executed result: its header (fields and their types) and its rows.
func Execute ¶
func Execute(ctx context.Context, canal *canalquery.Client, sources datasource.DataSources, compiled anfranode.CompileToSQLResult, truncateRows int) (*RunResult, error)
Execute runs already-compiled SQL via canal-query against the data source the dataset targets, returning the SQL and the result rows. Split from Compile so callers can distinguish a compile failure (a query problem) from an execution failure (a data-source/DB problem). truncateRows caps the rows canal returns (NoLimit for all rows); it's how anfra applies the AQL `limit:` directive.
func ExecuteSQL ¶
func ExecuteSQL(ctx context.Context, canal *canalquery.Client, ds datasource.DataSource, sql string) (*RunResult, error)
ExecuteSQL runs sql on ds as it is: the caller wrote it in the data source's dialect, with its own LIMIT. Nothing is compiled into it — no restriction applies.
type Source ¶ added in v0.9.0
type Source struct {
Repo repo.Repo
DataSources datasource.DataSources
}
Source is what a query compiles against and runs on: the repo's AML, and its data sources, whose dialects compiling asks for and one of whose connections a run asks for.