contactql

Documentation

Index

• Constants
• func EvaluateQuery(env envs.Environment, query *ContactQuery, queryable Queryable) bool
• func IsQueryError(err error) (bool, error)
• type BoolCombination
  • func NewBoolCombination(op BoolOperator, children ...QueryNode) *BoolCombination
  • func (b *BoolCombination) Children() []QueryNode
  • func (b *BoolCombination) Operator() BoolOperator
  • func (b *BoolCombination) String() string
• type BoolOperator
• type Condition
  • func (c *Condition) Operator() Operator
  • func (c *Condition) PropertyKey() string
  • func (c *Condition) PropertyType() PropertyType
  • func (c *Condition) String() string
  • func (c *Condition) Value() string
  • func (c *Condition) ValueAsDate(env envs.Environment) (time.Time, error)
  • func (c *Condition) ValueAsGroup(resolver Resolver) assets.Group
  • func (c *Condition) ValueAsNumber() (decimal.Decimal, error)
• type ContactQuery
  • func ParseQuery(env envs.Environment, text string, resolver Resolver) (*ContactQuery, error)
  • func (q *ContactQuery) Resolver() Resolver
  • 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"
	AttributeTickets    = "tickets"
	AttributeCreatedOn  = "created_on"
	AttributeLastSeenOn = "last_seen_on"
)

Fixed attributes that can be searched

Functions

func EvaluateQuery

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

EvaluateQuery evaluates the given query against the given queryable. That query must have been parsed with a resolver to ensure all fields and groups resolve. If not function panics.

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) 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) 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) Value

func (c *Condition) Value() string

Value returns the value being compared against

func (*Condition) ValueAsDate

func (c *Condition) ValueAsDate(env envs.Environment) (time.Time, error)

ValueAsDate returns the value as a date if possible, or an error if not

func (*Condition) ValueAsGroup

func (c *Condition) ValueAsGroup(resolver Resolver) assets.Group

ValueAsGroup returns the value as a date if possible, or an error if not

func (*Condition) ValueAsNumber

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

ValueAsNumber returns the value as a number if possible, or an error if not

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. If resolver is provided then we validate against it to ensure that fields and groups exist. If not provided then still validate what we can.

func (*ContactQuery) Resolver

func (q *ContactQuery) Resolver() Resolver

Resolver returns the optional resolver this query was parsed with

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
	// contains filtered or unexported methods
}

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