contactql

Documentation

Index

• Constants
• func EvaluateQuery(env envs.Environment, query *ContactQuery, queryable Queryable) (bool, error)
• func IsQueryError(err error) (bool, error)
• type BoolCombination
  • func NewBoolCombination(op BoolOperator, children ...QueryNode) *BoolCombination
  • func (b *BoolCombination) Children() []QueryNode
  • func (b *BoolCombination) Evaluate(env envs.Environment, queryable Queryable) (bool, error)
  • func (b *BoolCombination) Operator() BoolOperator
  • func (b *BoolCombination) String() string
• type BoolOperator
• type Condition
  • func (c *Condition) Evaluate(env envs.Environment, queryable Queryable) (bool, error)
  • func (c *Condition) Operator() Operator
  • func (c *Condition) PropertyKey() string
  • func (c *Condition) PropertyType() PropertyType
  • func (c *Condition) String() string
  • func (c *Condition) Validate(env envs.Environment, resolver Resolver) error
  • func (c *Condition) Value() string
  • func (c *Condition) ValueAsDate() time.Time
  • func (c *Condition) ValueAsNumber() decimal.Decimal
• type ContactQuery
  • func ParseQuery(env envs.Environment, text string, resolver Resolver) (*ContactQuery, error)
  • func (q *ContactQuery) Evaluate(env envs.Environment, queryable Queryable) (bool, error)
  • func (q *ContactQuery) Root() QueryNode
  • func (q *ContactQuery) String() string
• type Inspection
  • func Inspect(query *ContactQuery) *Inspection
• type Operator
• type PropertyType
• type QueryError
  • func NewQueryError(code, err string, args ...interface{}) *QueryError
  • func (e *QueryError) Code() string
  • func (e *QueryError) Error() string
  • func (e *QueryError) Extra() map[string]string
• type QueryNode
• type Queryable
• type Resolver
  • func NewMockResolver(fields map[string]assets.Field, groups map[string]assets.Group) Resolver

Constants

const (
	ErrUnexpectedToken       = "unexpected_token"       // `token` the unexpected token
	ErrInvalidNumber         = "invalid_number"         // `value` the value we tried to parse as a number
	ErrInvalidDate           = "invalid_date"           // `value` the value we tried to parse as a date
	ErrInvalidLanguage       = "invalid_language"       // `value` the value we tried to parse as a language code
	ErrInvalidGroup          = "invalid_group"          // `value` the value we tried to parse as a group name
	ErrInvalidPartialName    = "invalid_partial_name"   // `min_token_length` the minimum length of token required for name contains condition
	ErrInvalidPartialURN     = "invalid_partial_urn"    // `min_value_length` the minimum length of value required for URN contains condition
	ErrUnsupportedContains   = "unsupported_contains"   // `property` the property key
	ErrUnsupportedComparison = "unsupported_comparison" // `property` the property key, `operator` one of =>, <, >=, <=
	ErrUnsupportedSetCheck   = "unsupported_setcheck"   // `property` the property key, `operator` one of =, !=
	ErrUnknownProperty       = "unknown_property"       // `property` the property key
	ErrRedactedURNs          = "redacted_urns"
)

error codes with values included in extra

const (
	AttributeUUID      = "uuid"
	AttributeID        = "id"
	AttributeName      = "name"
	AttributeLanguage  = "language"
	AttributeURN       = "urn"
	AttributeGroup     = "group"
	AttributeCreatedOn = "created_on"
)

Fixed attributes that can be searched

Functions

func EvaluateQuery

func EvaluateQuery(env envs.Environment, query *ContactQuery, queryable Queryable) (bool, error)

EvaluateQuery evaluates the given parsed query against a queryable object

func IsQueryError

func IsQueryError(err error) (bool, error)

IsQueryError is a utility to determine if the cause of an error was a query error

Types

type BoolCombination

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

BoolCombination is a AND or OR combination of multiple conditions

func NewBoolCombination

func NewBoolCombination(op BoolOperator, children ...QueryNode) *BoolCombination

NewBoolCombination creates a new boolean combination

func (*BoolCombination) Children

func (b *BoolCombination) Children() []QueryNode

Children returns the children of this boolean combination

func (*BoolCombination) Evaluate

func (b *BoolCombination) Evaluate(env envs.Environment, queryable Queryable) (bool, error)

Evaluate returns whether this combination evaluates to true or false

func (*BoolCombination) Operator

func (b *BoolCombination) Operator() BoolOperator

Operator returns the type of boolean operator this combination is

func (*BoolCombination) String

func (b *BoolCombination) String() string

type BoolOperator

type BoolOperator string

BoolOperator is a boolean operator (and or or)

const (
	// BoolOperatorAnd is our constant for an AND operation
	BoolOperatorAnd BoolOperator = "and"

	// BoolOperatorOr is our constant for an OR operation
	BoolOperatorOr BoolOperator = "or"
)

type Condition

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

Condition represents a comparison between a keywed value on the contact and a provided value

func (*Condition) Evaluate

func (c *Condition) Evaluate(env envs.Environment, queryable Queryable) (bool, error)

Evaluate evaluates this condition against the queryable contact

func (*Condition) Operator

func (c *Condition) Operator() Operator

Operator returns the type of comparison being made

func (*Condition) PropertyKey

func (c *Condition) PropertyKey() string

PropertyKey returns the key for the property being queried

func (*Condition) PropertyType

func (c *Condition) PropertyType() PropertyType

PropertyType returns the type (attribute, scheme, field)

func (*Condition) String

func (c *Condition) String() string

func (*Condition) Validate

func (c *Condition) Validate(env envs.Environment, resolver Resolver) error

Validate checks that this condition is valid (and thus can be evaluated)

func (*Condition) Value

func (c *Condition) Value() string

Value returns the value being compared against

func (*Condition) ValueAsDate

func (c *Condition) ValueAsDate() time.Time

ValueAsDate returns the value as a date if condition is datetime

func (*Condition) ValueAsNumber

func (c *Condition) ValueAsNumber() decimal.Decimal

ValueAsNumber returns the value as a number if value type is number

type ContactQuery

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

ContactQuery is a parsed contact QL query

func ParseQuery

func ParseQuery(env envs.Environment, text string, resolver Resolver) (*ContactQuery, error)

ParseQuery parses a ContactQL query from the given input

func (*ContactQuery) Evaluate

func (q *ContactQuery) Evaluate(env envs.Environment, queryable Queryable) (bool, error)

Evaluate returns whether the given queryable matches this query

func (*ContactQuery) Root

func (q *ContactQuery) Root() QueryNode

Root returns the root node of this query

func (*ContactQuery) String

func (q *ContactQuery) String() string

String returns the pretty formatted version of this query

type Inspection

type Inspection struct {
	Attributes   []string                 `json:"attributes"`
	Schemes      []string                 `json:"schemes"`
	Fields       []*assets.FieldReference `json:"fields"`
	Groups       []*assets.GroupReference `json:"groups"`
	AllowAsGroup bool                     `json:"allow_as_group"`
}

Inspection holds the result of inspecting a query

func Inspect

func Inspect(query *ContactQuery) *Inspection

Inspect extracts information about a query

type Operator

type Operator string

Operator is a comparison operation between two values in a condition

const (
	OpEqual              Operator = "="
	OpNotEqual           Operator = "!="
	OpContains           Operator = "~"
	OpGreaterThan        Operator = ">"
	OpLessThan           Operator = "<"
	OpGreaterThanOrEqual Operator = ">="
	OpLessThanOrEqual    Operator = "<="
)

supported operators

type PropertyType

type PropertyType string

PropertyType is the type of the lefthand side of a condition

const (
	// PropertyTypeAttribute is builtin property
	PropertyTypeAttribute PropertyType = "attribute"

	// PropertyTypeScheme is a URN scheme
	PropertyTypeScheme PropertyType = "scheme"

	// PropertyTypeField is a custom contact field
	PropertyTypeField PropertyType = "field"
)

type QueryError

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

QueryError is used when an error is a result of an invalid query

func NewQueryError

func NewQueryError(code, err string, args ...interface{}) *QueryError

NewQueryError creates a new query error

func (*QueryError) Code

func (e *QueryError) Code() string

Code returns a code representing this error condition

func (*QueryError) Error

func (e *QueryError) Error() string

Error returns the error message

func (*QueryError) Extra

func (e *QueryError) Extra() map[string]string

Extra returns additional data about the error

type QueryNode

type QueryNode interface {
	fmt.Stringer
	Evaluate(envs.Environment, Queryable) (bool, error)
}

QueryNode is the base for nodes in our query parse tree

type Queryable

type Queryable interface {
	QueryProperty(envs.Environment, string, PropertyType) []interface{}
}

Queryable is the interface objects must implement queried

type Resolver

type Resolver interface {
	ResolveField(key string) assets.Field
	ResolveGroup(name string) assets.Group
}

Resolver provides functions for resolving fields and groups referenced in queries

func NewMockResolver

func NewMockResolver(fields map[string]assets.Field, groups map[string]assets.Group) Resolver

NewMockResolver creates a new mock resolver for fields and groups