Documentation
¶
Overview ¶
Package dataset defines the interface for managing time seres objects and provides time range manipulation capabilities
Index ¶
- func MarshalDataSet(ts timeseries.Timeseries, _ *timeseries.RequestOptions, _ int) ([]byte, error)
- func PointsAreEqual(p1, p2 Point) bool
- func UnmarshalDataSet(b []byte, trq *timeseries.TimeRangeQuery) (timeseries.Timeseries, error)
- type DataSet
- func (ds *DataSet) Clone() timeseries.Timeseries
- func (ds *DataSet) CropToRange(e timeseries.Extent)
- func (ds *DataSet) CropToSize(sz int, t time.Time, lur timeseries.Extent)
- func (ds *DataSet) CroppedClone(e timeseries.Extent) timeseries.Timeseries
- func (z *DataSet) DecodeMsg(dc *msgp.Reader) (err error)
- func (ds *DataSet) DefaultMerger(sortPoints bool, collection ...timeseries.Timeseries)
- func (ds *DataSet) DefaultRangeCropper(e timeseries.Extent)
- func (ds *DataSet) DefaultSizeCropper(sz int, t time.Time, lur timeseries.Extent)
- func (z *DataSet) EncodeMsg(en *msgp.Writer) (err error)
- func (ds *DataSet) Extents() timeseries.ExtentList
- func (ds *DataSet) FieldDefinitions() (timeseries.FieldDefinitions, timeseries.FieldDefinitions, ...)
- func (ds *DataSet) InjectTags(tags Tags)
- func (z *DataSet) MarshalMsg(b []byte) (o []byte, err error)
- func (ds *DataSet) Merge(sortPoints bool, collection ...timeseries.Timeseries)
- func (z *DataSet) Msgsize() (s int)
- func (ds *DataSet) PointCount() int
- func (ds *DataSet) SeriesCount() int
- func (ds *DataSet) SetExtents(el timeseries.ExtentList)
- func (ds *DataSet) SetTimeRangeQuery(trq *timeseries.TimeRangeQuery)
- func (ds *DataSet) SetVolatileExtents(e timeseries.ExtentList)
- func (ds *DataSet) Size() int64
- func (ds *DataSet) Sort()
- func (ds *DataSet) Step() time.Duration
- func (ds *DataSet) TimestampCount() int64
- func (z *DataSet) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (ds *DataSet) ValueCount() int64
- func (ds *DataSet) VolatileExtents() timeseries.ExtentList
- type DataSets
- type Hash
- type Hashes
- type MarshalWriter
- type Marshaler
- type Point
- type Points
- func (p Points) Clone() Points
- func (p Points) CloneRange(start, end int) Points
- func (z *Points) DecodeMsg(dc *msgp.Reader) (err error)
- func (z Points) EncodeMsg(en *msgp.Writer) (err error)
- func (p Points) Equal(p2 Points) bool
- func (p Points) Len() int
- func (p Points) Less(i, j int) bool
- func (z Points) MarshalMsg(b []byte) (o []byte, err error)
- func (z Points) Msgsize() (s int)
- func (p Points) Size() int64
- func (p Points) Swap(i, j int)
- func (z *Points) UnmarshalMsg(bts []byte) (o []byte, err error)
- type Result
- func (r *Result) Clone() *Result
- func (z *Result) DecodeMsg(dc *msgp.Reader) (err error)
- func (z *Result) EncodeMsg(en *msgp.Writer) (err error)
- func (r *Result) Hashes() Hashes
- func (z *Result) MarshalMsg(b []byte) (o []byte, err error)
- func (z *Result) Msgsize() (s int)
- func (r *Result) Size() int64
- func (r *Result) String() string
- func (z *Result) UnmarshalMsg(bts []byte) (o []byte, err error)
- type Results
- type ResultsLookup
- type Series
- func (s *Series) Clone() *Series
- func (z *Series) DecodeMsg(dc *msgp.Reader) (err error)
- func (z *Series) EncodeMsg(en *msgp.Writer) (err error)
- func (z *Series) MarshalMsg(b []byte) (o []byte, err error)
- func (z *Series) Msgsize() (s int)
- func (s *Series) Size() int64
- func (s *Series) String() string
- func (z *Series) UnmarshalMsg(bts []byte) (o []byte, err error)
- type SeriesHeader
- func (sh *SeriesHeader) CalculateHash(rehash ...bool) Hash
- func (sh *SeriesHeader) CalculateSize() int
- func (sh *SeriesHeader) Clone() SeriesHeader
- func (z *SeriesHeader) DecodeMsg(dc *msgp.Reader) (err error)
- func (z *SeriesHeader) EncodeMsg(en *msgp.Writer) (err error)
- func (sh *SeriesHeader) FieldDefinitions() timeseries.FieldDefinitions
- func (z *SeriesHeader) MarshalMsg(b []byte) (o []byte, err error)
- func (z *SeriesHeader) Msgsize() (s int)
- func (sh *SeriesHeader) String() string
- func (z *SeriesHeader) UnmarshalMsg(bts []byte) (o []byte, err error)
- type SeriesList
- func (sl SeriesList) Clone() SeriesList
- func (z *SeriesList) DecodeMsg(dc *msgp.Reader) (err error)
- func (z SeriesList) EncodeMsg(en *msgp.Writer) (err error)
- func (sl SeriesList) EqualHeader(sl2 SeriesList) bool
- func (z SeriesList) MarshalMsg(b []byte) (o []byte, err error)
- func (sl SeriesList) Merge(sl2 SeriesList, sortPoints bool) SeriesList
- func (z SeriesList) Msgsize() (s int)
- func (sl SeriesList) SortByTags()
- func (sl SeriesList) SortPoints()
- func (sl SeriesList) String() string
- func (z *SeriesList) UnmarshalMsg(bts []byte) (o []byte, err error)
- type SeriesLookup
- type SeriesLookupKey
- func (z *SeriesLookupKey) DecodeMsg(dc *msgp.Reader) (err error)
- func (z SeriesLookupKey) EncodeMsg(en *msgp.Writer) (err error)
- func (z SeriesLookupKey) MarshalMsg(b []byte) (o []byte, err error)
- func (z SeriesLookupKey) Msgsize() (s int)
- func (z *SeriesLookupKey) UnmarshalMsg(bts []byte) (o []byte, err error)
- type Tags
- func (t Tags) Clone() Tags
- func (z *Tags) DecodeMsg(dc *msgp.Reader) (err error)
- func (z Tags) EncodeMsg(en *msgp.Writer) (err error)
- func (t Tags) JSON() string
- func (t Tags) KVP() string
- func (t Tags) Keys() []string
- func (z Tags) MarshalMsg(b []byte) (o []byte, err error)
- func (t Tags) Merge(t2 Tags)
- func (z Tags) Msgsize() (s int)
- func (t Tags) Size() int
- func (t Tags) String() string
- func (t Tags) StringsWithSep(sep1, sep2 string) string
- func (z *Tags) UnmarshalMsg(bts []byte) (o []byte, err error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MarshalDataSet ¶
func MarshalDataSet(ts timeseries.Timeseries, _ *timeseries.RequestOptions, _ int, ) ([]byte, error)
MarshalDataSet marshals the dataset into a msgpack-formatted byte slice
func PointsAreEqual ¶
Equal returns true if p and p2 are exactly equal
func UnmarshalDataSet ¶
func UnmarshalDataSet(b []byte, trq *timeseries.TimeRangeQuery) (timeseries.Timeseries, error)
UnmarshalDataSet unmarshals the dataset from a msgpack-formatted byte slice
Types ¶
type DataSet ¶
type DataSet struct {
// Status is the optional status indicator for the DataSet
Status string `msg:"status"`
// ExtentList is the list of Extents (time ranges) represented in the Results
ExtentList timeseries.ExtentList `msg:"extent_list"`
// Results is the list of type Result. Each Result represents information about a
// different statement in the source query for this DataSet
Results Results `msg:"results"`
// UpdateLock is used to synchronize updates to the DataSet
UpdateLock sync.Mutex `msg:"-"`
// Error is a container for any DataSet-level Errors
Error string `msg:"error"`
// ErrorType describes the type for any DataSet-level Errors
ErrorType string `msg:"errorType"`
// Warnings is a container for any DataSet-level Warnings
Warnings []string `msg:"warnings"`
// TimeRangeQuery is the trq associated with the Timeseries
TimeRangeQuery *timeseries.TimeRangeQuery `msg:"trq"`
// VolatileExtents is the list extents in the dataset that should be refreshed
// on the next request to the Origin
VolatileExtentList timeseries.ExtentList `msg:"volatile_extents"`
// Sorter is the DataSet's Sort function, which defaults to DefaultSort
Sorter func() `msg:"-"`
// Merger is the DataSet's Merge function, which defaults to DefaultMerge
Merger func(sortPoints bool, ts ...timeseries.Timeseries) `msg:"-"`
// SizeCropper is the DataSet's CropToSize function, which defaults to DefaultSizeCropper
SizeCropper func(int, time.Time, timeseries.Extent) `msg:"-"`
// RangeCropper is the DataSet's CropToRange function, which defaults to DefaultRangeCropper
RangeCropper func(timeseries.Extent) `msg:"-"`
}
DataSet is the Common Time Series Format that Trickster uses to accelerate most of its supported TSDB backends DataSet conforms to the Timeseries interface
func (*DataSet) Clone ¶
func (ds *DataSet) Clone() timeseries.Timeseries
Clone returns a new, perfect copy of the DataSet
func (*DataSet) CropToRange ¶
func (ds *DataSet) CropToRange(e timeseries.Extent)
CropToRange reduces the DataSet down to timestamps contained within the provided Extents (inclusive). CropToRange assumes the base DataSet is already sorted, and will corrupt an unsorted DataSet
func (*DataSet) CropToSize ¶
CropToSize reduces the number of elements in the Timeseries to the provided count, by evicting elements using a least-recently-used methodology. The time parameter limits the upper extent to the provided time, in order to support backfill tolerance
func (*DataSet) CroppedClone ¶
func (ds *DataSet) CroppedClone(e timeseries.Extent) timeseries.Timeseries
CroppedClone returns a new, perfect copy of the DataSet, efficiently cropped to the provided Extent. CroppedClone assumes the DataSet is sorted.
func (*DataSet) DefaultMerger ¶
func (ds *DataSet) DefaultMerger(sortPoints bool, collection ...timeseries.Timeseries)
DefaultMerger is the default Merger function
func (*DataSet) DefaultRangeCropper ¶
func (ds *DataSet) DefaultRangeCropper(e timeseries.Extent)
DefaultRangeCropper is the default RangeCropper Function
func (*DataSet) DefaultSizeCropper ¶
DefaultSizeCropper is the default SizeCropper Function
func (*DataSet) Extents ¶
func (ds *DataSet) Extents() timeseries.ExtentList
Extents returns the DataSet's ExentList
func (*DataSet) FieldDefinitions ¶
func (ds *DataSet) FieldDefinitions() (timeseries.FieldDefinitions, timeseries.FieldDefinitions, timeseries.FieldDefinitions, timeseries.FieldDefinition, )
FieldDefinitions returns a de-duped slice of Field Definitions (FDs) from all series in the DataSet. The return values are: All FDs, Tag FDs, Value FDs, Timestamp FD
func (*DataSet) InjectTags ¶
InjectTags injects the provided tags into all series in all results in the DataSet in an insert-or-update fashion
func (*DataSet) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
func (*DataSet) Merge ¶
func (ds *DataSet) Merge(sortPoints bool, collection ...timeseries.Timeseries)
Merge merges the provided Timeseries list into the base DataSet (in the order provided) and optionally sorts the merged DataSet This implementation ignores any Timeseries that are not of type *DataSet
func (*DataSet) Msgsize ¶
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*DataSet) PointCount ¶
PointCount returns the total number of Points across all Results and Series
func (*DataSet) SeriesCount ¶
SeriesCount returns the count of all Series across all Results in the DataSet
func (*DataSet) SetExtents ¶
func (ds *DataSet) SetExtents(el timeseries.ExtentList)
SetExtents overwrites a DataSet's known extents with the provided extent list
func (*DataSet) SetTimeRangeQuery ¶
func (ds *DataSet) SetTimeRangeQuery(trq *timeseries.TimeRangeQuery)
SetTimeRangeQuery sets the TimeRangeQuery for the DataSet
func (*DataSet) SetVolatileExtents ¶
func (ds *DataSet) SetVolatileExtents(e timeseries.ExtentList)
SetVolatileExtents sets the list of time Extents in the dataset that should be re-fetched
func (*DataSet) Sort ¶
func (ds *DataSet) Sort()
Sort sorts all Values in each Series chronologically by their timestamp Sorting is efficiently baked into DataSet.Merge(), therefore this interface function is unused unless overridden
func (*DataSet) TimestampCount ¶
TimestampCount returns the count of unique timestamps across all series in the DataSet
func (*DataSet) UnmarshalMsg ¶
UnmarshalMsg implements msgp.Unmarshaler
func (*DataSet) ValueCount ¶
ValueCount returns the count of all values across all Series in the DataSet
func (*DataSet) VolatileExtents ¶
func (ds *DataSet) VolatileExtents() timeseries.ExtentList
VolatileExtents returns the list of time Extents in the dataset that should be re-fetched
type DataSets ¶
type DataSets []*DataSet
func (DataSets) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
type Hash ¶
type Hash uint64
Hash is a numeric value representing a calculated hash
func (Hash) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
type Hashes ¶
type Hashes []Hash
Hashes is a slice of type Hash
func (Hashes) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
type MarshalWriter ¶
type MarshalWriter func(io.Writer, *DataSet, *timeseries.RequestOptions, int) error
MarshalWriter is a function that serializes the DataSet via an io.Writer
type Marshaler ¶
type Marshaler func(*DataSet, *timeseries.RequestOptions, int) ([]byte, error)
Marshaler is a function that serializes the provided DataSet into a byte slice
type Point ¶
type Point struct {
Epoch epoch.Epoch `msg:"epoch"`
Size int `msg:"size"`
Values []any `msg:"values"`
}
Point represents a timeseries data point
func (*Point) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
type Points ¶
type Points []Point
Points is a slice of type *Point
func MergePoints ¶
Merge returns a new Points slice of p and p2 merged together. If sort is true the new slice is sorted and dupe-killed before being returned
func (Points) CloneRange ¶
CloneRange returns a perfect copy of the Points, cloning only the points in the provided index range (upper-bound exclusive)
func (Points) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
func (Points) Msgsize ¶
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
type Result ¶
type Result struct {
// StatementID represents the ID of the statement for this result. This field may not be
// used by all tsdb implementations
StatementID int `msg:"statement_id"`
// Error represents a statement-level error
Error string `msg:"error"`
// SeriesList is an ordered list of the Series in this result
SeriesList SeriesList `msg:"series"`
// Name is the name of the Result, used by some Providers that include
// multiple results in the same response, in lieu of a StatementID
Name string `msg:"name"`
}
Result represents the results of a single query statement in the DataSet
func (*Result) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
type Results ¶
type Results []*Result
func (Results) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
type ResultsLookup ¶
ResultsLookup is a map of Results searchable by the Statement ID
type Series ¶
type Series struct {
// Header is the Series Header describing the Series
Header SeriesHeader `msg:"header"`
// Points is the list of Points in the Series
Points Points `msg:"points"`
// PointSize is the memory utilization of the Points in bytes
PointSize int64 `msg:"ps"`
}
Series represents a single timeseries in a Result
func (*Series) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
func (*Series) Msgsize ¶
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
type SeriesHeader ¶
type SeriesHeader struct {
// Name is the name of the Series
Name string `msg:"name"`
// Tags is the map of tags associated with the Series. Each key will map to
// a fd.Name in TagFieldsList, with values representing the specific tag
// values for this Series.
Tags Tags `msg:"tags"`
// TimestampField is the Field Definitions for the timestamp field.
// Optional and used by some providers.
TimestampField timeseries.FieldDefinition `msg:"timestampField"`
// TagFieldsList is the ordered list of tag-based Field Definitions in the
// Series. Optional and used by some providers.
TagFieldsList timeseries.FieldDefinitions `msg:"tagFields"`
// ValueFieldsList is the ordered list of value-based Field Definitions in the Series.
ValueFieldsList timeseries.FieldDefinitions `msg:"valueFields"`
// UntrackedFieldsList is alist of Field Definitions in the Series whose row values are ignored.
UntrackedFieldsList timeseries.FieldDefinitions `msg:"untrackedFields"`
// QueryStatement is the original query to which this DataSet is associated
QueryStatement string `msg:"query"`
// Size is the memory utilization of the Header in bytes
Size int `msg:"size"`
// contains filtered or unexported fields
}
SeriesHeader is the header section of a series, and describes its shape, size, and attributes
func (*SeriesHeader) CalculateHash ¶
func (sh *SeriesHeader) CalculateHash(rehash ...bool) Hash
CalculateHash sums the FNV64a hash for the Header and stores it to the Hash member
func (*SeriesHeader) CalculateSize ¶
func (sh *SeriesHeader) CalculateSize() int
CalculateSize sets and returns the header size
func (*SeriesHeader) Clone ¶
func (sh *SeriesHeader) Clone() SeriesHeader
Clone returns a perfect, new copy of the SeriesHeader
func (*SeriesHeader) DecodeMsg ¶
func (z *SeriesHeader) DecodeMsg(dc *msgp.Reader) (err error)
DecodeMsg implements msgp.Decodable
func (*SeriesHeader) EncodeMsg ¶
func (z *SeriesHeader) EncodeMsg(en *msgp.Writer) (err error)
EncodeMsg implements msgp.Encodable
func (*SeriesHeader) FieldDefinitions ¶
func (sh *SeriesHeader) FieldDefinitions() timeseries.FieldDefinitions
FieldDefinitions returns all FieldDefinitions in the series ordered by OutputPosition
func (*SeriesHeader) MarshalMsg ¶
func (z *SeriesHeader) MarshalMsg(b []byte) (o []byte, err error)
MarshalMsg implements msgp.Marshaler
func (*SeriesHeader) Msgsize ¶
func (z *SeriesHeader) Msgsize() (s int)
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*SeriesHeader) String ¶
func (sh *SeriesHeader) String() string
func (*SeriesHeader) UnmarshalMsg ¶
func (z *SeriesHeader) UnmarshalMsg(bts []byte) (o []byte, err error)
UnmarshalMsg implements msgp.Unmarshaler
type SeriesList ¶
type SeriesList []*Series
SeriesList is an ordered list of Series
func (SeriesList) Clone ¶
func (sl SeriesList) Clone() SeriesList
func (*SeriesList) DecodeMsg ¶
func (z *SeriesList) DecodeMsg(dc *msgp.Reader) (err error)
DecodeMsg implements msgp.Decodable
func (SeriesList) EncodeMsg ¶
func (z SeriesList) EncodeMsg(en *msgp.Writer) (err error)
EncodeMsg implements msgp.Encodable
func (SeriesList) EqualHeader ¶
func (sl SeriesList) EqualHeader(sl2 SeriesList) bool
EqualHeader returns true if the slice elements contain identical header values in the identical order.
func (SeriesList) MarshalMsg ¶
func (z SeriesList) MarshalMsg(b []byte) (o []byte, err error)
MarshalMsg implements msgp.Marshaler
func (SeriesList) Merge ¶
func (sl SeriesList) Merge(sl2 SeriesList, sortPoints bool) SeriesList
Merge merges sl2 into the subject SeriesList, using sl2's authoritative order to adaptively reorder the existing+merged list such that it best emulates the fully constituted series order as it would be served by the origin. Merge assumes that a *Series in both lists, having the identical header hash, are the same series and will merge sl2[i].Points into sl.Points
func (SeriesList) Msgsize ¶
func (z SeriesList) Msgsize() (s int)
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (SeriesList) SortByTags ¶
func (sl SeriesList) SortByTags()
func (SeriesList) SortPoints ¶
func (sl SeriesList) SortPoints()
func (SeriesList) String ¶
func (sl SeriesList) String() string
func (*SeriesList) UnmarshalMsg ¶
func (z *SeriesList) UnmarshalMsg(bts []byte) (o []byte, err error)
UnmarshalMsg implements msgp.Unmarshaler
type SeriesLookup ¶
type SeriesLookup map[SeriesLookupKey]*Series
SeriesLookup is a map of Series searchable by Series Header Hash
type SeriesLookupKey ¶
SeriesLookupKey is the key for a SeriesLookup, consisting of a Result.StatementID and a Series.Hash
func (*SeriesLookupKey) DecodeMsg ¶
func (z *SeriesLookupKey) DecodeMsg(dc *msgp.Reader) (err error)
DecodeMsg implements msgp.Decodable
func (SeriesLookupKey) EncodeMsg ¶
func (z SeriesLookupKey) EncodeMsg(en *msgp.Writer) (err error)
EncodeMsg implements msgp.Encodable
func (SeriesLookupKey) MarshalMsg ¶
func (z SeriesLookupKey) MarshalMsg(b []byte) (o []byte, err error)
MarshalMsg implements msgp.Marshaler
func (SeriesLookupKey) Msgsize ¶
func (z SeriesLookupKey) Msgsize() (s int)
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*SeriesLookupKey) UnmarshalMsg ¶
func (z *SeriesLookupKey) UnmarshalMsg(bts []byte) (o []byte, err error)
UnmarshalMsg implements msgp.Unmarshaler
type Tags ¶
Tags is a key/value pair associated with a Series to scope the cardinality of the DataSet
func (Tags) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
func (Tags) Merge ¶
Merge merges the provided tags into the subject tags, replacing any duplicate tag names
func (Tags) Msgsize ¶
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (Tags) StringsWithSep ¶
StringsWithSep returns a string representation of the Tags with the provided key/value separator