ensql

Documentation

Index

• Constants
• Variables
• func InvalidState(expected, actual string) error
• type Condition
  • func (c Condition) IsPartial() bool
  • func (c Condition) String() string
• type ConditionGroup
  • func MakeConditionGroup(clause string) *ConditionGroup
  • func NewConditionGroup() *ConditionGroup
  • func (g *ConditionGroup) CloseParens() error
  • func (g *ConditionGroup) ConditionLeft(token Token) error
  • func (g *ConditionGroup) ConditionOperator(token Token) error
  • func (g *ConditionGroup) ConditionRight(token Token) error
  • func (g *ConditionGroup) LogicalOperator(op Operator) error
  • func (g *ConditionGroup) OpenParens() error
  • func (g *ConditionGroup) String() string
• type Operator
  • func (o Operator) String() string
• type Predicate
  • func (p Predicate) Evaluate(vars ...any) (bool, error)
  • func (p Predicate) Type() PredicateType
  • func (p Predicate) Validate() error
• type PredicateType
• type Query
  • func Parse(sql string) (Query, error)
  • func (q Query) String() string
• type QueryType
  • func (q QueryType) String() string
• type SyntaxError
  • func Error(pos int, near, msg string) *SyntaxError
  • func Errorf(pos int, near, format string, args ...interface{}) *SyntaxError
  • func (e *SyntaxError) Error() string
• type Token
  • func Tokenize(sql string) []Token
  • func (t Token) ParseBool() (bool, error)
  • func (t Token) ParseFloat(bitSize int) (float64, error)
  • func (t Token) ParseInt(base, bitSize int) (int64, error)
  • func (t Token) ParseOperator() (Operator, error)
  • func (t Token) ParseUint(base, bitSize int) (uint64, error)
• type TokenType
• type Topic

Constants

const (
	SELECT   = "SELECT"
	FROM     = "FROM"
	WHERE    = "WHERE"
	AS       = "AS"
	OFFSET   = "OFFSET"
	LIMIT    = "LIMIT"
	EQ       = "="
	NE       = "!="
	NEALT    = "<>"
	GT       = ">"
	LT       = "<"
	GTE      = ">="
	LTE      = "<="
	AND      = "AND"
	OR       = "OR"
	LIKE     = "LIKE"
	ILIKE    = "ILIKE"
	ASTERISK = "*"
	COMMA    = ","
	DOT      = "."
	LP       = "("
	RP       = ")"
	SC       = ";"
	SQUOTE   = '\''
	MINUS    = '-'
	ESCAPE   = '\\'
)

Reserved Words constants

Variables

var (
	ErrEmptyQuery             = errors.New("empty query is invalid")
	ErrMissingTopic           = errors.New("topic name cannot be empty")
	ErrUnhandledStep          = errors.New("parser has reached an unhandled state")
	ErrNoFieldsSelected       = errors.New("SELECT requires field projection or *")
	ErrInvalidSelectAllFields = errors.New("cannot select * and specify fields")
	ErrNonNumeric             = errors.New("cannot parse non-numeric token as a number")
	ErrNonBoolean             = errors.New("cannot parse non-boolean token as a bool")
	ErrNotAnOperator          = errors.New("cannot parse token as an operator")
	ErrUnknownOperator        = errors.New("unknown operator token specified")
	ErrPredicateType          = errors.New("unknown or unhandled operator in predicate")
	ErrInvalidPredicate       = errors.New("could not parse or evaluate predicate")
	ErrOpenParens             = errors.New("cannot open expression parentheses")
	ErrCloseParens            = errors.New("cannot close expression parentheses")
	ErrAppendOperator         = errors.New("cannot append operator to condition group")
	ErrAppendCondition        = errors.New("cannot append or update condition in group")
)

var (
	Empty = Token{"", EmptyToken, 0}
)

var ReservedWordType = map[string]TokenType{
	SELECT:   ReservedWord,
	FROM:     ReservedWord,
	WHERE:    ReservedWord,
	AS:       ReservedWord,
	OFFSET:   ReservedWord,
	LIMIT:    ReservedWord,
	EQ:       OperatorToken,
	NE:       OperatorToken,
	NEALT:    OperatorToken,
	GT:       OperatorToken,
	LT:       OperatorToken,
	GTE:      OperatorToken,
	LTE:      OperatorToken,
	AND:      OperatorToken,
	OR:       OperatorToken,
	LIKE:     OperatorToken,
	ILIKE:    OperatorToken,
	ASTERISK: Asterisk,
	COMMA:    Punctuation,
	DOT:      Punctuation,
	LP:       Punctuation,
	RP:       Punctuation,
	SC:       Punctuation,
}

var ReservedWords = []string{
	SELECT, FROM, WHERE, AS, OFFSET, LIMIT,
	EQ, NE, NEALT, GTE, LTE, GT, LT, AND, OR, LIKE, ILIKE,
	ASTERISK, COMMA, DOT, LP, RP, SC,
}

NOTE: GT and LT must follow GTE and LTE in this list (or in general, any word that is a prefix of another word must follow that word to ensure parsing is correct).

Functions

func InvalidState

func InvalidState(expected, actual string) error

InvalidState is a developer error; it means that the parser proceeded to a step but modified the underlying state of the parsing incorrectly. This is not a user error, e.g. due to syntax, so invalid state usually panics.

Types

type Condition

type Condition struct {
	Left     Token
	Operator Token
	Right    Token
}

Condition represents a basic expression in a where clause.

func (Condition) IsPartial

func (c Condition) IsPartial() bool

Returns true if the condition has not been completed yet.

func (Condition) String

func (c Condition) String() string

type ConditionGroup

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

ConditionGroup represents a list of subgroups, logical operators, and conditions. It is not an operational type, e.g. it cannot be used for evaluating an expression, but it is used as a substep to building a Predicate object from a series of nested conditions that are evaluated from a tokenizer.

func MakeConditionGroup

func MakeConditionGroup(clause string) *ConditionGroup

A helper method to tokenize a clause and create a condition group. Used for testing and should not be used for parsing. If the condition group creation errors, then the make function panics rather than returning an error.

func NewConditionGroup

func NewConditionGroup() *ConditionGroup

Initialize a ConditionGroup for parsing a predicate tree with precedence.

func (*ConditionGroup) CloseParens

func (g *ConditionGroup) CloseParens() error

CloseParens closes the current subgroup and returns control to the containing group. It returns an error if the last item in the parentheses is not another parentheses or a condition (e.g. parens cannot be closed after a logical operator nor can we parse empty parentheses in a sql query).

func (*ConditionGroup) ConditionLeft

func (g *ConditionGroup) ConditionLeft(token Token) error

Create a new condition with the left-token, appending it to the current condition group. Will return an error if the previous object is not a logical operator.

func (*ConditionGroup) ConditionOperator

func (g *ConditionGroup) ConditionOperator(token Token) error

Update the previous condition with an operator. Will return an error if the previous object is not a partial condition.

func (*ConditionGroup) ConditionRight

func (g *ConditionGroup) ConditionRight(token Token) error

Update the previous condition with the right token. Will return an error if the previous object is not a partial condition. Expects that the condition will no longer be partial after setting the right side value.

func (*ConditionGroup) LogicalOperator

func (g *ConditionGroup) LogicalOperator(op Operator) error

Append a logical operator to the current condition group. Will return an error if the previous object is not a closed parentheses group or a condition.

func (*ConditionGroup) OpenParens

func (g *ConditionGroup) OpenParens() error

OpenParens creates a new condition group that is a subgroup of the current group. It will return an error if the parens is not the first thing in the group or if it is not proceeded by a logical operator token.

func (*ConditionGroup) String

func (g *ConditionGroup) String() string

type Operator

type Operator uint8

Operator fields for where clauses and conditional queries

const (
	UnknownOperator Operator = iota
	Eq                       // =
	Ne                       // !=
	Gt                       // >
	Lt                       // <
	Gte                      // >=
	Lte                      // <=
	Like                     // like
	ILike                    // ilike
	And                      // AND
	Or                       // OR
)

func (Operator) String

func (o Operator) String() string

type Predicate

type Predicate struct {
	Left     any
	Operator Operator
	Right    any
}

Predicate implements a binary abstract syntax tree that can be used to evaluate complex predicate expressions that are created from where clauses. Predicates should be parsed into this abstract syntax tree with a precedence order defined.

func (Predicate) Evaluate

func (p Predicate) Evaluate(vars ...any) (bool, error)

Evaluate the predicate tree for the specified variables. TODO: from the predicate tree, extract a comparable representation that doesn't have to parse numbers/bools/etc every time and can be applied more efficiently to a large number of events.

func (Predicate) Type

func (p Predicate) Type() PredicateType

func (Predicate) Validate

func (p Predicate) Validate() error

Validate the predicate tree to ensure it is syntactically correct.

type PredicateType

type PredicateType uint8

const (
	UnknownPredicateType PredicateType = iota
	LogicalPredicate
	ComparisonPredicate
	SearchPredicate
)

type Query

type Query struct {
	Type       QueryType
	Topic      Topic
	Conditions *ConditionGroup
	Fields     []Token
	Aliases    map[string]string
	Offset     uint64
	HasOffset  bool
	Limit      uint64
	HasLimit   bool
	Raw        string
}

Query is a parsed representation of an EnSQL statement that can be used to process EnSQL requests. All elements from the SQL statement must be represented in the query (including things like comments if supported by EnSQL). The raw sql is also available on the query for debugging purposes.

func Parse

func Parse(sql string) (Query, error)

Parse an EnSQL statement to create a Query object for an Ensign SQL execution. An error is returned on syntax or validation errors that occur during parsing.

func (Query) String

func (q Query) String() string

The raw query is returned as the string representation of the query.

type QueryType

type QueryType uint8

The type of the EnSQL query (e.g. SELECT)

const (
	UnknownQueryType QueryType = iota
	SelectQuery
)

func (QueryType) String

func (q QueryType) String() string

type SyntaxError

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

func Error

func Error(pos int, near, msg string) *SyntaxError

func Errorf

func Errorf(pos int, near, format string, args ...interface{}) *SyntaxError

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

type Token

type Token struct {
	Token  string
	Type   TokenType
	Length int
}

A token represents a parsed element from the SQL and is returned from peek. The token string may not match the original string in the query (for example it might be uppercased or have quotations or whitespace stripped). When evaluating tokens, both the token type and the token itself should be used in concert to ensure correct normalization has occurred. The length is used to advance the parser index and may not match the length of the parsed token string.

func Tokenize

func Tokenize(sql string) []Token

Tokenize returns the tokens parsed from the input string with no validation or FSM. This function is primarily used by tests but can also be used by debugging tools to determine how a SQL query is being parsed.

func (Token) ParseBool

func (t Token) ParseBool() (bool, error)

Parse a boolean token as a bool using strconv.ParseBool.

func (Token) ParseFloat

func (t Token) ParseFloat(bitSize int) (float64, error)

Parse a numeric token as a float using strconv.ParseFloat. Generally, the bitSize should be 64 (e.g. double) unless otherwise defined by the schema.

func (Token) ParseInt

func (t Token) ParseInt(base, bitSize int) (int64, error)

Parse a numeric token as a signed integer using strconv.ParseInt. Generally, the base should be 10 and the bitSize should be 64 unless otherwise defined by the schema.

func (Token) ParseOperator

func (t Token) ParseOperator() (Operator, error)

func (Token) ParseUint

func (t Token) ParseUint(base, bitSize int) (uint64, error)

Parse a numeric token as an unsigned integer using strconv.ParseUint. Generally, the base should be 10 and the bitSize should be 64 unless otherwise defined by the schema.

type TokenType

type TokenType uint8

const (
	UnknownTokenType TokenType = iota
	EmptyToken
	ReservedWord
	OperatorToken
	Asterisk
	Punctuation
	Identifier
	QuotedString
	Numeric
	Boolean
)

type Topic

type Topic struct {
	Topic   string
	Schema  string
	Version uint32
}

Represents the topic and event types that are processed by the query.