timeseries

Documentation

Index

• Constants
• Variables
• func Delete(ctx context.Context, c deleteQueryClient, req Request, src queries.Source) error
• type GranLevel
• type Request
  • func (r Request) Validate() error
• type Result
  • func Execute(ctx context.Context, c executeClient, req Request, src queries.Source) (Result, error)
  • func Read(ctx context.Context, c readClient, req Request, src queries.Source) (Result, error)
  • func (r Result) Average() float64
  • func (r Result) CircularMean() float64
  • func (r Result) GeometricMean() float64
  • func (r Result) STD() float64
  • func (r Result) ZScore(currentValue float64) float64

Constants

const (
	GranularityMinutes = "minutes"
	GranularityHours   = "hours"
	GranularityDays    = "days"
	GranularityDays30  = "days30"
)

Granularity levels for timeseries cell bucketing.

const (
	CellsSizeMinutes int64 = 60
	CellsSizeHours   int64 = 24
	CellsSizeDays    int64 = 30
	CellsSizeDays30  int64 = 24
)

Default ring buffer capacities for fine-grained granularity levels.

const (
	SetTimeseries = "timeseries_set"
	SetMeta       = "timeseries_meta"
)

Set names for timeseries storage.

const KeyMultiplier int64 = 100

KeyMultiplier is the factor used to build hierarchical cell identifiers. Each coarser granularity shifts the finer cell ID left by this factor.

const MaxRange = 2 * 365 * 24 * time.Hour

MaxRange is the maximum supported time range (2 years). Matches original: estimator ErrTwoBigTimerange.

Variables

var ErrRangeTooLarge = errors.New("time range exceeds 2 years maximum")

ErrRangeTooLarge is returned when Range exceeds MaxRange.

Functions

func Delete

func Delete(ctx context.Context, c deleteQueryClient, req Request, src queries.Source) error

Delete removes all stored data for a timeseries variable. Reconstructs all possible cell keys from the range and metadata, then batch-deletes them. No key tracking set is needed — keys are deterministic.

For custom mode (Range=0): deletes the single record. For fixed mode (Range>0): computes all hierarchical cell positions across all granularity levels and deletes them + metadata.

Types

type GranLevel

type GranLevel struct {
	Name     string
	CellSize int64
}

GranLevel describes a granularity level with its ring-buffer cell count. The coarsest level has a dynamic cell count derived from the time range; finer levels use fixed defaults.

type Request

type Request struct {
	Name           string        // variable name
	Namespace      string        // FrogoDB namespace
	GroupBy        []string      // source keys to group by
	Range          time.Duration // time window (0 = all-time custom mode)
	Fields         queries.Field // which fields to compute
	PercentileP    float64       // p value for percentile (0-1)
	Value          string        // source key for the numeric value
	DistinctBy     string        // source key for distinct counting
	TTL            time.Duration // REQUIRED. Expiration for stored data.
	IncludeCurrent bool          // true: write then read; false: read then write
}

Request describes a timeseries query. Range > 0 enables multi-granularity cell mode (fixed query). Range == 0 enables single-record all-time mode (custom query).

func (Request) Validate

func (r Request) Validate() error

Validate checks that required fields are set.

type Result

type Result struct {
	Count         int64
	Sum           float64
	Min           float64
	Max           float64
	DistinctCount int64
	SumQ          float64 // for STD
	SumLog        float64 // for GMean
	SumCos        float64 // for CMean
	SumSin        float64 // for CMean
	Percentile    float64 // from TDigest
}

Result holds aggregated timeseries values read from one or more cells.

func Execute

func Execute(ctx context.Context, c executeClient, req Request, src queries.Source) (Result, error)

Execute writes the current event and reads aggregated results. The order of write vs read is controlled by IncludeCurrent.

func Read

func Read(ctx context.Context, c readClient, req Request, src queries.Source) (Result, error)

Read performs a read-only query without writing the current event.

func (Result) Average

func (r Result) Average() float64

Average returns sum/count. Returns 0 when count is zero.

func (Result) CircularMean

func (r Result) CircularMean() float64

CircularMean returns atan2(sumSin, sumCos).

func (Result) GeometricMean

func (r Result) GeometricMean() float64

GeometricMean returns exp(sumLog / count). Returns 0 when count is zero.

func (Result) STD

func (r Result) STD() float64

STD returns the sample standard deviation: sqrt((sumQ - sum*sum/count) / (count-1)). Returns 0 when count < 2.

func (Result) ZScore

func (r Result) ZScore(currentValue float64) float64

ZScore returns (currentValue - avg) / std. Returns 0 when std is zero.