logchefql

package
v1.5.0 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2026 License: AGPL-3.0 Imports: 7 Imported by: 0

Documentation

Overview

Package logchefql provides parsing and SQL generation for the LogchefQL query language. LogchefQL is a simple query language for filtering logs, designed to be user-friendly while translating to efficient ClickHouse SQL queries.

Index

Constants

View Source 
const (
	ErrUnterminatedString     = "UNTERMINATED_STRING"
	ErrUnexpectedEnd          = "UNEXPECTED_END"
	ErrUnexpectedToken        = "UNEXPECTED_TOKEN"
	ErrExpectedOperator       = "EXPECTED_OPERATOR"
	ErrExpectedValue          = "EXPECTED_VALUE"
	ErrExpectedClosingParen   = "EXPECTED_CLOSING_PAREN"
	ErrUnknownOperator        = "UNKNOWN_OPERATOR"
	ErrUnknownBooleanOperator = "UNKNOWN_BOOLEAN_OPERATOR"
	ErrInvalidTokenType       = "INVALID_TOKEN_TYPE"
	ErrMissingBooleanOperator = "MISSING_BOOLEAN_OPERATOR"
	ErrTrailingTokens         = "TRAILING_TOKENS"
	ErrInvalidTimeFormat      = "INVALID_TIME_FORMAT"
	ErrInvalidTimezone        = "INVALID_TIMEZONE"
	ErrInvalidIdentifier      = "INVALID_IDENTIFIER"
)

Error codes for parse errors

Variables

This section is empty.

Functions

func BuildFullQuery 

func BuildFullQuery(params QueryBuildParams) (string, error)

BuildFullQuery builds a complete SQL query from LogchefQL with time range and other parameters. This is used when executing the query against ClickHouse.

func DetectQueryType added in v1.1.0 

func DetectQueryType(query string) string

func TranslateToSQLConditions 

func TranslateToSQLConditions(query string, schema *Schema) string

TranslateToSQLConditions is a convenience function that returns just the SQL string. Returns empty string on error.

Types

type ASTNode 

type ASTNode interface {
	// contains filtered or unexported methods
}

ASTNode is the interface for all AST node types

func ConvertToAST added in v1.1.0 

func ConvertToAST(pq *PQuery) ASTNode

ConvertToAST converts the Participle AST to the existing AST types

type BoolOperator 

type BoolOperator string

BoolOperator represents boolean operators for combining conditions 

const (
	BoolAnd BoolOperator = "AND"
	BoolOr  BoolOperator = "OR"
)

func ParseBoolOperator 

func ParseBoolOperator(s string) (BoolOperator, bool)

ParseBoolOperator converts a string to a BoolOperator, returning ok=false if invalid

type ColumnInfo 

type ColumnInfo struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

ColumnInfo represents column metadata from the schema

type ExpressionNode 

type ExpressionNode struct {
	Key      interface{} `json:"key"` // string or NestedField
	Operator Operator    `json:"operator"`
	Value    interface{} `json:"value"` // string, number, bool, or nil
	Quoted   bool        `json:"quoted,omitempty"`
}

ExpressionNode represents a single comparison expression (e.g., field="value")

type FilterCondition 

type FilterCondition struct {
	Field    string `json:"field"`
	Operator string `json:"operator"`
	Value    string `json:"value"`
	IsRegex  bool   `json:"is_regex"`
}

FilterCondition represents a single filter condition extracted from the query This is used for the field sidebar feature

func GetConditionsFromQuery 

func GetConditionsFromQuery(query string) []FilterCondition

GetConditionsFromQuery extracts filter conditions from a LogchefQL query. This is useful for the field sidebar feature.

type GroupNode 

type GroupNode struct {
	Children []ASTNode `json:"children"`
}

GroupNode represents a parenthesized group of expressions

type LogicalNode 

type LogicalNode struct {
	Operator BoolOperator `json:"operator"`
	Children []ASTNode    `json:"children"`
}

LogicalNode represents a logical combination of nodes (AND/OR)

type NestedField 

type NestedField struct {
	Base string   `json:"base"`
	Path []string `json:"path"`
}

NestedField represents a field with nested path access (e.g., log.level or attributes["key"])

type Operator 

type Operator string

Operator represents comparison operators in LogchefQL 

const (
	OpEquals    Operator = "="
	OpNotEquals Operator = "!="
	OpRegex     Operator = "~"
	OpNotRegex  Operator = "!~"
	OpGT        Operator = ">"
	OpLT        Operator = "<"
	OpGTE       Operator = ">="
	OpLTE       Operator = "<="
)

func ParseOperator 

func ParseOperator(s string) (Operator, bool)

ParseOperator converts a string to an Operator, returning ok=false if invalid

type PAndExpr added in v1.1.0 

type PAndExpr struct {
	Left  *PTerm      `parser:"@@"`
	Right []*PAndTail `parser:"@@*"`
}

PAndExpr handles AND precedence (higher than OR)

type PAndTail added in v1.1.0 

type PAndTail struct {
	Right *PTerm `parser:"'and':Ident @@"`
}

PAndTail captures "and <term>"

type PComparison added in v1.1.0 

type PComparison struct {
	Field    *PFieldPath `parser:"@@"`
	Operator string      `parser:"@Operator"`
	Value    *PValue     `parser:"@@"`
}

type PFieldPath added in v1.1.0 

type PFieldPath struct {
	First *PPathSegment   `parser:"@@"`
	Rest  []*PPathSegment `parser:"( Dot @@ )*"`
}

type POrExpr added in v1.1.0 

type POrExpr struct {
	Left  *PAndExpr  `parser:"@@"`
	Right []*POrTail `parser:"@@*"`
}

POrExpr handles OR precedence (lowest)

type POrTail added in v1.1.0 

type POrTail struct {
	Right *PAndExpr `parser:"'or':Ident @@"`
}

POrTail captures "or <and_expr>"

type PPathSegment added in v1.1.0 

type PPathSegment struct {
	Ident  *string `parser:"( @Ident"`
	Quoted *string `parser:"| @String )"`
}

type PQuery added in v1.1.0 

type PQuery struct {
	Where  *POrExpr       `parser:"@@?"`
	Select []*PSelectItem `parser:"( Pipe @@+ )?"`
}

PQuery is the top-level query with optional WHERE clause and optional SELECT (pipe)

func ParseLogchefQL added in v1.1.0 

func ParseLogchefQL(input string) (*PQuery, error)

ParseLogchefQL parses a LogchefQL query string into the Participle AST

type PSelectItem added in v1.1.0 

type PSelectItem struct {
	Field *PFieldPath `parser:"@@"`
}

type PTerm added in v1.1.0 

type PTerm struct {
	Group      *POrExpr     `parser:"( LParen @@ RParen"`
	Comparison *PComparison `parser:"| @@ )"`
}

PTerm is either a grouped expression or a comparison

type PValue added in v1.1.0 

type PValue struct {
	String *string  `parser:"( @String"`
	Number *float64 `parser:"| @Number"`
	Ident  *string  `parser:"| @Ident )"`
}

PValue can be a string, number, or bare identifier (for booleans/null/unquoted values)

type ParseError 

type ParseError struct {
	Code     string    `json:"code"`
	Message  string    `json:"message"`
	Position *Position `json:"position,omitempty"`
}

ParseError represents an error encountered during parsing

func (*ParseError) Error 

func (e *ParseError) Error() string

type Position 

type Position struct {
	Line   int `json:"line"`
	Column int `json:"column"`
}

Position represents a position in the source query string

type QueryBuildParams 

type QueryBuildParams struct {
	LogchefQL      string  // The LogchefQL query string
	Schema         *Schema // Optional schema for type-aware SQL generation
	TableName      string  // Fully qualified table name (database.table)
	TimestampField string  // Name of the timestamp column
	StartTime      string  // Start time in format "2006-01-02 15:04:05"
	EndTime        string  // End time in format "2006-01-02 15:04:05"
	Timezone       string  // Timezone for time conversion
	Limit          int     // Result limit
}

QueryBuildParams contains parameters for building a full SQL query

type QueryNode 

type QueryNode struct {
	Where  ASTNode       `json:"where,omitempty"`
	Select []SelectField `json:"select,omitempty"`
}

QueryNode represents the top-level query with optional WHERE and SELECT

type SQLGenerator 

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

SQLGenerator converts an AST into ClickHouse SQL

func NewSQLGenerator 

func NewSQLGenerator(schema *Schema) *SQLGenerator

NewSQLGenerator creates a new SQL generator with optional schema

func (*SQLGenerator) Generate 

func (g *SQLGenerator) Generate(node ASTNode) string

Generate converts an AST node to SQL WHERE clause conditions

func (*SQLGenerator) GenerateSelectClause 

func (g *SQLGenerator) GenerateSelectClause(selectFields []SelectField, defaultTimestampField string) string

GenerateSelectClause generates the SELECT clause from select fields

type Schema 

type Schema struct {
	Columns []ColumnInfo `json:"columns"`
}

Schema represents table schema information for type-aware SQL generation

type SelectField 

type SelectField struct {
	Field interface{} `json:"field"` // string or NestedField
	Alias string      `json:"alias,omitempty"`
}

SelectField represents a field selection with optional alias

type Token 

type Token struct {
	Type       TokenType `json:"type"`
	Value      string    `json:"value"`
	Position   Position  `json:"position"`
	Quoted     bool      `json:"quoted,omitempty"`
	Incomplete bool      `json:"incomplete,omitempty"`
}

Token represents a lexical token from the tokenizer

type TokenType 

type TokenType string

TokenType represents the type of a lexical token 

const (
	TokenKey      TokenType = "key"
	TokenOperator TokenType = "operator"
	TokenValue    TokenType = "value"
	TokenParen    TokenType = "paren"
	TokenBool     TokenType = "bool"
	TokenPipe     TokenType = "pipe"
)

type TranslateResult 

type TranslateResult struct {
	SQL          string            `json:"sql"`                     // WHERE clause conditions only
	SelectClause string            `json:"select_clause,omitempty"` // Custom SELECT clause if pipe operator used
	Valid        bool              `json:"valid"`
	Error        *ParseError       `json:"error,omitempty"`
	Conditions   []FilterCondition `json:"conditions"`
	FieldsUsed   []string          `json:"fields_used"`
}

TranslateResult represents the result of translating a LogchefQL query

func Translate 

func Translate(query string, schema *Schema) *TranslateResult

Translate parses a LogchefQL query and returns the SQL translation with metadata.

type ValidateResult 

type ValidateResult struct {
	Valid bool        `json:"valid"`
	Error *ParseError `json:"error,omitempty"`
}

ValidateResult represents the result of validating a LogchefQL query

func Validate 

func Validate(query string) *ValidateResult

Validate checks if a LogchefQL query is syntactically valid.

func ValidateWithDetails 

func ValidateWithDetails(query string) *ValidateResult

ValidateWithDetails is an alias for Validate that returns detailed error information.

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.