Documentation
¶
Overview ¶
Package anfranode is the anfra-node sidecar, the AML/AQL engine: its supervisor, which spawns one or connects to an external one, and its JSON-RPC client.
Index ¶
- Constants
- func CompileDataSources(m map[string]datasource.DataSource) map[string]CompileDataSource
- type AQLDiagnostic
- type CatalogIngestRequest
- type CatalogSearchRequest
- type CatalogSearchResult
- type Client
- func (c *Client) Call(ctx context.Context, method string, params any, out any) error
- func (c *Client) CompileToSQL(ctx context.Context, req CompileToSQLRequest) (CompileToSQLResult, error)
- func (c *Client) IngestCatalog(ctx context.Context, req CatalogIngestRequest) error
- func (c *Client) Ping(ctx context.Context) (map[string]any, error)
- func (c *Client) SearchCatalog(ctx context.Context, req CatalogSearchRequest) (CatalogSearchResult, error)
- func (c *Client) ShowAML(ctx context.Context, req ShowRequest) (ShowResult, error)
- func (c *Client) ValidateAML(ctx context.Context, req ValidateAMLRequest) (ValidateAMLResult, error)
- func (c *Client) ValidateAQL(ctx context.Context, req CompileToSQLRequest) (ValidateAQLResult, error)
- func (c *Client) WaitReady(ctx context.Context) error
- type CompileDataSource
- type CompileError
- type CompileOptions
- type CompileToSQLRequest
- type CompileToSQLResult
- type ExploreColumn
- type Pagination
- type QueryCondition
- type QueryDateDrill
- type QueryFilter
- type QuerySort
- type QueryTransforms
- type RPCError
- type ReportTrace
- type ReportTraceLoc
- type ShowDataset
- type ShowField
- type ShowModel
- type ShowObject
- type ShowRepo
- type ShowRequest
- type ShowResult
- type Sidecar
- type ValidateAMLRequest
- type ValidateAMLResult
- type ValidateAQLResult
- type ValidationReport
Constants ¶
const Name = "anfra-node"
Name is the sidecar's name, in its logs, its errors and its binary's.
const RPCInvalidParams = -32602
RPCInvalidParams is the JSON-RPC code anfra-node answers a request it refuses as invalid input with (its InvalidInputError).
Variables ¶
This section is empty.
Functions ¶
func CompileDataSources ¶
func CompileDataSources(m map[string]datasource.DataSource) map[string]CompileDataSource
CompileDataSources is the repo's data sources as the sidecar takes them: a name and a dialect each, without their connections.
Types ¶
type AQLDiagnostic ¶
type AQLDiagnostic struct {
Message string `json:"message"`
Severity string `json:"severity"`
Line *int `json:"line,omitempty"`
Column *int `json:"column,omitempty"`
}
AQLDiagnostic is one AQL type-check finding. Severity is "error" or "warning"; Line/Column are 1-based positions when known.
type CatalogIngestRequest ¶
type CatalogIngestRequest struct {
RepoPath string `json:"repoPath"`
SourcesPath string `json:"sourcesPath"`
CatalogPath string `json:"catalogPath"`
CanalQueryBaseURL string `json:"canalQueryBaseUrl"`
Source string `json:"source,omitempty"`
}
CatalogIngestRequest mirrors anfra-node's catalog.ingest params. The Go host starts sidecars and passes runtime paths/URLs; anfra-node owns source parsing and ingestion internals.
type CatalogSearchRequest ¶
type CatalogSearchRequest struct {
CatalogPath string `json:"catalogPath"`
CanalQueryBaseURL string `json:"canalQueryBaseUrl"`
Query string `json:"query"`
}
CatalogSearchRequest mirrors anfra-node's catalog.search params. The Go host supplies the local catalog path and canal-query URL; anfra-node owns search parsing, planning, and result shaping.
type CatalogSearchResult ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client talks to an anfra-node over JSON-RPC. It is address-based and owns no process, so it works against a host-spawned sidecar (Unix socket) or an external one reachable over TCP (docker-compose / k8s).
func NewClientHTTP ¶
NewClientHTTP connects to an anfra-node reachable over TCP, e.g. a docker-compose / k8s service. No process is owned.
func NewClientUnix ¶
NewClientUnix dials a host-spawned sidecar over its Unix socket.
func (*Client) Call ¶
Call invokes a JSON-RPC method and unmarshals the result into out (if non-nil).
func (*Client) CompileToSQL ¶
func (c *Client) CompileToSQL(ctx context.Context, req CompileToSQLRequest) (CompileToSQLResult, error)
CompileToSQL compiles an AQL query against a dataset into dialect SQL.
func (*Client) IngestCatalog ¶
func (c *Client) IngestCatalog(ctx context.Context, req CatalogIngestRequest) error
IngestCatalog builds the local search catalog through anfra-node. The anfra-node method is a void RPC: success means the catalog was written, while failures are returned through the JSON-RPC error channel.
func (*Client) SearchCatalog ¶
func (c *Client) SearchCatalog(ctx context.Context, req CatalogSearchRequest) (CatalogSearchResult, error)
SearchCatalog searches the active local catalog through anfra-node.
func (*Client) ShowAML ¶
func (c *Client) ShowAML(ctx context.Context, req ShowRequest) (ShowResult, error)
ShowAML shows an object of the repo, read from its compiled AML.
func (*Client) ValidateAML ¶
func (c *Client) ValidateAML(ctx context.Context, req ValidateAMLRequest) (ValidateAMLResult, error)
ValidateAML validates an AML repo (compile + validator suite) for the selected paths and returns the findings.
func (*Client) ValidateAQL ¶
func (c *Client) ValidateAQL(ctx context.Context, req CompileToSQLRequest) (ValidateAQLResult, error)
ValidateAQL type-checks a single AQL query against a dataset (same inputs as CompileToSQL) and returns its diagnostics instead of throwing on the first error.
type CompileDataSource ¶
CompileDataSource is the name->dialect entry the sidecar needs to compile SQL. Connection/credentials are NOT part of this — they stay host-side.
type CompileError ¶
type CompileError struct {
FilePath string `json:"filePath,omitempty"`
Message string `json:"message"`
Row *int `json:"row,omitempty"`
Col *int `json:"col,omitempty"`
}
CompileError is an AML file that failed to compile (interpret). Row/Col are 1-based when a location is known.
type CompileOptions ¶
type CompileOptions struct {
TimezoneRegion string `json:"timezoneRegion,omitempty"`
}
CompileOptions are the compile options anfra sets. TimezoneRegion is an IANA zone, for relative dates and date truncation.
type CompileToSQLRequest ¶
type CompileToSQLRequest struct {
RepoPath string `json:"repoPath"`
// RepoID is the sidecar's compile-cache identity for this repo. One sidecar
// may serve many repos (and, when shared, many tenants), so it travels per
// request rather than per process. Omitted, the sidecar derives one from
// RepoPath.
RepoID string `json:"repoId,omitempty"`
DatasetFqn string `json:"datasetFqn"`
AQL string `json:"aql"`
DataSources map[string]CompileDataSource `json:"dataSources"`
// Input is the query's Query Input, applied by rewriting the AQL before it
// compiles. Nil: none.
Input *QueryTransforms `json:"input,omitempty"`
// Pagination asks for one page of rows, compiled into LIMIT/OFFSET. Nil: every
// row. Refused for a pivot query.
Pagination *Pagination `json:"pagination,omitempty"`
Options *CompileOptions `json:"options,omitempty"`
}
CompileToSQLRequest / Result mirror the sidecar's aql.compile_to_sql method.
type CompileToSQLResult ¶
type CompileToSQLResult struct {
SQL string `json:"sql"`
// AQL is the query that compiled: the AQL with its Query Input applied.
AQL string `json:"aql"`
DataSource CompileDataSource `json:"dataSource"` // the data source the SQL targets (for execution routing)
// Columns describes each output column of an explore query; absent for other
// query shapes.
Columns []ExploreColumn `json:"columns,omitempty"`
}
type ExploreColumn ¶
type ExploreColumn 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"`
// Type is the AMQL type the type checker gives the column's expression
// (number, text, date, ...), not the type its field declares: a count of a
// text field is a number. Absent from an anfra-node before 0.4.0.
Type string `json:"type,omitempty"`
}
ExploreColumn is one column of a query's answer: the key its values come back under, and the dataset field it draws, in the names AQL uses in the dataset. anfra-node describes an explore query's; the core API passes them through in these names, amql's and the Anfra SDK's.
type Pagination ¶
Pagination is one 1-based page of rows.
type QueryCondition ¶
type QueryCondition struct {
Expr string `json:"expr" doc:"an AQL condition"`
}
type QueryDateDrill ¶
type QueryFilter ¶
type QueryFilter struct {
Field string `json:"field" doc:"model.field for a dataset field, or the name of a dataset metric"`
Operator string `json:"operator" doc:"the operator, such as is, contains, between, last"`
Values []any `` /* 297-byte string literal not displayed */
Modifier string `json:"modifier,omitempty" doc:"the date unit of a relative operator, such as day"`
Aggregation string `json:"aggregation,omitempty" doc:"the condition applies to this aggregate of field, such as sum"`
}
type QueryTransforms ¶
type QueryTransforms struct {
Filters []QueryFilter `json:"filters,omitempty" doc:"conditions on fields, ANDed with the query's own filters"`
Conditions []QueryCondition `json:"conditions,omitempty" doc:"AQL conditions ANDed with the query's own filters"`
Sorts []QuerySort `json:"sorts,omitempty" doc:"sorts by result column, replacing the query's own"`
DateDrills []QueryDateDrill `json:"dateDrills,omitempty" doc:"date fields redrawn at another grain, their columns' names kept"`
}
QueryTransforms is a query's Query Input: the structured transforms it carries on one run (a Data App's control filters, cross-filter conditions, sorts and date drills), applied by anfra-node rewriting its AQL before it compiles. The core API passes it through in these names, amql's and the Anfra SDK's: anfra-node checks the values (an operator, a grain).
type RPCError ¶
RPCError is an error anfra-node answered a call with. Data is the error's JSON-RPC data, when it carries one: for invalid input, the {path} of what is wrong, e.g. a Query Input entry.
type ReportTrace ¶
type ReportTrace struct {
Kind string `json:"kind"`
Name string `json:"name"`
Loc *ReportTraceLoc `json:"loc,omitempty"`
}
type ReportTraceLoc ¶
type ReportTraceLoc struct {
FilePath string `json:"filePath"`
Line *int `json:"line,omitempty"`
Column *int `json:"column,omitempty"`
}
ReportTraceLoc / ReportTrace locate a validator finding within the AML source.
type ShowDataset ¶
type ShowDataset struct {
Kind string `json:"kind" enum:"dataset"`
Fqn string `json:"fqn" doc:"the dataset's fully qualified name, as AQL and the catalog name it"`
Name string `json:"name"`
Label string `json:"label,omitempty"`
Description string `json:"description,omitempty"`
Models []ShowModel `json:"models,omitempty" doc:"the models the dataset uses; absent in outline"`
Metrics []ShowField `json:"metrics,omitempty" doc:"the dataset's metrics; absent in outline"`
}
ShowDataset is a dataset: in outline, who it is; in full, also its models and metrics. Its interface, not its implementation: what a caller needs to write a query against it or read a query's result, nothing of how it is built.
type ShowField ¶
type ShowField struct {
Fqn string `json:"fqn" doc:"the catalog's identity: <model fqn>.<name>, or <dataset fqn>.<name> for a dataset-level field or a metric"`
Name string `json:"name" doc:"AQL writes <model fqn>.<name>; a metric, its name alone"`
Label string `json:"label,omitempty"`
Description string `json:"description,omitempty"`
Role string `json:"role" enum:"dimension,measure,param,metric"`
Type string `json:"type" doc:"the compiled data type, such as number, text, date, datetime, truefalse"`
Aggregation string `json:"aggregation,omitempty" doc:"a measure's aggregation, such as sum or count distinct; custom for a custom one"`
Hidden bool `json:"hidden"`
Format any `json:"format,omitzero" doc:"how a value displays, as the AML declares it"`
Definition string `json:"definition,omitempty" doc:"the definition of a field or metric written in AQL"`
DefinedInDataset bool `json:"definedInDataset,omitzero" doc:"a dimension the dataset declares on one of its models"`
}
ShowField is a field or a metric.
type ShowModel ¶
type ShowModel struct {
Fqn string `json:"fqn" doc:"the model's fully qualified name: what AQL writes before a field"`
Name string `json:"name"`
Label string `json:"label,omitempty"`
Description string `json:"description,omitempty"`
Fields []ShowField `json:"fields"`
}
ShowModel is a model as a dataset uses it, with the fields AQL can reference on it.
type ShowObject ¶
type ShowObject struct {
Repo *ShowRepo
Dataset *ShowDataset
}
ShowObject is one object of the repo, tagged by its kind: the repo, or a dataset. Exactly one of its fields is set. More kinds come (a model, a field, a metric), so a client must accept a kind it does not know.
func (ShowObject) MarshalJSONTo ¶
func (o ShowObject) MarshalJSONTo(enc *jsontext.Encoder) error
MarshalJSONTo encodes the object set, within the encoder it is in, so the encoder's options reach inside it (httpkit.JSONOptions).
func (ShowObject) Schema ¶
func (ShowObject) Schema(r huma.Registry) *huma.Schema
Schema publishes the union, discriminated by kind.
func (*ShowObject) UnmarshalJSON ¶
func (o *ShowObject) UnmarshalJSON(b []byte) error
type ShowRepo ¶
type ShowRepo struct {
Kind string `json:"kind" enum:"repo"`
Datasets []ShowDataset `` /* 151-byte string literal not displayed */
}
ShowRepo is the repo: the datasets it offers, each in full, or in outline when it cannot be shown in full (a diagnostic says why).
type ShowRequest ¶
type ShowRequest struct {
RepoPath string `json:"repoPath"`
// RepoID is the compile-cache identity; see CompileToSQLRequest.RepoID.
RepoID string `json:"repoId,omitempty"`
DataSources map[string]CompileDataSource `json:"dataSources"`
Type string `json:"type,omitempty"`
Fqn string `json:"fqn,omitempty"`
}
ShowRequest mirrors the sidecar's aml.show params: what to show, as the semantic catalog identifies it, an entity type and its fqn; both empty for the repo. DataSources are what compiling a dataset resolves its dialect from.
type ShowResult ¶
type ShowResult struct {
Object ShowObject `json:"object"`
Diagnostics []CompileError `` /* 214-byte string literal not displayed */
}
ShowResult is aml.show's answer, which the core API passes through: the object shown, and what is wrong in the repo for it.
type Sidecar ¶
type Sidecar struct {
// contains filtered or unexported fields
}
Sidecar supervises a host-spawned anfra-node. It owns the process lifecycle and exposes a Client pointed at it; callers do their RPC through Client() (which also works against external sidecars, so consumers don't depend on host-spawning).
type ValidateAMLRequest ¶
type ValidateAMLRequest struct {
RepoPath string `json:"repoPath"`
// RepoID is the compile-cache identity; see CompileToSQLRequest.RepoID.
RepoID string `json:"repoId,omitempty"`
Paths []string `json:"paths,omitempty"`
}
ValidateAMLRequest mirrors the sidecar's aml.validate params. Paths are file/dir/glob selectors relative to the repo; empty validates the whole repo. No data sources are involved — this type-checks AML.
type ValidateAMLResult ¶
type ValidateAMLResult struct {
CompileErrors []CompileError `json:"compileErrors"`
Reports []ValidationReport `json:"reports"`
}
ValidateAMLResult mirrors the sidecar's aml.validate result: files that failed to compile, plus the validator suite's findings.
type ValidateAQLResult ¶
type ValidateAQLResult struct {
Diagnostics []AQLDiagnostic `json:"diagnostics"`
}
type ValidationReport ¶
type ValidationReport struct {
Validator string `json:"validator"`
FilePath string `json:"filePath"`
Type string `json:"type"`
Fqn string `json:"fqn"`
Severity string `json:"severity"`
Message string `json:"message"`
Code any `json:"code,omitzero"`
Trace []ReportTrace `json:"trace,omitempty"`
}
ValidationReport is one finding from the validator suite. Severity is "error", "warning", or "info".