bydbql

package
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package bydbql provides BanyanDB Query Language (BydbQL) parsing and translation capabilities.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BindParams added in v0.11.0 

func BindParams(g *Grammar, params []*modelv1.TagValue) error

BindParams binds positional parameters to the `?` placeholders in the parsed grammar, in their order of appearance in the query text. After a successful call, the grammar is indistinguishable from one parsed with literal values, so the transformer needs no placeholder awareness. Callers must invoke it before Transform even when params is empty, so a query holding unbound placeholders is rejected instead of silently misinterpreted. Parameter positions in error messages are 1-based.

Binding mutates the grammar in place, so a grammar binds exactly once: rebinding is rejected and a failed bind leaves the grammar partially bound and unusable — parse the query again in both cases. For parse-once/bind-many reuse, use Prepare and (*PreparedStatement).Bind, which never mutate the parsed template.

Types

type BoundQuery added in v0.11.0 

type BoundQuery struct {
	// contains filtered or unexported fields
}

BoundQuery pairs an immutable prepared statement with the values bound for one request. Its values are the per-request overlay indexed by placeholder position, allocated by Bind and never shared or mutated after. Pass it to Transformer.TransformBound.

type Grammar 

type Grammar struct {
	Select *GrammarSelectStatement `parser:"  @@"`
	TopN   *GrammarTopNStatement   `parser:"| @@"`
	// contains filtered or unexported fields
}

Grammar represents the root of a BydbQL statement parsed by Participle.

func ParseQuery 

func ParseQuery(query string) (*Grammar, error)

ParseQuery parses a BydbQL query string into a Grammar struct.

type GrammarAggregateFunction 

type GrammarAggregateFunction struct {
	Function string                 `parser:"@('SUM'|'MEAN'|'AVG'|'COUNT'|'MAX'|'MIN')"`
	Column   *GrammarIdentifierPath `parser:"'(' @@ ')'"`
}

GrammarAggregateFunction represents aggregate functions.

type GrammarAndExpr 

type GrammarAndExpr struct {
	Left  *GrammarPredicate  `parser:"@@"`
	Right []*GrammarAndRight `parser:"@@*"`
}

GrammarAndExpr represents AND expression.

type GrammarAndRight 

type GrammarAndRight struct {
	And   string            `parser:"@'AND'"`
	Right *GrammarPredicate `parser:"@@"`
}

GrammarAndRight represents right side of AND.

type GrammarBinaryPredicate 

type GrammarBinaryPredicate struct {
	Identifier *GrammarIdentifierPath      `parser:"@@"`
	Tail       *GrammarBinaryPredicateTail `parser:"@@"`
}

GrammarBinaryPredicate captures comparison or MATCH predicates sharing an identifier left-hand side.

type GrammarBinaryPredicateTail 

type GrammarBinaryPredicateTail struct {
	Match   *GrammarMatchTail   `parser:"  @@"`
	Compare *GrammarCompareTail `parser:"| @@"`
}

GrammarBinaryPredicateTail distinguishes between a MATCH suffix and a standard comparison operator.

type GrammarColumn 

type GrammarColumn struct {
	Aggregate  *GrammarAggregateFunction `parser:"  @@"`
	Identifier *GrammarIdentifierPath    `parser:"| @@"`
	TypeSpec   *string                   `parser:"( '::' @('TAG'|'FIELD') )?"`
}

GrammarColumn represents a column in projection.

type GrammarCompareTail 

type GrammarCompareTail struct {
	Operator string        `parser:"@( '=' | '!=' | '>=' | '<=' | '>' | '<' )"`
	Value    *GrammarValue `parser:"@@"`
}

GrammarCompareTail represents traditional binary comparison operators.

type GrammarFromClause 

type GrammarFromClause struct {
	From         string              `parser:"@'FROM'"`
	ResourceType string              `parser:"@('STREAM'|'MEASURE'|'TRACE'|'PROPERTY')"`
	ResourceName string              `parser:"@Ident"`
	In           *GrammarInClause    `parser:"@@"`
	Stage        *GrammarStageClause `parser:"@@?"`
}

GrammarFromClause represents FROM clause.

type GrammarGroupByClause 

type GrammarGroupByClause struct {
	Group   string                  `parser:"@'GROUP'"`
	By      string                  `parser:"@'BY'"`
	Columns []*GrammarGroupByColumn `parser:"@@ ( ',' @@ )*"`
}

GrammarGroupByClause represents GROUP BY clause.

type GrammarGroupByColumn 

type GrammarGroupByColumn struct {
	Identifier *GrammarIdentifierPath `parser:"@@"`
	TypeSpec   *string                `parser:"( '::' @('TAG'|'FIELD') )?"`
}

GrammarGroupByColumn represents a column in GROUP BY.

type GrammarHavingPredicate 

type GrammarHavingPredicate struct {
	Identifier *GrammarIdentifierPath `parser:"@@"`
	Not        *string                `parser:"@'NOT'?"`
	Having     string                 `parser:"@'HAVING'"`
	Values     *GrammarHavingValues   `parser:"@@"`
}

GrammarHavingPredicate represents HAVING/NOT HAVING predicate.

type GrammarHavingValues 

type GrammarHavingValues struct {
	Single *GrammarValue   `parser:"  @@"`
	Array  []*GrammarValue `parser:"| '(' @@ ( ',' @@ )* ')'"`
}

GrammarHavingValues represents values in HAVING.

type GrammarIdentifierPart 

type GrammarIdentifierPart struct {
	Ident   *string `parser:"  @Ident"`
	Keyword *string `parser:"| @Keyword"`
}

GrammarIdentifierPart Can be either an Ident or a Keyword (keywords are allowed in paths, but not as standalone identifiers).

func (*GrammarIdentifierPart) Value 

func (p *GrammarIdentifierPart) Value() string

Value returns the string value of the identifier part.

type GrammarIdentifierPath 

type GrammarIdentifierPath struct {
	QuotedIdent *string                  `parser:"  ( @QuotedIdent | @String )"`
	First       *GrammarIdentifierPart   `parser:"| @@"`
	Rest        []*GrammarIdentifierPart `parser:"  ( '.' @@ )*"`
}

GrammarIdentifierPath Examples: column_name, _column, response.time, metadata.service.id, "count", 'trace.span.id'.

func (*GrammarIdentifierPath) ToString 

func (g *GrammarIdentifierPath) ToString(hasTypeSpec bool) (string, error)

ToString converts identifier path to string representation.

type GrammarInClause 

type GrammarInClause struct {
	In     string   `parser:"@'IN'"`
	LParen bool     `parser:"@'('?"`
	Groups []string `parser:"@Ident ( ',' @Ident )*"`
	RParen bool     `parser:"@')'?"`
}

GrammarInClause represents IN clause.

type GrammarInPredicate 

type GrammarInPredicate struct {
	Identifier *GrammarIdentifierPath `parser:"@@"`
	Not        *string                `parser:"@'NOT'?"`
	In         string                 `parser:"@'IN'"`
	Values     []*GrammarValue        `parser:"'(' @@? ( ',' @@ )* ')'"`
}

GrammarInPredicate represents IN/NOT IN predicate.

type GrammarLimitClause 

type GrammarLimitClause struct {
	Limit      string `parser:"@'LIMIT'"`
	Value      int    `parser:"( @Int"`
	Param      bool   `parser:"| @Param )"`
	ParamIndex int
}

GrammarLimitClause represents LIMIT clause.

type GrammarMatchTail 

type GrammarMatchTail struct {
	MatchToken string              `parser:"@'MATCH'"`
	LParen     string              `parser:"@'('"`
	Values     *GrammarMatchValues `parser:"@@"`
	Analyzer   *string             `parser:"( ',' @String"`
	Operator   *string             `parser:"  ( ',' @String )? )?"`
	RParen     string              `parser:"@')'"`
}

GrammarMatchTail represents the RHS of a MATCH predicate.

type GrammarMatchValues 

type GrammarMatchValues struct {
	Single *GrammarValue   `parser:"  @@"`
	Array  []*GrammarValue `parser:"| '(' @@ ( ',' @@ )* ')'"`
}

GrammarMatchValues represents values in MATCH.

type GrammarOffsetClause 

type GrammarOffsetClause struct {
	Offset     string `parser:"@'OFFSET'"`
	Value      int    `parser:"( @Int"`
	Param      bool   `parser:"| @Param )"`
	ParamIndex int
}

GrammarOffsetClause represents OFFSET clause.

type GrammarOrExpr 

type GrammarOrExpr struct {
	Left  *GrammarAndExpr   `parser:"@@"`
	Right []*GrammarOrRight `parser:"@@*"`
}

GrammarOrExpr represents OR expression.

type GrammarOrRight 

type GrammarOrRight struct {
	Or    string          `parser:"@'OR'"`
	Right *GrammarAndExpr `parser:"@@"`
}

GrammarOrRight represents right side of OR.

type GrammarOrderByTail 

type GrammarOrderByTail struct {
	DirOnly   *string                  `parser:"  @('ASC'|'DESC')"`
	WithIdent *GrammarOrderByWithIdent `parser:"| @@ "`
}

GrammarOrderByTail represents the tail of ORDER BY clause, Identifier with optional direction or direction only.

type GrammarOrderByWithIdent 

type GrammarOrderByWithIdent struct {
	Identifier *GrammarIdentifierPath `parser:"@@"`
	Direction  *string                `parser:"@( 'ASC' | 'DESC' )?"`
}

GrammarOrderByWithIdent represents ORDER BY with identifier and optional direction.

type GrammarPredicate 

type GrammarPredicate struct {
	Paren  *GrammarOrExpr          `parser:"  '(' @@ ')'"`
	Binary *GrammarBinaryPredicate `parser:"| @@"`
	In     *GrammarInPredicate     `parser:"| @@"`
	Having *GrammarHavingPredicate `parser:"| @@"`
}

GrammarPredicate represents a predicate.

type GrammarProjection 

type GrammarProjection struct {
	All     bool                   `parser:"  @'*'"`
	Empty   bool                   `parser:"| @'(' ')'"`
	TopN    *GrammarTopNProjection `parser:"| 'TOP' @@"`
	Columns []*GrammarColumn       `parser:"| @@ ( ',' @@ )*"`
}

GrammarProjection represents projection in SELECT.

type GrammarSelectOrderByClause 

type GrammarSelectOrderByClause struct {
	Order string             `parser:"@'ORDER'"`
	By    string             `parser:"@'BY'"`
	Tail  GrammarOrderByTail `parser:"@@"`
}

GrammarSelectOrderByClause represents ORDER BY clause in SELECT statement.

type GrammarSelectStatement 

type GrammarSelectStatement struct {
	Pos            lexer.Position
	Select         string                      `parser:"@'SELECT'"`
	Projection     *GrammarProjection          `parser:"@@"`
	From           *GrammarFromClause          `parser:"@@"`
	Time           *GrammarTimeClause          `parser:"@@?"`
	Where          *GrammarSelectWhereClause   `parser:"@@?"`
	GroupBy        *GrammarGroupByClause       `parser:"@@?"`
	OrderBy        *GrammarSelectOrderByClause `parser:"@@?"`
	WithQueryTrace *GrammarWithTraceClause     `parser:"@@?"`
	Limit          *GrammarLimitClause         `parser:"@@?"`
	Offset         *GrammarOffsetClause        `parser:"@@?"`
}

GrammarSelectStatement represents a SELECT statement in Participle grammar.

type GrammarSelectWhereClause 

type GrammarSelectWhereClause struct {
	Where string         `parser:"@'WHERE'"`
	Expr  *GrammarOrExpr `parser:"@@"`
}

GrammarSelectWhereClause represents WHERE clause.

type GrammarStageClause 

type GrammarStageClause struct {
	On      string   `parser:"@'ON'"`
	LParen  bool     `parser:"@'('?"`
	Stages  []string `parser:"@Ident ( ',' @Ident )*"`
	RParen  bool     `parser:"@')'?"`
	Stages2 string   `parser:"@'STAGES'"`
}

GrammarStageClause represents STAGES clause.

type GrammarTimeBetween 

type GrammarTimeBetween struct {
	Between string            `parser:"@'BETWEEN'"`
	Begin   *GrammarTimeValue `parser:"@@"`
	And     string            `parser:"@'AND'"`
	End     *GrammarTimeValue `parser:"@@"`
}

GrammarTimeBetween represents TIME BETWEEN.

type GrammarTimeClause 

type GrammarTimeClause struct {
	Time       string              `parser:"@'TIME'"`
	Comparator *string             `parser:"(  @( '=' | '>' | '<' | '>=' | '<=' )"`
	Value      *GrammarTimeValue   `parser:"   @@"`
	Between    *GrammarTimeBetween `parser:"| @@ )"`
}

GrammarTimeClause represents TIME clause.

type GrammarTimeValue 

type GrammarTimeValue struct {
	String  *string `parser:"  @String"`
	Integer *int64  `parser:"| @Int"`
	Param   bool    `parser:"| @Param"`
	// ParamIndex is the placeholder's positional index, assigned by Prepare and
	// meaningful only when Param is true. It keys the per-request bound overlay.
	ParamIndex int
}

GrammarTimeValue represents a time value (string, integer, or a `?` placeholder).

func (*GrammarTimeValue) ToString 

func (g *GrammarTimeValue) ToString() string

ToString converts time value to string representation.

type GrammarTopNAggregateByClause 

type GrammarTopNAggregateByClause struct {
	Aggregate string                        `parser:"@'AGGREGATE'"`
	By        string                        `parser:"@'BY'"`
	Function  *GrammarTopNAggregateFunction `parser:"@@"`
}

GrammarTopNAggregateByClause represents AGGREGATE BY clause.

type GrammarTopNAggregateFunction 

type GrammarTopNAggregateFunction struct {
	Function string `parser:"@('SUM'|'MEAN'|'AVG'|'COUNT'|'MAX'|'MIN')"`
}

GrammarTopNAggregateFunction represents aggregate functions without column (for TOP N).

type GrammarTopNOrderByClause 

type GrammarTopNOrderByClause struct {
	Order string  `parser:"@'ORDER'"`
	By    string  `parser:"@'BY'"`
	Dir   *string `parser:"@('ASC'|'DESC')?"`
}

GrammarTopNOrderByClause represents ORDER BY clause in TOP N statement.

type GrammarTopNProjection 

type GrammarTopNProjection struct {
	N            int  `parser:"( @Int"`
	NParam       bool `parser:"| @Param )"`
	NParamIndex  int
	OrderField   *GrammarIdentifierPath `parser:"@@"`
	Direction    *string                `parser:"@('ASC'|'DESC')?"`
	OtherColumns []*GrammarColumn       `parser:"  ( ',' @@ ( ',' @@ )* )?"`
}

GrammarTopNProjection represents TOP N projection.

type GrammarTopNStatement 

type GrammarTopNStatement struct {
	Pos            lexer.Position
	Show           string `parser:"@'SHOW'"`
	Top            string `parser:"@'TOP'"`
	N              int    `parser:"( @Int"`
	NParam         bool   `parser:"| @Param )"`
	NParamIndex    int
	From           *GrammarFromClause            `parser:"@@"`
	Time           *GrammarTimeClause            `parser:"@@?"`
	Where          *GrammarTopNWhereClause       `parser:"@@?"`
	AggregateBy    *GrammarTopNAggregateByClause `parser:"@@?"`
	OrderBy        *GrammarTopNOrderByClause     `parser:"@@?"`
	WithQueryTrace *GrammarWithTraceClause       `parser:"@@?"`
}

GrammarTopNStatement represents a SHOW TOP N statement.

type GrammarTopNWhereClause 

type GrammarTopNWhereClause struct {
	Where string          `parser:"@'WHERE'"`
	Expr  *GrammarAndExpr `parser:"@@"`
}

GrammarTopNWhereClause represents WHERE clause in TOP N.

type GrammarValue 

type GrammarValue struct {
	String  *string `parser:"  @String"`
	Integer *int64  `parser:"| @Int"`
	Null    bool    `parser:"| @'NULL'"`
	Param   bool    `parser:"| @Param"`
	// ParamIndex is the placeholder's positional index, assigned by Prepare and
	// meaningful only when Param is true. It keys the per-request bound overlay.
	ParamIndex int
}

GrammarValue represents a value.

type GrammarWithTraceClause 

type GrammarWithTraceClause struct {
	With       string `parser:"@'WITH'"`
	QueryTrace string `parser:"@'QUERY_TRACE'"`
}

GrammarWithTraceClause represents WITH QUERY_TRACE clause.

type PreparedStatement added in v0.11.0 

type PreparedStatement struct {
	// contains filtered or unexported fields
}

PreparedStatement is an immutable, reusable parsed query. It is safe to cache and to Bind concurrently: Prepare numbers the placeholders once, and Bind never mutates the template — the bound values live in a per-request overlay.

func Prepare added in v0.11.0 

func Prepare(query string) (*PreparedStatement, error)

Prepare parses a query and numbers its `?` placeholders so it can be bound repeatedly with different parameters without re-parsing.

func (*PreparedStatement) Bind added in v0.11.0 

func (ps *PreparedStatement) Bind(params []*modelv1.TagValue) (*BoundQuery, error)

Bind resolves params against the statement's placeholders and returns a per-request BoundQuery, leaving the template untouched, so a statement may be bound repeatedly and concurrently. Parameter positions in errors are 1-based, matching BindParams.

func (*PreparedStatement) EstimatedSize added in v0.11.0 

func (ps *PreparedStatement) EstimatedSize() int

EstimatedSize returns an approximate in-memory byte footprint of the prepared statement — its parsed grammar template and placeholder specs. It is a heuristic for cache byte-accounting (a reflection walk of the object graph), not an exact measurement, and is meant to be called off the hot path.

func (*PreparedStatement) NumPlaceholders added in v0.11.0 

func (ps *PreparedStatement) NumPlaceholders() int

NumPlaceholders reports how many `?` placeholders the statement carries. A zero count means a literal query with no reusable parameters.

type QueryType 

type QueryType int

QueryType represents the type of query. 

const (
	QueryTypeMeasure QueryType = iota
	QueryTypeStream
	QueryTypeTrace
	QueryTypeProperty
	QueryTypeTopN
)

Supported query types.

func (QueryType) String 

func (t QueryType) String() string

type TransformResult 

type TransformResult struct {
	QueryRequest proto.Message
	Original     *Grammar
	Type         QueryType
}

TransformResult is the result of transforming a Grammar into a query request.

type Transformer 

type Transformer struct {
	// contains filtered or unexported fields
}

Transformer transforms a Grammar into a native query request.

func NewTransformer 

func NewTransformer(registry metadata.Repo) *Transformer

NewTransformer creates a new Transformer with the given schema registry.

func (*Transformer) Transform 

func (t *Transformer) Transform(ctx context.Context, grammar *Grammar) (*TransformResult, error)

Transform transforms a Grammar into a native query request. The grammar must be free of unbound placeholders: either a literal query or one bound in place by BindParams. Use TransformBound for a reusable prepared statement.

func (*Transformer) TransformBound added in v0.11.0 

func (t *Transformer) TransformBound(ctx context.Context, bq *BoundQuery) (*TransformResult, error)

TransformBound transforms a bound prepared statement, reading parameter values from the per-request overlay instead of the immutable template.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.