models

Documentation

Index

• Constants
• Variables
• func CheckTime(t time.Time) error
• func EscapeStringField(in string) string
• func GetPrecisionMultiplier(precision string) int64
• func MakeKey(name []byte, tags Tags) []byte
• func SafeCalcTime(timestamp int64, precision string) (time.Time, error)
• type ConsistencyLevel
  • func ParseConsistencyLevel(level string) (ConsistencyLevel, error)
• type Fields
  • func (p Fields) MarshalBinary() []byte
• type Point
  • func MustNewPoint(name string, tags Tags, fields Fields, time time.Time) Point
  • func NewPoint(name string, tags Tags, fields Fields, time time.Time) (Point, error)
  • func NewPointFromBytes(b []byte) (Point, error)
  • func ParsePoints(buf []byte) ([]Point, error)
  • func ParsePointsString(buf string) ([]Point, error)
  • func ParsePointsWithPrecision(buf []byte, defaultTime time.Time, precision string) ([]Point, error)
• type Points
  • func (a Points) Len() int
  • func (a Points) Less(i, j int) bool
  • func (a Points) Swap(i, j int)
• type Row
  • func (r *Row) SameSeries(o *Row) bool
• type Rows
  • func (p Rows) Len() int
  • func (p Rows) Less(i, j int) bool
  • func (p Rows) Swap(i, j int)
• type Statistic
• type Tags
  • func ParseKey(buf string) (string, Tags, error)
  • func (t Tags) HashKey() []byte
  • func (t Tags) Merge(other map[string]string) Tags

Constants

const (
	// MinNanoTime is the minumum 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
)

const (
	MaxKeyLength = 65535
)

Variables

var (
	ErrPointMustHaveAField  = errors.New("point without fields is unsupported")
	ErrInvalidNumber        = errors.New("invalid number")
	ErrInvalidPoint         = errors.New("point is invalid")
	ErrMaxKeyLengthExceeded = errors.New("max key length exceeded")
)

var (
	// ErrInvalidConsistencyLevel is returned when parsing the string version
	// of a consistency level.
	ErrInvalidConsistencyLevel = errors.New("invalid consistency level")
)

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 CheckTime

func CheckTime(t time.Time) error

CheckTime checks that a time is within the safe range.

func EscapeStringField

func EscapeStringField(in string) string

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

func GetPrecisionMultiplier

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 SafeCalcTime

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.

Types

type ConsistencyLevel

type ConsistencyLevel int

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

const (
	// ConsistencyLevelAny allows for hinted hand off, 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

func ParseConsistencyLevel(level string) (ConsistencyLevel, error)

ParseConsistencyLevel converts a consistency level string to the corresponding ConsistencyLevel const

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 represenation NOTE: uint64 is specifically not supported due to potential overflow when we decode again later to an int64

type Point

type Point interface {
	Name() string
	SetName(string)

	Tags() Tags
	AddTag(key, value string)
	SetTags(tags Tags)

	Fields() Fields

	Time() time.Time
	SetTime(t time.Time)
	UnixNano() int64

	HashID() uint64
	Key() []byte

	Data() []byte
	SetData(buf []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

	// Bytes returns a []byte representation of the point similar to string.
	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
}

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, time 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 out of range time is passed, this function returns an error.

func NewPointFromBytes

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 buffer.

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.

type Points

type Points []Point

Points represents a sortable list of points by timestamp.

func (Points) Len

func (a Points) Len() int

func (Points) Less

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

func (Points) Swap

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

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"`
	Err     error             `json:"err,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

func (Rows) Less

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

func (Rows) Swap

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

type Statistic

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

type Tags

type Tags map[string]string

Tags represents a mapping between a Point's tag names and their values.

func ParseKey

func ParseKey(buf string) (string, Tags, error)

ParseKey returns the measurement name and tags from a point.

func (Tags) HashKey

func (t Tags) HashKey() []byte

HashKey hashes all of a tag's keys.

func (Tags) Merge

func (t 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.