Database Series Functions

Overview

These functions retrieve series records from the database at any stage of the rule evaluation process.

The db_last and db_statistic functions retrieve the last stored value or calculate statistics from other stored values. The queried series can be different from the series in the current window.

Reference

db_last

Retrieves the most recent value stored in the database for the specified series, regardless of the date of storage.

Returns Double.NaN if no matching series is found.

db_last(string m)

db_last(string m) number

Retrieves the last value for the specified metric m and the same entity and tags as defined in the current window.

Example:

value > 60 && db_last('temperature') < 30

As an alternative, if the specified metric is received in the same command, use the value() function. The value() function returns metric values set in the command without querying the database.

db_last(string m, string e)

db_last(string m, string e) number

Retrieves the last value for the specified metric m and entity e.

Specify entity e as a string literal value or with an entity field, in which case it represents the name of the entity in the current window.

Example:

value > 60 && db_last('temperature', 'sensor-01') < 30
// same as db_last('temperature')
value > 60 && db_last('temperature', entity) < 30

db_last(string m, string e, string t | [] t)

db_last(string m, string e, string t) number
db_last(string m, string e, [] t) number

Retrieves the last value for the specified metric m, entity e, and series tags t.

Tags argument t can be specified as follows:

  • Empty string '' for no series tags.
  • String containing one or multiple name=value pairs separated by comma: 'tag1=value1,tag2=value2'.
  • Map: ["tag1":"value1","tag2":"value2"]
  • The tags field representing the grouping tags of the current window.

Example:

value > 60 && db_last('temperature', 'sensor-01', 'stage=heating') < 30

db_statistic

Requires two arguments: s and i.

Argument s accepts a statistical function name such as avg which is applied to all values within the selection interval.

Argument i is the duration of the selection interval specified in 'count units', for example, '1 hour'. The end of the selection interval is set to current time.

Returns Double.NaN if no matching series are found or if no records are present within the selection interval.

db_statistic(string s, string i)

db_statistic(string s, string i) number

Retrieves an aggregated value from the database for the same metric, entity and tags as defined in the current window.

Example:

value > 60 && db_statistic('avg', '3 hour') > 30

db_statistic(string s, string i, string m)

db_statistic(string s, string i, string m) number

Retrieves an aggregated value from the database for the specified metric m and the same entity and series tags as defined in the current window.

Example:

value > 60 && db_statistic('avg', '3 hour', 'temperature') < 50

db_statistic(string s, string i, string m, string e)

db_statistic(string s, string i, string m, string e) number

Retrieves an aggregated value from the database for the specified metric m and entity e. The entity can either be specified as a string or as entity to invoke current entity in the window.

Example:

value > 60 && db_statistic('avg', '3 hour', 'temperature', 'sensor-01') < 50

db_statistic(string s, string i, string m, string e, string t | [] t)

db_statistic(string s, string i, string m, string e, string t) number
db_statistic(string s, string i, string m, string e, [] t) number

Retrieves an aggregated value from the database for the specified metric m, entity e, and series tags t.

The tags argument t can be specified as follows:

  • Empty string '' for no series tags.
  • String containing one or multiple name=value pairs separated by comma: 'tag1=value1,tag2=value2'.
  • Map: ["tag1":"value1","tag2":"value2"]
  • The tags field representing the grouping tags of the current window.

Example:

value > 60 && db_statistic('avg', '3 hour', 'temperature', 'sensor-01', '') < 50

Series Match Examples

Both db_last and db_statistic functions search the database for matching series based on the specified metric/entity/tags filter and return a numeric value for the first matched series. If the series in the current window has tags which are not collected by the specified metric and entity, those tags are excluded from the filter.

Tags : No Tags

In the example below, the db_last('cpu_busy') function ignores the tags mount_point and file_system because the tags are not collected by the metric cpu_busy.

  • Current Window
metric = disk_used
entity = nurswgvml007
tags   = mount_point=/,file_system=/sda
  • Expression
db_last('cpu_busy') > 10
  • Search Filter
metric = cpu_busy
entity = nurswgvml007
tags   = [empty - no tags]
  • Matched Series
metric = cpu_busy
entity = nurswgvml007
tags   = no tags

Same Tags

In this example, the function db_last('disk_used_percent') uses the same series tags as in the current window because all of these tags are collected by the metric disk_used_percent.

  • Current Window
metric = disk_used
entity = nurswgvml007
tags   = mount_point=/,file_system=/sda
  • Expression
db_last('disk_used_percent') > 90
  • Search Filter
metric = disk_used_percent
entity = nurswgvml007
tags   = mount_point=/,file_system=/sda
  • Matched Series
metric = cpu_busy
entity = nurswgvml007
tags   = mount_point=/,file_system=/sda

No Tags : Tags

In this example, the function db_last('disk_used_percent') searches for a series with any tags configuration; the metric cpu_busy in the current window has no tags. If the search matches multiple series, the first series is returned. To better control which series is matched, use db_last('disk_used_percent', entity, 'mount_point=/') syntax.

  • Current Window
metric = cpu_busy
entity = nurswgvml007
tags   = [empty - no tags]
  • Expression
db_last('disk_used_percent') > 90
  • Search Filter
metric = disk_used_percent
entity = nurswgvml007
tags   = [empty - no tags]
  • Matched Series
metric = disk_used_percent
entity = nurswgvml007
tags   = mount_point=/,file_system=/sda

Different Tags

In this example, the function db_last('io_disk_percent_util') searches for the first series with any tags configuration; the metrics io_disk_percent_util and disk_used have different non-intersecting tag sets. If the search matches multiple series, the first series is returned. To better control which series is matched, use db_last('io_disk_percent_util', entity, 'device=sda') syntax.

  • Current Window
metric = disk_used_percent
entity = nurswgvml007
tags   = mount_point=/,file_system=/sda
  • Expression
db_last('io_disk_percent_util') > 90
  • Search Filter
metric = io_disk_percent_util
entity = nurswgvml007
tags   = [empty - no tags - because there are no intersecting tag names]
  • Matched Series
metric = io_disk_percent_util
entity = nurswgvml007
tags   = device=sda