pql

package
v0.22.7 Latest Latest
Warning

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

 Go to latest Published: Jul 6, 2024 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Copyright 2022 Molecula Corp. (DBA FeatureBase). SPDX-License-Identifier: Apache-2.0

Copyright 2022 Molecula Corp. (DBA FeatureBase). SPDX-License-Identifier: Apache-2.0

Copyright 2022 Molecula Corp. (DBA FeatureBase). SPDX-License-Identifier: Apache-2.0

Package pql defines the Pilosa Query Language.

Copyright 2022 Molecula Corp. (DBA FeatureBase). SPDX-License-Identifier: Apache-2.0

Copyright 2022 Molecula Corp. (DBA FeatureBase). SPDX-License-Identifier: Apache-2.0

Index

Constants

View Source 
const (
	// PrecallNone calls can be executed per shard.
	PrecallNone = CallType(iota)

	// PrecallGlobal indicates a call which must be run globally *before*
	// distributing the call to other shards. Example: A Distinct query,
	// where every shard could potentially produce results for any shard,
	// so you have to produce the results up front.
	// These are processed directly when inside of a count operation.
	PrecallGlobal

	// PrecallPerNode indicates a call which needs to be run per-shard
	// in a way that lets it be done on each shard, but where it should
	// be done prior to spawning per-shard goroutines. Example:
	// A cross-index query, where each local shard may or may not need
	// to get data from a remote node, but batches of shards can
	// probably be gotten from the same remote node.
	PrecallPerNode
)

Variables

This section is empty.

Functions

func CopyArgs 

func CopyArgs(m map[string]interface{}) map[string]interface{}

CopyArgs returns a copy of m.

func CopyArgsDecimalToFloat 

func CopyArgsDecimalToFloat(m map[string]interface{}) map[string]interface{}

CopyArgsDecimalToFloat makes a copy of m, but in the process, replaces any Decimal values with Float64 values.

func IsReservedArg 

func IsReservedArg(name string) bool

func MinMax 

func MinMax(scale int64) (Decimal, Decimal)

MinMax returns the minimum and maximum values supported by the provided scale.

func NewParser 

func NewParser(r io.Reader) *parser

NewParser returns a new instance of Parser.

func Pow10 

func Pow10(p int64) int64

Pow10 is a function which can be used in place of math.Pow10() to avoid the float64 logic. Note that only powers 0-18 are currently supported; anything else will return 0, which is probably going to result in incorrect values.

func Pretty 

func Pretty(pretty bool) func(*PQL) error

func Size 

func Size(size int) func(*PQL) error

func Unquote 

func Unquote(s string) (string, error)

Unquote interprets s as a single-quoted, double-quoted, or backquoted Go string literal, returning the string value that s quotes. It is a copy of stdlib's strconv.Unquote, but modified so that if s is single-quoted, it can still be a string rather than only character literal. This version of Unquote also accepts unquoted strings and passes them back unchanged.

Types

type Call 

type Call struct {
	Name        string
	Args        map[string]interface{}
	Children    []*Call
	Type        CallType
	Precomputed map[uint64]interface{}
}

Call represents a function call in the AST. The Precomputed field is used by the executor to handle non-standard call types; it does these by actually executing them separately, then replacing them in the call tree with a new call using the special precomputed type, with the Precomputed field set to a map from shards to results.

func (*Call) Arg 

func (c *Call) Arg(key string) (interface{}, bool)

Arg is for reading the value at key from call.Args. If the key is not in Call.Args, the value of the returned bool will be false.

func (*Call) ArgString 

func (c *Call) ArgString(key string) string

func (*Call) BoolArg 

func (c *Call) BoolArg(key string) (bool, bool, error)

BoolArg is for reading the value at key from call.Args as a bool. If the key is not in Call.Args, the value of the returned bool will be false, and the error will be nil. The value is assumed to be a bool. An error is returned if the value is not a bool.

func (*Call) CallArg 

func (c *Call) CallArg(key string) (*Call, bool, error)

CallArg is for reading the value at key from call.Args as a Call. If the key is not in Call.Args, the value of the returned value will be nil, and the error will be nil. An error is returned if the value is not a Call.

func (*Call) CallIndex 

func (c *Call) CallIndex() string

CallIndex handles guessing whether we've been asked to apply this to a different index. An empty string means "no".

func (*Call) CheckCallInfo 

func (c *Call) CheckCallInfo() error

CheckCallInfo tries to validate that arguments are correct and valid for the given call. It does not guarantee checking all possible errors; for instance, if an argument is a field name, CheckCallInfo can't validate that the field exists. It also updates with information like whether the call is expected to require precalling.

func (*Call) Clone 

func (c *Call) Clone() *Call

Clone returns a copy of c.

func (*Call) ExpandVars 

func (c *Call) ExpandVars(vars map[string]interface{}) ([]*Call, error)

ExpandVars recursively replaces variables in the call with their values.

func (*Call) FieldArg 

func (c *Call) FieldArg() (string, error)

FieldArg determines which key-value pair contains the field and rowID, in the case of arguments like Set(colID, field=rowID). Returns the field as a string if present, or an error if not.

func (*Call) FieldEquality 

func (c *Call) FieldEquality(k string) (isNull bool, value uint64, equal bool, err error)

FieldEquality returns an equality test suitable for a non-BSI field. Given a field name, it returns an equality test from the corresponding argument. An equality test indicates whether the test is actually against null, or if not what specific uint64 value it's against, and whether it's an equal or non-equal test. This exists mostly to be able to extract `== null` and `!= null` tests consistently even for non-BSI fields.

func (*Call) FieldRange 

func (c *Call) FieldRange(k string) (op Token, value interface{}, err error)

FieldRange yields the range test corresponding to the given key, which means either it's a Condition, or it's just a raw equality to a value, which we treat as {EQ, []any{value}}. This is suitable for use with BSI fields, which generally get their operations as Conditions, and simplifies the caller side of this.

func (*Call) FirstStringArg 

func (c *Call) FirstStringArg(keys ...string) (string, error)

func (*Call) HasCall 

func (c *Call) HasCall(name string) bool

HasCall returns true if q contains the given call name.

func (*Call) HasConditionArg 

func (c *Call) HasConditionArg() bool

HasConditionArg returns true if any arg is a conditional.

func (*Call) IntArg 

func (c *Call) IntArg(key string) (int64, bool, error)

IntArg is for reading the value at key from call.Args as an int64. If the key is not in Call.Args, the value of the returned bool will be false, and the error will be nil. The value is assumed to be a unt64 or an int64 and then cast to an int64. An error is returned if the value is not an int64 or uint64.

func (*Call) IsWrite 

func (c *Call) IsWrite() bool

IsWrite returns whether the call is a mutating call.

func (*Call) String 

func (c *Call) String() string

String returns the string representation of the call.

func (*Call) StringArg 

func (c *Call) StringArg(key string) (string, bool, error)

func (*Call) TranslateInfo 

func (c *Call) TranslateInfo(columnLabel, rowLabel string) (colKey, rowKey, fieldName string)

TranslateInfo returns the relevant translation fields.

func (*Call) UintArg 

func (c *Call) UintArg(key string) (uint64, bool, error)

UintArg is for reading the value at key from call.Args as a uint64. If the key is not in Call.Args, the value of the returned bool will be false, and the error will be nil. The value is assumed to be a uint64 or an int64 and then cast to a uint64. An error is returned if the value is not an int64 or uint64.

func (*Call) UintSliceArg 

func (c *Call) UintSliceArg(key string) ([]uint64, bool, error)

UintSliceArg reads the value at key from call.Args as a slice of uint64. If the key is not in Call.Args, the value of the returned bool will be false, and the error will be nil. If the value is a slice of int64 it will convert it to []uint64. Otherwise, if it is not a []uint64 it will return an error.

func (*Call) Writable 

func (c *Call) Writable() bool

Writable returns true if call is mutable (e.g. can write new translation keys)

type CallType 

type CallType byte

CallType represents a Call type such as "global" or "per-node". Some call types may require special handling, which needs to occur before distributing processing to individual shards.

type Condition 

type Condition struct {
	Op    Token
	Value interface{}
}

Condition represents an operation & value. When used in an argument map it represents a binary expression.

func (*Condition) Int64SliceValue 

func (cond *Condition) Int64SliceValue() ([]int64, bool)

func (*Condition) Int64Value 

func (cond *Condition) Int64Value() (int64, bool)

func (*Condition) String 

func (cond *Condition) String() string

String returns the string representation of the condition.

func (*Condition) StringSliceValue 

func (cond *Condition) StringSliceValue() ([]string, bool)

StringSliceValue returns the value(s) of the conditional as a slice of strings. For example, if cond.Value is []int64{-10,20}, this will return []string{"-10","20"}. It also returns a bool indicating that the conversion succeeded.

func (*Condition) StringWithSubj 

func (cond *Condition) StringWithSubj(subj string) string

StringWithSubj returns the string representation of the condition including the provided subject.

func (*Condition) Uint64SliceValue 

func (cond *Condition) Uint64SliceValue() ([]uint64, bool)

func (*Condition) Uint64Value 

func (cond *Condition) Uint64Value() (uint64, bool)

type Decimal 

type Decimal struct {
	Scale int64
	// contains filtered or unexported fields
}

Decimal represents a decimal value; the intention is to avoid relying on float64, and the primary purpose is to have a predictable way to encode such values used in query strings. Scale is the number of digits to the right of the decimal point. Precision is currently not considered; precision, for our purposes is implied to be the complete, known value.

func AddDecimal 

func AddDecimal(a, b Decimal) Decimal

AddDecimal adds a and b together and returns a new Decimal with the computed sum.

If the Scale of a and b don't match, the returned Decimal will have the smallest Scale needed to precisely represent the sum.

func DivideDecimal 

func DivideDecimal(a, b Decimal) Decimal

DivideDecimal multiplies a by b and returns a new Decimal.

If the Scale of a and b don't match, the returned Decimal will have the smallest Scale needed to precisely represent the sum.

func FromFloat64 

func FromFloat64(f float64) Decimal

FromFloat64 converts a float into a Decimal.

func FromFloat64WithScale 

func FromFloat64WithScale(f float64, scale int) (Decimal, error)

FromFloat64WithScale converts a float into a Decimal.

func FromInt64 

func FromInt64(i int64, scale int64) Decimal

FromInt64 converts an int64 into a Decimal.

func MultiplyDecimal 

func MultiplyDecimal(a, b Decimal) Decimal

MultiplyDecimal multiplies a by b and returns a new Decimal.

If the Scale of a and b don't match, the returned Decimal will have the smallest Scale needed to precisely represent the sum.

func NewDecimal 

func NewDecimal(value, scale int64) Decimal

NewDecimal returns a Decimal based on the provided arguments.

func ParseDecimal 

func ParseDecimal(s string) (Decimal, error)

ParseDecimal parses a string into a Decimal.

func SubtractDecimal 

func SubtractDecimal(a, b Decimal) Decimal

SubtractDecimal subtracts b from a and returns a new Decimal.

If the Scale of a and b don't match, the returned Decimal will have the smallest Scale needed to precisely represent the sum.

func (Decimal) Clone 

func (d Decimal) Clone() (r *Decimal)

func (Decimal) EqualTo 

func (d Decimal) EqualTo(d2 Decimal) bool

EqualTo returns true if d == d2.

func (Decimal) Float64 

func (d Decimal) Float64() float64

Float64 returns d as a float64. TODO: this could potentially lose precision; we should audit its use and protect against unexpected results. If d.value cannot be represented as an int64, results are undefined.

func (Decimal) GreaterThan 

func (d Decimal) GreaterThan(d2 Decimal) bool

GreaterThan returns true if d > d2.

func (Decimal) GreaterThanOrEqualTo 

func (d Decimal) GreaterThanOrEqualTo(d2 Decimal) bool

GreaterThanOrEqualTo returns true if d >= d2.

func (Decimal) IsValid 

func (d Decimal) IsValid() bool

IsValid returns true if the decimal does not break any assumption or resrictions on input.

func (Decimal) LessThan 

func (d Decimal) LessThan(d2 Decimal) bool

LessThan returns true if d < d2.

func (Decimal) LessThanOrEqualTo 

func (d Decimal) LessThanOrEqualTo(d2 Decimal) bool

LessThanOrEqualTo returns true if d <= d2.

func (Decimal) MarshalJSON 

func (d Decimal) MarshalJSON() ([]byte, error)

MarshalJSON is a custom marshaller for the Decimal type.

func (Decimal) MarshalYAML 

func (d Decimal) MarshalYAML() (interface{}, error)

MarshalYAML is a custom marshaller for the Decimal type.

func (*Decimal) SetBigIntValue 

func (d *Decimal) SetBigIntValue(v *big.Int)

func (*Decimal) SetValue 

func (d *Decimal) SetValue(v int64)

func (Decimal) String 

func (d Decimal) String() string

String returns the string representation of the decimal.

func (Decimal) SupportedByScale 

func (d Decimal) SupportedByScale(scale int64) bool

SupportedByScale returns true if d can be represented by a decimal based on scale. For example: scale = 2: min: -92233720368547758.08 max: 92233720368547758.07 would not support: NewDecimal(9223372036854775807, 0)

func (Decimal) ToInt64 

func (d Decimal) ToInt64(scale int64) int64

ToInt64 returns d as an int64 adjusted to the provided scale. If d.value cannot be represented as an int64, results are undefined.

func (*Decimal) UnmarshalJSON 

func (d *Decimal) UnmarshalJSON(data []byte) error

UnmarshalJSON is a custom unmarshaller for the Decimal type. The intention is to avoid the use of float64 anywhere, so this unmarhaller parses the decimal out of the byte string.

func (*Decimal) UnmarshalYAML 

func (d *Decimal) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML is a custom unmarshaller for the Decimal type.

func (*Decimal) Value 

func (d *Decimal) Value() big.Int

type PQL 

type PQL struct {
	Query

	Buffer string

	Pretty bool
	// contains filtered or unexported fields
}

func (*PQL) AST 

func (t *PQL) AST() *node32

func (*PQL) Add 

func (t *PQL) Add(rule pegRule, begin, end, index uint32)

func (*PQL) Execute 

func (p *PQL) Execute()

func (*PQL) Init 

func (p *PQL) Init(options ...func(*PQL) error) error

func (*PQL) Parse 

func (p *PQL) Parse(rule ...int) error

func (*PQL) PrettyPrintSyntaxTree 

func (t *PQL) PrettyPrintSyntaxTree(buffer string)

func (*PQL) Print 

func (t *PQL) Print()

func (*PQL) PrintSyntaxTree 

func (p *PQL) PrintSyntaxTree()

func (*PQL) Reset 

func (p *PQL) Reset()

func (*PQL) SprintSyntaxTree 

func (p *PQL) SprintSyntaxTree() string

func (*PQL) Tokens 

func (t *PQL) Tokens() []token32

func (*PQL) Trim 

func (t *PQL) Trim(length uint32)

func (*PQL) WriteSyntaxTree 

func (p *PQL) WriteSyntaxTree(w io.Writer)

type Query 

type Query struct {
	Calls []*Call
	// contains filtered or unexported fields
}

Query represents a PQL query.

func ParseString 

func ParseString(s string) (*Query, error)

ParseString parses s into a query.

func (*Query) ExpandVars 

func (q *Query) ExpandVars(vars map[string]interface{}) (*Query, error)

ExpandVars recursively replaces variables in the query with their values.

func (*Query) HasCall 

func (q *Query) HasCall(name string) bool

HasCall returns true if q contains the given call name.

func (*Query) String 

func (q *Query) String() string

String returns a string representation of the query.

func (*Query) WriteCallN 

func (q *Query) WriteCallN() int

WriteCallN returns the number of mutating calls.

type Token 

type Token int

Token is a lexical token of the PQL language. 

const (
	// Special tokens
	ILLEGAL Token = iota

	ASSIGN // =
	EQ     // ==
	NEQ    // !=
	LT     // <
	LTE    // <=
	GT     // >
	GTE    // >=

	BETWEEN // ><  (this is like a <= x <= b)

	// not used in lexing/parsing, but so that the parser can signal
	// to the executor how to treat the arguments. We used to just add
	// 1 to the arguments if they were LT so the executor could assume
	// it was always <=, <=, but then we needed to support
	// floats/decimals and couldn't do that any more.
	BTWN_LT_LTE // a < x <= b
	BTWN_LTE_LT // a <= x < b
	BTWN_LT_LT  // a < x < b
)

func (Token) String 

func (tok Token) String() string

String returns the string representation of the token.

type Variable 

type Variable struct {
	Name string
}

Variable represents a placeholder variable in a query.

func NewVariable 

func NewVariable(name string) *Variable

NewVariable returns a new instance of Variable.

func (*Variable) String 

func (v *Variable) String() string

String returns the string representation of v.

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.