Documentation
¶
Overview ¶
Package query is the query commands: query runs a query, query.compile compiles one to SQL, and query.validate checks one. What they share, and only they, stays in here.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Compile = command.Define(command.Def[QueryRunInput, CompiledQuery]{ Name: "query.compile", Short: "Compile a query to SQL, without running it", ReadOnly: true, Timeout: 2 * time.Minute, Needs: func(in QueryRunInput) command.Sidecars { return command.Sidecars{Node: in.Lang != "sql"} }, Check: QueryRunInput.check, Errors: []apperr.AnyCode{query.QueryInvalid, errcode.DataPermsUnenforceable}, Run: func(ctx context.Context, cc command.CommandContext, in QueryRunInput) (CompiledQuery, error) { if in.Lang == "sql" { if err := in.checkDataSource(ctx, cc); err != nil { return CompiledQuery{}, err } return CompiledQuery{SQL: in.Query}, nil } aql, _, err := in.aql() if err != nil { return CompiledQuery{}, err } if err := command.RequireSidecars(cc, command.Sidecars{Node: true}); err != nil { return CompiledQuery{}, err } src, err := sourceOf(cc) if err != nil { return CompiledQuery{}, err } compiled, err := compileAQL(ctx, cc, src, in.Dataset, aql, in.run()) if err != nil { return CompiledQuery{}, err } return CompiledQuery{SQL: compiled.SQL, AQL: compiled.AQL, Columns: compiledColumns(compiled.Columns)}, nil }, })
Compile compiles a query to SQL, without running it.
var Export = command.Define(command.Def[ExportInput, command.ExportLink]{ Name: "query.export", Short: "Export a query's whole result as a file: a link to download it", Long: "Export a query's whole result as a file: a link to download it.\n\n" + "The query runs to completion before the answer, so a query that fails fails here. " + "The CLI downloads the file, to stdout or --output; --link prints the answer instead.", NonDestructive: true, Timeout: 30 * time.Minute, Needs: func(in ExportInput) command.Sidecars { return command.Sidecars{Node: in.Lang != "sql", CanalQuery: true} }, Check: ExportInput.check, Errors: []apperr.AnyCode{query.QueryInvalid, errcode.QueryFailed, errcode.DataPermsUnenforceable, errcode.ExportsUnavailable}, Run: runExport, })
Export runs a query and answers its whole result as a file: a link to download it. See docs/designs/exports.md.
var Query = command.Define(command.Def[QueryRunInput, QueryResult]{ Name: "query", Short: "Run a query: its rows, and the SQL that produced them", ReadOnly: true, Timeout: 10 * time.Minute, Needs: func(in QueryRunInput) command.Sidecars { return command.Sidecars{Node: in.Lang != "sql", CanalQuery: true} }, Check: QueryRunInput.check, Errors: []apperr.AnyCode{query.QueryInvalid, errcode.QueryFailed, errcode.DataPermsUnenforceable}, Run: func(ctx context.Context, cc command.CommandContext, in QueryRunInput) (QueryResult, error) { if in.Lang == "sql" { ds, err := in.dataSource(ctx, cc) if err != nil { return QueryResult{}, err } if err := command.RequireSidecars(cc, command.Sidecars{CanalQuery: true}); err != nil { return QueryResult{}, err } r, err := query.ExecuteSQL(ctx, cc.Clients.CanalQuery, ds, in.Query) if err != nil { return QueryResult{}, failed(err) } return QueryResult{SQL: r.SQL, Columns: describeColumns(r.Header, nil), Result: QueryRows{Fields: r.Fields, Records: r.Records}}, nil } aql, limit, err := in.aql() if err != nil { return QueryResult{}, err } if err := command.RequireSidecars(cc, command.Sidecars{Node: true, CanalQuery: true}); err != nil { return QueryResult{}, err } src, err := sourceOf(cc) if err != nil { return QueryResult{}, err } compiled, err := compileAQL(ctx, cc, src, in.Dataset, aql, in.run()) if err != nil { return QueryResult{}, err } r, err := query.Execute(ctx, cc.Clients.CanalQuery, src.DataSources, compiled, limit) if err != nil { return QueryResult{}, failed(err) } return QueryResult{SQL: r.SQL, AQL: compiled.AQL, Columns: describeColumns(r.Header, compiled.Columns), Result: QueryRows{Fields: r.Fields, Records: r.Records}}, nil }, })
Query runs a query: its rows, and the SQL that produced them.
var Validate = command.Define(command.Def[QueryInput, query.QueryValidation]{ Name: "query.validate", Short: "Validate a query: its diagnostics, without running it", ReadOnly: true, Timeout: 2 * time.Minute, Needs: func(QueryInput) command.Sidecars { return command.Sidecars{Node: true} }, Check: func(in QueryInput) error { if in.Lang == "sql" { return command.InvalidArg("lang", "unsupported", "validating a SQL query is not supported yet; you can still run it directly") } return in.target() }, Run: func(ctx context.Context, cc command.CommandContext, in QueryInput) (query.QueryValidation, error) { aql, _, err := in.aql() if err != nil { return query.QueryValidation{}, err } if err := command.RequireSidecars(cc, command.Sidecars{Node: true}); err != nil { return query.QueryValidation{}, err } src, err := sourceOf(cc) if err != nil { return query.QueryValidation{}, err } return query.Check(ctx, cc.Clients.Node, src, in.Dataset, aql) }, Valid: func(r query.QueryValidation) bool { return r.Valid }, })
Validate checks a query: its diagnostics, without running it.
Functions ¶
This section is empty.
Types ¶
type Column ¶
type Column struct {
Name string `json:"name" doc:"the column's key, as in fields"`
FieldName string `json:"fieldName" doc:"the field it draws; for an adhoc column, its name"`
ModelID string `` /* 126-byte string literal not displayed */
Label string `json:"label"`
Adhoc bool `json:"adhoc" doc:"a query-local expression, not a field the dataset defines"`
IsMeasure bool `json:"isMeasure"`
Aggregation string `json:"aggregation,omitempty" doc:"an aggregated field's aggregation, such as sum or count distinct"`
SemanticType SemanticType `` /* 389-byte string literal not displayed */
ArrowType canalquery.ArrowType `` /* 135-byte string literal not displayed */
DBType string `` /* 180-byte string literal not displayed */
}
Column is one column of a query's answer: what it draws from the dataset, as anfra-node describes it, in amql's names (camelCase); and its types, which the core adds, in the API's (snake_case). See docs/designs/result-values.md.
type CompiledQuery ¶
type CompiledQuery struct {
SQL string `json:"sql"`
AQL string `json:"aql,omitempty" doc:"the AQL compiled: the query with its Query Input applied; absent for a SQL query"`
Columns []Column `` /* 133-byte string literal not displayed */
}
CompiledQuery is the `query compile` result: the SQL the query compiles to.
type ExportFormatOptions ¶
type ExportFormatOptions struct {
Header string `` /* 203-byte string literal not displayed */
BOM bool `` /* 155-byte string literal not displayed */
}
ExportFormatOptions are a format's options. Each applies to the formats it names; given to another, it is refused (check).
type ExportInput ¶
type ExportInput struct {
QueryInput
Input *anfranode.QueryTransforms `` /* 126-byte string literal not displayed */
Timezone string `json:"timezone,omitempty" doc:"the IANA time zone relative dates and date truncation use, such as Asia/Ho_Chi_Minh"`
Format string `json:"format,omitempty" enum:"csv" default:"csv" doc:"the file's format"`
FormatOptions *ExportFormatOptions `json:"format_options,omitempty" doc:"the format's options"`
Filename string `` /* 181-byte string literal not displayed */
}
ExportInput is what query.export takes: a query and what shapes its run, as query takes them, but no page, since an export is the whole result; and the file's format.
func (ExportInput) TransformSchema ¶
type QueryInput ¶
type QueryInput struct {
Query string `json:"query" cli:"positional,stdin" doc:"the query"`
Lang string `json:"lang,omitempty" short:"l" enum:"aql,sql" default:"aql" doc:"the language the query is written in"`
Dataset string `json:"dataset,omitempty" short:"d" doc:"the dataset an AQL query runs against"`
DataSource string `json:"data_source,omitempty" short:"s" doc:"the data source a SQL query runs against"`
}
QueryInput is a query: its text, the language it is written in, and the target it runs against. Which target a language runs against is target's to say: AQL against a dataset, and SQL against a data source.
func (QueryInput) TransformSchema ¶
TransformSchema publishes the required query (command.ArgsSchema). The target is not a group in the schema: which one is required depends on lang, which a group cannot say, so target checks it.
type QueryResult ¶
type QueryResult struct {
SQL string `json:"sql"`
AQL string `json:"aql,omitempty" doc:"the AQL that ran: the query with its Query Input applied; absent for a SQL query"`
Columns []Column `json:"columns" doc:"one per field of result, in order"`
Result QueryRows `json:"result"`
}
QueryResult is the `query` result: the SQL that ran, the AQL it was compiled from, what each column is, and the rows.
type QueryRows ¶
type QueryRows struct {
Fields []string `json:"fields"`
Records []canalquery.Row `` /* 309-byte string literal not displayed */
}
type QueryRunInput ¶
type QueryRunInput struct {
QueryInput
Input *anfranode.QueryTransforms `` /* 126-byte string literal not displayed */
Page int `json:"page,omitempty" minimum:"1" doc:"the 1-based page of rows to answer; needs a page size"`
PageSize int `json:"page_size,omitempty" minimum:"1" doc:"rows per page; alone, the first page"`
Timezone string `json:"timezone,omitempty" doc:"the IANA time zone relative dates and date truncation use, such as Asia/Ho_Chi_Minh"`
}
QueryRunInput is what query and query.compile take: a query, and what shapes its run. query.validate takes the query alone (QueryInput), since none of it applies to checking one.
func (QueryRunInput) TransformSchema ¶
type SemanticType ¶
type SemanticType string
SemanticType is what a column's values mean: AML's types, plus bit.
const ( SemanticText SemanticType = "text" SemanticNumber SemanticType = "number" SemanticDate SemanticType = "date" SemanticDatetime SemanticType = "datetime" SemanticTruefalse SemanticType = "truefalse" SemanticJSON SemanticType = "json" SemanticBit SemanticType = "bit" SemanticUnknown SemanticType = "unknown" )