query

package
v0.9.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 15, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

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

View Source
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.

View Source
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.

View Source
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.

View Source
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

func (ExportInput) TransformSchema(_ huma.Registry, s *huma.Schema) *huma.Schema

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

func (QueryInput) TransformSchema(_ huma.Registry, s *huma.Schema) *huma.Schema

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

func (QueryRunInput) TransformSchema(_ huma.Registry, s *huma.Schema) *huma.Schema

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"
)

func (SemanticType) Schema

Schema publishes the semantic types semanticTypes gives, and no other, so the enum can neither miss one the core answers nor list one it never does.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL