models

package
v1.11.0 Latest Latest
Warning

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

 Go to latest Published: Dec 6, 2022 License: MIT Imports: 14 Imported by: 703

Documentation

Overview

Package models implements basic objects used throughout the TICK stack.

Index

Constants

View Source 
const (
	FieldKeyTagKey    = "\xff"
	MeasurementTagKey = "\x00"
)

Values used to store the field key and measurement name as special internal tags.

View Source 
const (
	// MinNanoTime is the minimum time that can be represented.
	//
	// 1677-09-21 00:12:43.145224194 +0000 UTC
	//
	// The two lowest minimum integers are used as sentinel values.  The
	// minimum value needs to be used as a value lower than any other value for
	// comparisons and another separate value is needed to act as a sentinel
	// default value that is unusable by the user, but usable internally.
	// Because these two values need to be used for a special purpose, we do
	// not allow users to write points at these two times.
	MinNanoTime = int64(math.MinInt64) + 2

	// MaxNanoTime is the maximum time that can be represented.
	//
	// 2262-04-11 23:47:16.854775806 +0000 UTC
	//
	// The highest time represented by a nanosecond needs to be used for an
	// exclusive range in the shard group, so the maximum time needs to be one
	// less than the possible maximum number of nanoseconds representable by an
	// int64 so that we don't lose a point at that one time.
	MaxNanoTime = int64(math.MaxInt64) - 1
)
View Source 
const (
	// MaxKeyLength is the largest allowed size of the combined measurement and tag keys.
	MaxKeyLength = 65535
)

Variables

View Source 
var (
	FieldKeyTagKeyBytes    = []byte(FieldKeyTagKey)
	MeasurementTagKeyBytes = []byte(MeasurementTagKey)
)

Predefined byte representations of special tag keys.

View Source 
var (

	// ErrPointMustHaveAField is returned when operating on a point that does not have any fields.
	ErrPointMustHaveAField = errors.New("point without fields is unsupported")

	// ErrInvalidNumber is returned when a number is expected but not provided.
	ErrInvalidNumber = errors.New("invalid number")

	// ErrInvalidPoint is returned when a point cannot be parsed correctly.
	ErrInvalidPoint = errors.New("point is invalid")

	// ErrInvalidKevValuePairs is returned when the number of key, value pairs
	// is odd, indicating a missing value.
	ErrInvalidKevValuePairs = errors.New("key/value pairs is an odd length")
)
View Source 
var (
	// ErrInvalidConsistencyLevel is returned when parsing the string version
	// of a consistency level.
	ErrInvalidConsistencyLevel = errors.New("invalid consistency level")
)
View Source 
var (

	// ErrTimeOutOfRange gets returned when time is out of the representable range using int64 nanoseconds since the epoch.
	ErrTimeOutOfRange = fmt.Errorf("time outside range %d - %d", MinNanoTime, MaxNanoTime)
)

Functions

func AppendMakeKey added in v1.5.1 

func AppendMakeKey(dst []byte, name []byte, tags Tags) []byte

AppendMakeKey appends the key derived from name and tags to dst and returns the extended buffer.

func CheckTime added in v0.10.0 

func CheckTime(t time.Time) error

CheckTime checks that a time is within the safe range.

func CompareTags added in v1.3.0 

func CompareTags(a, b Tags) int

CompareTags returns -1 if a < b, 1 if a > b, and 0 if a == b.

func EnableUintSupport added in v1.4.0 

func EnableUintSupport()

EnableUintSupport manually enables uint support for the point parser. This function will be removed in the future and only exists for unit tests during the transition.

func EscapeMeasurement added in v1.4.0 

func EscapeMeasurement(in []byte) []byte

func EscapeStringField added in v1.0.0 

func EscapeStringField(in string) string

EscapeStringField returns a copy of in with any double quotes or backslashes with escaped values.

func GetPrecisionMultiplier added in v0.10.0 

func GetPrecisionMultiplier(precision string) int64

GetPrecisionMultiplier will return a multiplier for the precision specified.

func MakeKey 

func MakeKey(name []byte, tags Tags) []byte

MakeKey creates a key for a set of tags.

func ParseName added in v1.3.0 

func ParseName(buf []byte) []byte

func SafeCalcTime added in v0.10.0 

func SafeCalcTime(timestamp int64, precision string) (time.Time, error)

SafeCalcTime safely calculates the time given. Will return error if the time is outside the supported range.

func ValidKeyToken added in v1.5.4 

func ValidKeyToken(s string) bool

ValidKeyToken returns true if the token used for measurement, tag key, or tag value is a valid unicode string and only contains printable, non-replacement characters. Note \n (newline) is not printable.

func ValidKeyTokens added in v1.5.4 

func ValidKeyTokens(name string, tags Tags) bool

ValidKeyTokens returns true if the measurement name and all tags are valid.

func ValidPointStrings added in v1.9.3 

func ValidPointStrings(p Point) (err error)

ValidPointStrings validates the measurement name, tage names and values, and field names in a point

Types

type ConsistencyLevel added in v0.12.0 

type ConsistencyLevel int

ConsistencyLevel represent a required replication criteria before a write can be returned as successful.

The consistency level is handled in open-source InfluxDB but only applicable to clusters. 

const (
	// ConsistencyLevelAny allows for hinted handoff, potentially no write happened yet.
	ConsistencyLevelAny ConsistencyLevel = iota

	// ConsistencyLevelOne requires at least one data node acknowledged a write.
	ConsistencyLevelOne

	// ConsistencyLevelQuorum requires a quorum of data nodes to acknowledge a write.
	ConsistencyLevelQuorum

	// ConsistencyLevelAll requires all data nodes to acknowledge a write.
	ConsistencyLevelAll
)

func ParseConsistencyLevel added in v0.12.0 

func ParseConsistencyLevel(level string) (ConsistencyLevel, error)

ParseConsistencyLevel converts a consistency level string to the corresponding ConsistencyLevel const.

type FieldIterator added in v1.1.0 

type FieldIterator interface {
	// Next indicates whether there any fields remaining.
	Next() bool

	// FieldKey returns the key of the current field.
	FieldKey() []byte

	// Type returns the FieldType of the current field.
	Type() FieldType

	// StringValue returns the string value of the current field.
	StringValue() string

	// IntegerValue returns the integer value of the current field.
	IntegerValue() (int64, error)

	// UnsignedValue returns the unsigned value of the current field.
	UnsignedValue() (uint64, error)

	// BooleanValue returns the boolean value of the current field.
	BooleanValue() (bool, error)

	// FloatValue returns the float value of the current field.
	FloatValue() (float64, error)

	// Reset resets the iterator to its initial state.
	Reset()
}

FieldIterator provides a low-allocation interface to iterate through a point's fields.

type FieldType added in v1.1.0 

type FieldType int

FieldType represents the type of a field. 

const (
	// Integer indicates the field's type is integer.
	Integer FieldType = iota

	// Float indicates the field's type is float.
	Float

	// Boolean indicates the field's type is boolean.
	Boolean

	// String indicates the field's type is string.
	String

	// Empty is used to indicate that there is no field.
	Empty

	// Unsigned indicates the field's type is an unsigned integer.
	Unsigned
)

func (FieldType) String added in v1.7.5 

func (i FieldType) String() string

type Fields 

type Fields map[string]interface{}

Fields represents a mapping between a Point's field names and their values.

func (Fields) MarshalBinary 

func (p Fields) MarshalBinary() []byte

MarshalBinary encodes all the fields to their proper type and returns the binary representation NOTE: uint64 is specifically not supported due to potential overflow when we decode again later to an int64 NOTE2: uint is accepted, and may be 64 bits, and is for some reason accepted...

type InlineFNV64a added in v1.1.0 

type InlineFNV64a uint64

InlineFNV64a is an alloc-free port of the standard library's fnv64a. See https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function.

func NewInlineFNV64a added in v1.1.0 

func NewInlineFNV64a() InlineFNV64a

NewInlineFNV64a returns a new instance of InlineFNV64a.

func (*InlineFNV64a) Sum64 added in v1.1.0 

func (s *InlineFNV64a) Sum64() uint64

Sum64 returns the uint64 of the current resulting hash.

func (*InlineFNV64a) Write added in v1.1.0 

func (s *InlineFNV64a) Write(data []byte) (int, error)

Write adds data to the running hash.

type Point 

type Point interface {
	// Name return the measurement name for the point.
	Name() []byte

	// SetName updates the measurement name for the point.
	SetName(string)

	// Tags returns the tag set for the point.
	Tags() Tags

	// ForEachTag iterates over each tag invoking fn.  If fn return false, iteration stops.
	ForEachTag(fn func(k, v []byte) bool)

	// AddTag adds or replaces a tag value for a point.
	AddTag(key, value string)

	// SetTags replaces the tags for the point.
	SetTags(tags Tags)

	// HasTag returns true if the tag exists for the point.
	HasTag(tag []byte) bool

	// ForEachField iterates over each field invoking fn. if fn returns false, iteration stops.
	ForEachField(fn func(k, v []byte) bool) error

	// Fields returns the fields for the point.
	Fields() (Fields, error)

	// Time return the timestamp for the point.
	Time() time.Time

	// SetTime updates the timestamp for the point.
	SetTime(t time.Time)

	// UnixNano returns the timestamp of the point as nanoseconds since Unix epoch.
	UnixNano() int64

	// HashID returns a non-cryptographic checksum of the point's key.
	HashID() uint64

	// Key returns the key (measurement joined with tags) of the point.
	Key() []byte

	// String returns a string representation of the point. If there is a
	// timestamp associated with the point then it will be specified with the default
	// precision of nanoseconds.
	String() string

	// MarshalBinary returns a binary representation of the point.
	MarshalBinary() ([]byte, error)

	// PrecisionString returns a string representation of the point. If there
	// is a timestamp associated with the point then it will be specified in the
	// given unit.
	PrecisionString(precision string) string

	// RoundedString returns a string representation of the point. If there
	// is a timestamp associated with the point, then it will be rounded to the
	// given duration.
	RoundedString(d time.Duration) string

	// Split will attempt to return multiple points with the same timestamp whose
	// string representations are no longer than size. Points with a single field or
	// a point without a timestamp may exceed the requested size.
	Split(size int) []Point

	// Round will round the timestamp of the point to the given duration.
	Round(d time.Duration)

	// StringSize returns the length of the string that would be returned by String().
	StringSize() int

	// AppendString appends the result of String() to the provided buffer and returns
	// the result, potentially reducing string allocations.
	AppendString(buf []byte) []byte

	// FieldIterator returns a FieldIterator that can be used to traverse the
	// fields of a point without constructing the in-memory map.
	FieldIterator() FieldIterator
}

Point defines the values that will be written to the database.

func MustNewPoint 

func MustNewPoint(name string, tags Tags, fields Fields, time time.Time) Point

MustNewPoint returns a new point with the given measurement name, tags, fields and timestamp. If an unsupported field value (NaN) is passed, this function panics.

func NewPoint 

func NewPoint(name string, tags Tags, fields Fields, t time.Time) (Point, error)

NewPoint returns a new point with the given measurement name, tags, fields and timestamp. If an unsupported field value (NaN, or +/-Inf) or out of range time is passed, this function returns an error.

func NewPointFromBytes added in v0.9.6 

func NewPointFromBytes(b []byte) (Point, error)

NewPointFromBytes returns a new Point from a marshalled Point.

func ParsePoints 

func ParsePoints(buf []byte) ([]Point, error)

ParsePoints returns a slice of Points from a text representation of a point with each point separated by newlines. If any points fail to parse, a non-nil error will be returned in addition to the points that parsed successfully.

func ParsePointsString 

func ParsePointsString(buf string) ([]Point, error)

ParsePointsString is identical to ParsePoints but accepts a string.

func ParsePointsWithPrecision 

func ParsePointsWithPrecision(buf []byte, defaultTime time.Time, precision string) ([]Point, error)

ParsePointsWithPrecision is similar to ParsePoints, but allows the caller to provide a precision for time.

NOTE: to minimize heap allocations, the returned Points will refer to subslices of buf. This can have the unintended effect preventing buf from being garbage collected.

type Points 

type Points []Point

Points represents a sortable list of points by timestamp.

func (Points) Len 

func (a Points) Len() int

Len implements sort.Interface.

func (Points) Less 

func (a Points) Less(i, j int) bool

Less implements sort.Interface.

func (Points) Swap 

func (a Points) Swap(i, j int)

Swap implements sort.Interface.

type Row 

type Row struct {
	Name    string            `json:"name,omitempty"`
	Tags    map[string]string `json:"tags,omitempty"`
	Columns []string          `json:"columns,omitempty"`
	Values  [][]interface{}   `json:"values,omitempty"`
	Partial bool              `json:"partial,omitempty"`
}

Row represents a single row returned from the execution of a statement.

func (*Row) SameSeries 

func (r *Row) SameSeries(o *Row) bool

SameSeries returns true if r contains values for the same series as o.

type Rows 

type Rows []*Row

Rows represents a collection of rows. Rows implements sort.Interface.

func (Rows) Len 

func (p Rows) Len() int

Len implements sort.Interface.

func (Rows) Less 

func (p Rows) Less(i, j int) bool

Less implements sort.Interface.

func (Rows) Swap 

func (p Rows) Swap(i, j int)

Swap implements sort.Interface.

type Statistic added in v1.0.0 

type Statistic struct {
	Name   string                 `json:"name"`
	Tags   map[string]string      `json:"tags"`
	Values map[string]interface{} `json:"values"`
}

Statistic is the representation of a statistic used by the monitoring service.

func NewStatistic added in v1.1.0 

func NewStatistic(name string) Statistic

NewStatistic returns an initialized Statistic.

type StatisticTags added in v1.1.0 

type StatisticTags map[string]string

StatisticTags is a map that can be merged with others without causing mutations to either map.

func (StatisticTags) Merge added in v1.1.0 

func (t StatisticTags) Merge(tags map[string]string) map[string]string

Merge creates a new map containing the merged contents of tags and t. If both tags and the receiver map contain the same key, the value in tags is used in the resulting map.

Merge always returns a usable map.

type Tag added in v1.1.0 

type Tag struct {
	Key   []byte
	Value []byte
}

Tag represents a single key/value tag pair.

func NewTag added in v1.3.0 

func NewTag(key, value []byte) Tag

NewTag returns a new Tag.

func (Tag) Clone added in v1.1.2 

func (t Tag) Clone() Tag

Clone returns a shallow copy of Tag.

Tags associated with a Point created by ParsePointsWithPrecision will hold references to the byte slice that was parsed. Use Clone to create a Tag with new byte slices that do not refer to the argument to ParsePointsWithPrecision.

func (Tag) Size added in v1.3.0 

func (t Tag) Size() int

Size returns the size of the key and value.

func (*Tag) String added in v1.3.0 

func (t *Tag) String() string

String returns the string reprsentation of the tag.

type TagKeysSet added in v1.7.8 

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

TagKeysSet provides set operations for combining Tags.

func (*TagKeysSet) Clear added in v1.7.8 

func (set *TagKeysSet) Clear()

Clear removes all the elements of TagKeysSet and ensures all internal buffers are reset.

func (*TagKeysSet) IsSupersetBytes added in v1.7.8 

func (set *TagKeysSet) IsSupersetBytes(other [][]byte) bool

IsSupersetBytes returns true if the TagKeysSet is a superset of all the keys in other. Other must be lexicographically sorted or the results are undefined.

func (*TagKeysSet) IsSupersetKeys added in v1.7.8 

func (set *TagKeysSet) IsSupersetKeys(other Tags) bool

IsSupersetKeys returns true if the TagKeysSet is a superset of all the keys contained in other.

func (*TagKeysSet) Keys added in v1.7.8 

func (set *TagKeysSet) Keys() []string

Keys returns a copy of the merged keys in lexicographical order.

func (*TagKeysSet) KeysBytes added in v1.7.8 

func (set *TagKeysSet) KeysBytes() [][]byte

KeysBytes returns the merged keys in lexicographical order. The slice is valid until the next call to UnionKeys, UnionBytes or Reset.

func (*TagKeysSet) String added in v1.7.8 

func (set *TagKeysSet) String() string

func (*TagKeysSet) UnionBytes added in v1.7.8 

func (set *TagKeysSet) UnionBytes(other [][]byte)

UnionBytes updates the set so that it is the union of itself and all the keys contained in other. Other must be lexicographically sorted or the results are undefined.

func (*TagKeysSet) UnionKeys added in v1.7.8 

func (set *TagKeysSet) UnionKeys(other Tags)

UnionKeys updates the set so that it is the union of itself and all the keys contained in other.

type Tags 

type Tags []Tag

Tags represents a sorted list of tags.

func CopyTags added in v1.3.0 

func CopyTags(a Tags) Tags

CopyTags returns a shallow copy of tags.

func DeepCopyTags added in v1.3.0 

func DeepCopyTags(a Tags) Tags

DeepCopyTags returns a deep copy of tags.

func NewTags added in v1.1.0 

func NewTags(m map[string]string) Tags

NewTags returns a new Tags from a map.

func NewTagsKeyValues added in v1.9.0 

func NewTagsKeyValues(a Tags, kv ...[]byte) (Tags, error)

NewTagsKeyValues returns a new Tags from a list of key, value pairs, ensuring the returned result is correctly sorted. Duplicate keys are removed, however, it which duplicate that remains is undefined. NewTagsKeyValues will return ErrInvalidKevValuePairs if len(kvs) is not even. If the input is guaranteed to be even, the error can be safely ignored. If a has enough capacity, it will be reused.

func ParseKey added in v0.9.6 

func ParseKey(buf []byte) (string, Tags)

ParseKey returns the measurement name and tags from a point.

NOTE: to minimize heap allocations, the returned Tags will refer to subslices of buf. This can have the unintended effect preventing buf from being garbage collected.

func ParseKeyBytes added in v1.5.0 

func ParseKeyBytes(buf []byte) ([]byte, Tags)

func ParseKeyBytesWithTags added in v1.6.1 

func ParseKeyBytesWithTags(buf []byte, tags Tags) ([]byte, Tags)

func ParseTags added in v1.3.0 

func ParseTags(buf []byte) Tags

func (Tags) AppendHashKey added in v1.5.1 

func (a Tags) AppendHashKey(dst []byte) []byte

AppendHashKey appends the result of hashing all of a tag's keys and values to dst and returns the extended buffer.

func (Tags) Clone added in v1.1.2 

func (a Tags) Clone() Tags

Clone returns a copy of the slice where the elements are a result of calling `Clone` on the original elements

Tags associated with a Point created by ParsePointsWithPrecision will hold references to the byte slice that was parsed. Use Clone to create Tags with new byte slices that do not refer to the argument to ParsePointsWithPrecision.

func (*Tags) Delete added in v1.1.0 

func (a *Tags) Delete(key []byte)

Delete removes a tag by key.

func (Tags) Equal added in v1.3.0 

func (a Tags) Equal(other Tags) bool

Equal returns true if a equals other.

func (Tags) Get added in v1.1.0 

func (a Tags) Get(key []byte) []byte

Get returns the value for a key.

func (Tags) GetString added in v1.1.0 

func (a Tags) GetString(key string) string

GetString returns the string value for a string key.

func (Tags) HashKey 

func (a Tags) HashKey() []byte

HashKey hashes all of a tag's keys.

func (Tags) Keys added in v1.4.0 

func (a Tags) Keys() []string

Keys returns the list of keys for a tag set.

func (Tags) Len added in v1.1.0 

func (a Tags) Len() int

func (Tags) Less added in v1.1.0 

func (a Tags) Less(i, j int) bool

func (Tags) Map added in v1.1.0 

func (a Tags) Map() map[string]string

Map returns a map representation of the tags.

func (Tags) Merge added in v1.0.0 

func (a Tags) Merge(other map[string]string) Tags

Merge merges the tags combining the two. If both define a tag with the same key, the merged value overwrites the old value. A new map is returned.

func (*Tags) Set added in v1.1.0 

func (a *Tags) Set(key, value []byte)

Set sets the value for a key.

func (*Tags) SetString added in v1.1.0 

func (a *Tags) SetString(key, value string)

SetString sets the string value for a string key.

func (Tags) Size added in v1.3.0 

func (a Tags) Size() int

Size returns the number of bytes needed to store all tags. Note, this is the number of bytes needed to store all keys and values and does not account for data structures or delimiters for example.

func (Tags) String added in v1.3.0 

func (a Tags) String() string

String returns the string representation of the tags.

func (Tags) Swap added in v1.1.0 

func (a Tags) Swap(i, j int)

func (Tags) Values added in v1.4.0 

func (a Tags) Values() []string

Values returns the list of values for a tag set.

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.