query

Documentation

Overview

Package query provides the datatypes for construction queries and working with their results.

The base for every query is the `Query` type:

q := query.Query{
	// ...
}

Index

• type Aggregation
• type AggregationOp
  • func (op AggregationOp) MarshalJSON() ([]byte, error)
  • func (i AggregationOp) String() string
  • func (op *AggregationOp) UnmarshalJSON(b []byte) (err error)
• type Entry
• type EntryGroup
• type EntryGroupAgg
• type Filter
• type FilterOp
  • func (op FilterOp) MarshalJSON() ([]byte, error)
  • func (i FilterOp) String() string
  • func (op *FilterOp) UnmarshalJSON(b []byte) (err error)
• type History
• type Interval
• type Kind
  • func (k Kind) EncodeValues(key string, v *url.Values) error
  • func (k Kind) MarshalJSON() ([]byte, error)
  • func (i Kind) String() string
  • func (k *Kind) UnmarshalJSON(b []byte) error
• type Message
• type MessageCode
  • func (i MessageCode) String() string
  • func (mc *MessageCode) UnmarshalJSON(b []byte) error
• type MessagePriority
  • func (i MessagePriority) String() string
  • func (mp *MessagePriority) UnmarshalJSON(b []byte) error
• type Options
• type Order
• type Projection
• type Query
  • func (q Query) MarshalJSON() ([]byte, error)
  • func (q *Query) UnmarshalJSON(b []byte) error
• type Result
• type Status
  • func (s Status) MarshalJSON() ([]byte, error)
  • func (s *Status) UnmarshalJSON(b []byte) error
• type Timeseries
• type VirtualField

Types

type Aggregation

type Aggregation struct {
	// Alias for the aggregation.
	Alias string `json:"alias"`
	// Op is the operation of the aggregation.
	Op AggregationOp `json:"op"`
	// Field the aggregation operation is performed on.
	Field string `json:"field"`
	// Argument to the aggregation. Only valid for `OpCountDistinctIf`,
	// `OpTopk`, `OpPercentiles` and `OpHistogram`
	// aggregations.
	Argument interface{} `json:"argument"`
}

Aggregation performed as part of a query.

type AggregationOp

type AggregationOp uint8

An AggregationOp can be applied on queries to aggrgate based on different conditions.

const (

	// Works with all types, field should be `*`.
	OpCount         AggregationOp // count
	OpCountDistinct               // distinct

	// Only works for numbers.
	OpSum               // sum
	OpAvg               // avg
	OpMin               // min
	OpMax               // max
	OpTopk              // topk
	OpPercentiles       // percentiles
	OpHistogram         // histogram
	OpVariance          // variance
	OpStandardDeviation // stdev

	// Read-only. Not to be used for query requests. Only in place to support
	// the APL query result.
	OpCountIf         // countif
	OpCountDistinctIf // distinctif
)

All available query aggregation operations.

func (AggregationOp) MarshalJSON

func (op AggregationOp) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. It is in place to marshal the AggregationOp to its string representation because that's what the server expects.

func (AggregationOp) String

func (i AggregationOp) String() string

func (*AggregationOp) UnmarshalJSON

func (op *AggregationOp) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON implements json.Unmarshaler. It is in place to unmarshal the AggregationOp from the string representation the server returns.

type Entry

type Entry struct {
	// Time is the time the event occurred. Matches SysTime if not specified
	// during ingestion.
	Time time.Time `json:"_time"`
	// SysTime is the time the event was recorded on the server.
	SysTime time.Time `json:"_sysTime"`
	// RowID is the unique ID of the event row.
	RowID string `json:"_rowId"`
	// Data contains the raw data of the event (with filters and aggregations
	// applied).
	Data map[string]interface{} `json:"data"`
}

Entry is an event that matched a query and is thus part of the result set.

type EntryGroup

type EntryGroup struct {
	// ID is the unique the group.
	ID uint64 `json:"id"`
	// Group maps the fieldnames to the unique values for the entry.
	Group map[string]interface{} `json:"group"`
	// Aggregations of the group.
	Aggregations []EntryGroupAgg `json:"aggregations"`
}

EntryGroup is a group of queried event.

type EntryGroupAgg

type EntryGroupAgg struct {
	// Alias is the aggregations alias. If it wasn't specified at query time, it
	// is the uppercased string representation of the aggregation operation.
	Alias string `json:"op"`
	// Value is the result value of the aggregation.
	Value interface{} `json:"value"`
}

EntryGroupAgg is an aggregation which is part of a group of queried events.

type Filter

type Filter struct {
	// Op is the operation of the filter.
	Op FilterOp `json:"op"`
	// Field the filter operation is performed on.
	Field string `json:"field"`
	// Value to perform the filter operation against.
	Value interface{} `json:"value"`
	// CaseSensitive specifies if the filter is case sensitive or not. Only
	// valid for OpStartsWith, OpNotStartsWith, OpEndsWith, OpNotEndsWith,
	// OpContains and OpNotContains.
	CaseSensitive bool `json:"caseSensitive"`
	// Children specifies child filters for the filter. Only valid for OpAnd,
	// OpOr and OpNot.
	Children []Filter `json:"children"`
}

Filter applied as part of a query.

type FilterOp

type FilterOp uint8

A FilterOp can be applied on queries to filter based on different conditions.

const (
	OpAnd FilterOp // and
	OpOr           // or
	OpNot          // not

	// Works for strings and numbers.
	OpEqual     // ==
	OpNotEqual  // !=
	OpExists    // exists
	OpNotExists // not-exists

	// Only works for numbers.
	OpGreaterThan      // >
	OpGreaterThanEqual // >=
	OpLessThan         // <
	OpLessThanEqual    // <=

	// Only works for strings.
	OpStartsWith    // starts-with
	OpNotStartsWith // not-starts-with
	OpEndsWith      // ends-with
	OpNotEndsWith   // not-ends-with
	OpRegexp        // regexp
	OpNotRegexp     // not-regexp

	// Works for strings and arrays.
	OpContains    // contains
	OpNotContains // not-contains
)

All available query filter operations.

func (FilterOp) MarshalJSON

func (op FilterOp) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. It is in place to marshal the FilterOp to its string representation because that's what the server expects.

func (FilterOp) String

func (i FilterOp) String() string

func (*FilterOp) UnmarshalJSON

func (op *FilterOp) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON implements json.Unmarshaler. It is in place to unmarshal the FilterOp from the string representation the server returns.

type History

type History struct {
	// ID is the unique ID of the history query.
	ID string `json:"id"`
	// Kind of the history query.
	Kind Kind `json:"kind"`
	// Dataset the history query belongs to.
	Dataset string `json:"dataset"`
	// Owner is the team or user ID of the history queries owner.
	Owner string `json:"who"`
	// Query is the actual query.
	Query Query `json:"query"`
	// CreatedAt is the time the history query was created.
	CreatedAt time.Time `json:"created"`
}

History represents a query stored inside the query history.

type Interval

type Interval struct {
	// StartTime of the interval.
	StartTime time.Time `json:"startTime"`
	// EndTime of the interval.
	EndTime time.Time `json:"endTime"`
	// Groups of the interval.
	Groups []EntryGroup `json:"groups"`
}

Interval is the interval of queried time series.

type Kind

type Kind uint8

Kind represents the role of a query.

const (
	Analytics Kind = iota + 1 // analytics
	Stream                    // stream

	// Read-only. Not to be used for requests. Only in place to support typed
	// responses.
	APL // apl
)

All available query kinds.

func (Kind) EncodeValues

func (k Kind) EncodeValues(key string, v *url.Values) error

EncodeValues implements `query.Encoder`. It is in place to encode the Kind into a string URL value because that's what the server expects.

func (Kind) MarshalJSON

func (k Kind) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. It is in place to marshal the Kind to its string representation because that's what the server expects.

func (Kind) String

func (i Kind) String() string

func (*Kind) UnmarshalJSON

func (k *Kind) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler. It is in place to unmarshal the Kind from the string representation the server returns.

type Message

type Message struct {
	// Priority of the message.
	Priority MessagePriority `json:"priority"`
	// Count describes how often a message of this type was raised by the query.
	Count uint `json:"count"`
	// Code of the message.
	Code MessageCode `json:"code"`
	// Text is a human readable text representation of the message.
	Text string `json:"msg"`
}

Message is a message associated with a query result.

type MessageCode

type MessageCode uint8

MessageCode represents the code of a message associated with a query.

const (
	UnknownMessageCode          MessageCode = iota
	VirtualFieldFinalizeError               // virtual_field_finalize_error
	MissingColumn                           // missing_column
	LicenseLimitForQueryWarning             // license_limit_for_query_warning
	DefaultLimitWarning                     // default_limit_warning
)

All available message codes.

func (MessageCode) String

func (i MessageCode) String() string

func (*MessageCode) UnmarshalJSON

func (mc *MessageCode) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler. It is in place to unmarshal the MessageCode from the string representation the server returns.

type MessagePriority

type MessagePriority uint8

MessagePriority represents the priority of a message associated with a query.

const (
	Trace MessagePriority = iota + 1 // trace
	Debug                            // debug
	Info                             // info
	Warn                             // warn
	Error                            // error
	Fatal                            // fatal
)

All available message priorities.

func (MessagePriority) String

func (i MessagePriority) String() string

func (*MessagePriority) UnmarshalJSON

func (mp *MessagePriority) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler. It is in place to unmarshal the MessagePriority from the string representation the server returns.

type Options

type Options struct {
	// StreamingDuration of a query.
	StreamingDuration time.Duration `url:"streaming-duration,omitempty"`
	// NoCache omits the query cache.
	NoCache bool `url:"nocache,omitempty"`
	// SaveKind saves the query on the server with the given query kind. The ID
	// of the saved query is returned with the query result as part of the
	// response. `query.APL` is not a valid kind for this field.
	SaveKind Kind `url:"saveAsKind,omitempty"`
}

Options specifies the optional parameters to various query methods.

type Order

type Order struct {
	// Field to order on. Must be present in `GroupBy` or used by an
	// aggregation.
	Field string `json:"field"`
	// Desc specifies if the field is ordered ascending or descending.
	Desc bool `json:"desc"`
}

Order specifies the order a queries result will be in.

type Projection

type Projection struct {
	// Field to project to the query result.
	Field string `json:"field"`
	// Alias to reference the projected field by. Optional.
	Alias string `json:"alias"`
}

A Projection is a field that is projected to the query result.

type Query

type Query struct {
	// StartTime of the query. Required.
	StartTime time.Time `json:"startTime"`
	// EndTime of the query. Required.
	EndTime time.Time `json:"endTime"`
	// Resolution of the queries graph. Valid values are the queries time
	// range / 100 at maximum and / 1000 at minimum. Use zero value for
	// serve-side auto-detection.
	Resolution time.Duration `json:"resolution"`
	// Aggregations performed as part of the query.
	Aggregations []Aggregation `json:"aggregations"`
	// GroupBy is a list of field names to group the query result by. Only valid
	// when at least one aggregation is specified.
	GroupBy []string `json:"groupBy"`
	// Filter applied on the queried results.
	Filter Filter `json:"filter"`
	// Order is a list of order rules that specify the order of the query
	// result.
	Order []Order `json:"order"`
	// Limit the amount of results returned from the query.
	Limit uint32 `json:"limit"`
	// VirtualFields is a list of virtual fields that can be referenced by
	// aggregations, filters and orders.
	VirtualFields []VirtualField `json:"virtualFields"`
	// Projections is a list of projections that can be referenced by
	// aggregations, filters and orders. Leaving it empty projects all available
	// fields to the query result.
	Projections []Projection `json:"project"`
	// Cursor is the query cursor. It should be set to the Cursor returned with
	// a previous query result if it was partial.
	Cursor string `json:"cursor"`
	// IncludeCursor will return the Cursor as part of the query result, if set
	// to true.
	IncludeCursor bool `json:"includeCursor"`
	// ContinuationToken is used to get more results of a previous query. It is
	// not valid for starred queries or otherwise stored queries.
	ContinuationToken string `json:"continuationToken"`
}

Query represents a query that gets executed on a dataset.

func (Query) MarshalJSON

func (q Query) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. It is in place to marshal the Resolutions zero value to its proper string representation because that's what the server expects.

func (*Query) UnmarshalJSON

func (q *Query) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler. It is in place to unmarshal the Resolution string value to a proper time.Duration because that's what the server returns.

type Result

type Result struct {
	// Status of the query result.
	Status Status `json:"status"`
	// Matches are the events that matched the query.
	Matches []Entry `json:"matches"`
	// Buckets are the time series buckets.
	Buckets Timeseries `json:"buckets"`
	// SavedQueryID is the ID of the query that generated this result when it
	// was saved on the server. This is only set when the query was send with
	// the `SaveKind` option specified.
	SavedQueryID string `json:"-"`
}

Result is the result of a query.

type Status

type Status struct {
	// ElapsedTime is the duration it took the query to execute.
	ElapsedTime time.Duration `json:"elapsedTime"`
	// BlocksExamined is the amount of blocks that have been examined by the
	// query.
	BlocksExamined uint64 `json:"blocksExamined"`
	// RowsExamined is the amount of rows that have been examined by the query.
	RowsExamined uint64 `json:"rowsExamined"`
	// RowsMatched is the amount of rows that matched the query.
	RowsMatched uint64 `json:"rowsMatched"`
	// NumGroups is the amount of groups returned by the query.
	NumGroups uint32 `json:"numGroups"`
	// IsPartial describes if the query result is a partial result.
	IsPartial bool `json:"isPartial"`
	// ContinuationToken is populated when IsPartial is true and must be passed
	// to the next query request to retrieve the next result set.
	ContinuationToken string `json:"continuationToken"`
	// IsEstimate describes if the query result is estimated.
	IsEstimate bool `json:"isEstimate"`
	// MinBlockTime is the timestamp of the oldest block examined.
	MinBlockTime time.Time `json:"minBlockTime"`
	// MaxBlockTime is the timestamp of the newest block examined.
	MaxBlockTime time.Time `json:"maxBlockTime"`
	// Messages associated with the query.
	Messages []Message `json:"messages"`
}

Status is the status of a query result.

func (Status) MarshalJSON

func (s Status) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. It is in place to marshal the ElapsedTime into its microsecond representation because that's what the server expects.

func (*Status) UnmarshalJSON

func (s *Status) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler. It is in place to unmarshal the ElapsedTime into a proper time.Duration value because the server returns it in microseconds.

type Timeseries

type Timeseries struct {
	// Series are the intervals that build a time series.
	Series []Interval `json:"series"`
	// Totals of the time series.
	Totals []EntryGroup `json:"totals"`
}

Timeseries are queried time series.

type VirtualField

type VirtualField struct {
	// Alias the virtual field is referenced by.
	Alias string `json:"alias"`
	// Expression which specifies the virtual fields value.
	Expression string `json:"expr"`
}

A VirtualField is not part of a dataset and its value is derived from an expression. Aggregations, filters and orders can reference this field like any other field.