This is a reference manual for the Cloud Monitoring Monitoring Query Language.It covers the following topics:

• The data model underlying the time series database that theMonitoring Query Language accesses.

• The structure and semantics of queries.

• A description of each of the operations and functions that aquery is built from.

Data Model

Cloud Monitoring uses a time series database that contains all the measurementsit has ingested about each thing it is monitoring (known as a monitored resource).This describes the logical structure of that database.

The fundamental element is atime series whose data consists of observationsof the monitored resource being monitored.

Time series in the database are logically organized into relationaltables,each containing time series with a common meaning and structure. The tables arereferenced by queries that return data, generate graphs, and compute alerts.

The database also includesmetadata, which are slowly changing valuesassociated with a monitored resource and which are set by user configuration orby the service that implements the monitored-resource type.

Time series

Atime series is a named sequence ofpoints, each being a measured valueand the time to which the value applies. A time series consists of three parts:atype, which specifies the structure of the time series,anidentifier, which uniquely names the time series,and ahistory, which contains the time series data.Each of these three parts are explained in this section.

Atime series type specifies the structure of the time series identifier andthe time series history. It consists of two parts:

• Amonitored-resource type(listedhere)that names a particular kind of monitored resourcethat is monitored, such as a Compute Engine instance (gce_instance) or acloud SQL database (cloudsql_database).It has a set oflabel descriptors thatuniquely identify an instance of that type of monitored resource.

• Ametric type (listedhere)that describes a particular kind of measurement thatcan be taken on a monitored resource, for examplebytes read from disk by a Compute Engine instance is measuredby the metric namedcompute.googleapis.com/instance/disk/read_bytes_count, and thedata utilization of a cloud SQL database is measured by the metric namedcloudsql.googleapis.com/database/disk/bytes_used.The metric type specifiesthetype of measurement's value,theunits of themeasurement, and thekindof time series. It may specify label descriptors that distinguishtime series measuring different aspects of the same thing. For examplecommand indicating what command is counted intheappengine.googleapis.com/memcache/operation_count metric.

Note that a monitored resource type and a metric type are described by aMonitoredResourceDescriptor and aMetricDescriptor, respectively. Thesedescribe the types. They each contain a field namedtype which contains thename of that monitored resource or metric type.

Atime series identifier is the name of thetime series, uniquely identifying it among all time series with the same type.It consists of a set of values, one foreach of the label descriptors specified in the monitored resource and metrictypes that make up thetime series type.

• The labels from the monitored-resource type uniquely identify the particularinstance of the kind of monitored resource from which the measurements in the timeseries were taken. For example,thegce_instance monitored resource has labelsproject_id,instance_id, andzone which uniquely identify a particularGoogle Compute Engine virtual machine.

• Each label from the metric type identifies which specific kind ofmeasurement for the given metric is represented in the time series.For examplestatus indicating the status of the commands counted intheappengine.googleapis.com/memcache/operation_count metric mighthave value'HIT' for one time series that counts hits and'MISS' foranother time series that counts misses.

Atime series history is a time-ordered sequence ofpoints, eachrepresenting a simultaneous measurement of one, or, potentially, severalvalues (for example, CPU load or temperature and humidity) at some time orover some time range. A point has two elements:

• A point'sextent in time consists of anend time, which isalways present, and astart timewhich may or may not be present. Ifthe start time is not present, the point's extent is a single pointin time given by the end time. If the start time is given, it must bebefore the end time and the point's extent is the time interval startingat the start time and ending at the end time.

  No two points in a time series can have the same extent. In addition, theextents of the points in a time series are constrained by thetime series kind given by the metric type asdescribed below.

• A point'svalue represents a simultaneousmeasurement of one, or, potentially, severalvalues (for example, CPU load or temperature and humidity) that appliesto the time givenby the point's extent. The metric type describes each measurementvalue, giving ita name and avalue type for each. If there aremultiple measurement values, they are in a particular order and can bereference by their index in that order.

  A typical time series stored in the time series database has a singlevalue in each point. The name of the metric in the time series type isa URI and the name of the single value is the part of the metric nameafter the last/.For example, the metricappengine.googleapis.com/memcache/operation_count has a value column namedoperation_count.

  A time series that is the output of aquery may have multiple points whose type, name, and order are given bythe query.

  The metric type may also specifyunits of measurementfor the time series value if it is of typeInt,Double, orDistribution. The units are given using a subset of theUnified Codefor Units of Measure (UCUM). Forexample,ms for milliseconds orBy for bytes.SeeUnits of Measure for the details.

Each value in a point has a particularvalue type, whichis specified by the metrictype in the time series type. Also each label in the time seriesidentifier has a value type, given by thelabel descriptorin the time series type's monitored resource or metric type. The value types areas follows.

• Int: A 64-bit signed integer.

• String: A UTF-8 encoded Unicode string.

• Bool: A boolean value.

• Double: A 64-bit IEEE floating point value.

• Distribution: A complex value containing ahistogram and statistics that provide a summary description of a population(set) ofDouble values. The parts of this value are as follows:

  • Acount of the number of values in the population.
  • Thesum of the values in the population.
  • The sum of squared deviation of the values in the population.
  • Abucket specification indicating the boundariesbetween buckets in the histogram. A bucket contains a count of thevalues that fall between the lower and upper bound of the bucket.
  • A histogram giving the number of values that fall into each bucket.

  These parts are enough to additionally compute the populationmean,variance,standard deviation, and estimates ofpercentiles.

A point value's type may be any of the above. A time series identifier labeltype may only beString,Int, orBool

In addition to these types, there are two further types thatare in the start and end time of a point or are used to describetimes and durations in queries.

• Date: A particular point in time measured as thedistance since the Unix epoch. It is a time-zone-independentrepresentation of a point in time. The start and end time of a point areof this type.

• Duration: A length of time. This time does nothave a particular unit of measurement (although resolution is to themicrosecond level) but takes on a particular unit (e.g. seconds) whenconverted to anInt orDouble.

The set of values for each type (exceptDate andDuration) includes avalue calledno-value which indicates that there is nospecific value. This is used in two cases:

• When no specific value is known, for example when there is an error (such asdividing by 0) that prevents the computation of a value.

• No-value will be the value of a label in a time series identifier when thelabel is required by the time series type but no value is known for it.This may happen in cases where no value is known when the metric iscollected or if the time series was generated by a query and the computationgenerating the label value did not produce a value. Note that no-value isa distinct value and thus distinguishes the time series identifier from anyother that has an actual value for the given label.

No-value is distinct from an IEEE NaN and from a string value that is the emptystring. It is not possible for any value in a point to be no-value.

Thetime series kind describes the meaning of thevalues of the points in a time series and constrains eachpoint'sextents. There are three time series kinds:

• Gauge:   The value of a point inaGauge time series is a measurement taken at the point's end time.A point in aGauge stream does not have a start time so its extent is asingle point in time. The value of a point may represent one of thefollowing things:

  • Asample taken of some variable (such as the length of a queue or anamount of memory in use).

  • Astate quality that is true at the point's time andwill remain true until the time of the next point.

  • Asummary of some quantity (mean, max, etc.) that applies to theperiod between the point and the next earlier point in the time series.

• Delta:   For numeric values (Int orDouble), each pointrepresents the change in some measured value over the point'sextent, that is to saybetween the point's start time, which is present, and end time.For a Distribution's value, it has apopulation of the numeric values that arose during the point's extent.ADelta time series kind must have a value of typeInt,Double, orDistribution.

  For aDelta time series, the extents of any two points cannot overlap, soeach point represents an independent change in the measured value (numeric)or disjoint population of values (Distribution). Ideally, the extent ofeach point starts immediately after the extent of the next earlier point sothe time series is a complete description of the range of time it covers.

• Cumulative:   This can be thought of as aDelta time series with overlapping extents. The constraint is that, iftwo points have overlapping extents, they must have the same start time.Thus each point represents a cumulative increase in some measured valueover the last point with a common start time.

  Cumulative metrics are a robust way to collect time series from anexternal source of data:

  • The source is not required to reset counters or accumulators eachtime a value is collected and can be be easily monitored atmultiple periods.

  • Accumulated counts are not lost if some points are missing; thenext point has all the counts since the start time, including thosefrom the missing point. Only temporal resolution is lost.

  In queries, however, cumulative time series are not often observed. To makeoperations on time series returned from queries more straightforward, whena cumulative time series is fetched, it is automatically converted into adelta time series by making each point's extent start at the time of thenext earlier point and making its value be the change since that nextearlier point. This does not change the information present but makes eachpoint independent of the others. (This can be overridden byfetch_cumulative.)

  For a time series whose points have more than one value, each value has atime series kind which can only beGauge orDelta. If any value hasDelta kind, then the overall metric hasDelta kind (and thus each pointhas a start and end time). Otherwise, the metric hasGauge kind (and onlyend time).

Tables

All time series with the sametime series type(monitored-resource type and metrictype) are logically organized into a relationaltable. The table hasatable name which consists of themonitored-resource type name followed by the metric type name.

A table has one row for each point in each of the time series included in it.The table has the following kinds of columns:

• Time series identifier columns, One column for eachtime series identifier label as specified by themonitored resource and metric types. The name of the column is the name of thelabel (itskey)and the type of the column is the value type of the label. Ifa monitored resource label and a metric label have the same name, the name ofthe metric label column hasmetric. prepended to it.

  A time series is made up of all the rows in a table with the same value foreach of the corresponding time series idenfiter columns.

• Time column or columns, derived from theextent of the points in the time series. There is always oneend time column that is accessed by thefunctionend() (we don't actually give the column a name). If themetric is ofDelta time series kind, then there is a start time columnaccessed by the functionstart(). (There is also a starttime column for metrics with Cumulative time series kind.) Both columnshave values of typeDate.

• Value columns, one for eachvalue in thevalue of the points of the time series.Each column has the name and type given of that value and the value columnsare in the same order as that given by the metric type.If there is a monitored resource or metric label with the same name as a valuename, the value name given by the metric type is prefixed withvalue. to form the column name.

All the points in one time series have the same value in the time seriesidentifier columns and these columns uniquely identify time series. The timeseries columns plus the end time column make up the table's primary key,uniquely identifying a row and thus a point.

The above describes astored table consisting of time series that are storedin the database. A query takesstored tables as the initial inputs andperforms successive table operations (filtering, aggregating, joining, etc),yielding intermediatederived tables as the output from these table operations.

A derived table has the same structure as a stored table with these differences:

• The table will still be associated with a monitored-resource type if thetransformation that produced it preserved all the monitored resourcelabel columns.Otherwise it is not associated with a monitored-resource type.This is important formetadata (described in the next section).

• The table is described by a table type rather than bya monitored-resource typeand metric type. The table type is the same as a metric type exceptthat the set of labels includes all the columns of the time seriesidentifier. Depending on the actual derivation of the table, the timeseries identifier columns may have no relation to the columns specifiedby any actual monitored-resource type or metric type.

• A derived table does not have a name.

Metadata

A monitored-resource typecan havemetadata types, each of which associates avalue with every instance of that particular monitored-resource type. Each metadatatype has a name and a value type (which isString,Int, orBool).

There are two kinds of metadata:

• System metadata which is created by the service that creates and managesthe monitored resource. System metadata has a name of the formmetadata.system_labels.<key>, where<key> identifies a specifickind of metadata.

• User metadata which is present when a service allows the user to attachlabels toa specific monitored resource. User metadata has a name of the formmetadata.user_labels.<key>, where<key> is the key of the label theuser has attached to the entity. For example:metadata.user_labels.my_key. The value of user metadata isalways of typeString.

A table (stored or derived) that is associated with a monitored resourcecan be considered to have additional virtual value columns, one for eachmetadata type associated with the monitored-resource type.For each row in the table, ametadata column has the value of that metadata at the time of the row's endtime column. These additional metadata columns are not actually part of thetable, but they can be referenced in query expressions as if they were bygiving the name of the metadata in the expressions that operate on a table row.

Alignment

A time series istemporally aligned (or justaligned) if the end time ofits points occur only at regular intervals. We say a time series is alignedwith respect to a particular alignment base time and period if everypoint in the time series has an end time that is some multiple of thealignment period before (or after) the alignment base time. For example,with an alignment base time of 10:03 and an alignment period of 5 minutes,09:48, 09:53, 09:58, 10:03, 10:08 would all be valid end times for points.

If a table's time series haveDelta time series kind then the start time ofeach point must be earlier than the end time by the duration of the period,making the duration of every point be of equal length. A table withCumulative start times cannot be aligned because it is not, in general,possible to make the start times of points line up between different timeseries.

If all the time series that make up a table are aligned with respect to thesame alignment time and period, then the table is aligned with respectto that time and period.

When a table is aligned, the points in different time series line up with eachother in time. This makes it possible to do operations combining differenttime series. For example, if we want to get the time series that isthe sum of some metric over all of our monitored resources,we need the points in the individual time series to 'line up', that is, havethe same alignment. Then the value of points in the resulting time series isthe sum of values of the points at the same time in the individual time series.

Syntax and Semantics

Lexical Elements

The text of a query is made up of a sequence oftokens which are described inthe followinggrammar with these rules:

• A token is described by one of the all-capitalized non-terminal symbols inthe grammar below.
• A token other thanbase_string has no white space within it. White spaceis space, tab, newline, and comments. A comment is any text, not in abase_string starting with# and ending with a newline.
• White space between tokens is ignored, other than to separate tokens.
• Two adjacent tokens must be separated by white space if this grammar wouldallow them to be recognized as a single token other thanBARE_NAME (whichis only recognized in certain contexts).

ID : letter { letter_num_under } .QUOTED_COLUMN : ( 'c' | 'C' ) base_string .BARE_NAME : ( '/' | letter_num_under ) { letter_num_under | '.' | '/' | '-' } .NUMBER : digit { digit } [ fraction | '.' ] [ exponent ] | fraction [exponent] .STRING : [ 'r' | 'R' ] base_string .DURATION : digit { digit } ( 's' | 'ms' | 'us' | 'm' | 'h' | 'd' | 'w' ) .DATE : ( 'd' | 'D' ) base_string .letter_num_under : letter | digit | '_' .base_string : '\'' any-but-quote '\'' | '"' any-but-quote-quote '"' .fraction : '.' digit { digit } .exponent : ( 'e' | 'E' ) [ '-' | '+' ] digit { digit } .letter - an ASCII letterdigit  - an ASCII digitany-but-quote - any Unicode character except the ASCII control codes or `'`.any-but-quote-quote - any Unicode character except the ASCII control codes or `"'.

Identifiers (ID) are used to name the builtin table operations and functionsthat are part of the Monitoring Query Language and to name columns and metadatain expressions. The syntax distinguishes between a place that anID can be atable operation or function name and a place that anID can be a column name,so there are no "reserved" identifiers that can't be used as column names. AQUOTED_COLUMN is used to give the name of a column that will not parse as anidentifier. Example:c'total cpu'

TheNUMBER,STRING,DURATION, andDATE tokens identify literal values.ANUMBER can be followed by aunit which gives theunits of measure of that literal value as aSTRING.ASTRING may contain Unicode characters. If it is not prefixed byr orR, the normal escape sequences will be recognized. The suffix of aDURATIONindicates how a time duration is being denominated: seconds, milliseconds,microseconds, minutes, hours, days, or weeks. Thebase_string in a datecontains a date in the form2010/06/23-19:32:15-07:00, where the first- canbe a space and the timezone (-07:00) can be dropped (as can the seconds,minutes, or hours).

The remaining tokens are punctuation and operator tokens that appear in quotesin the grammar that follows (e.g.'^' or'<=').These tokens are  ^,  <=,  <,==,  = =~,  >=, >,  ||,  |,  _,  -,  ,, ;,  ::,  :,  !=,  <>,  !~, !,  //, /,.,  (,  ),  [,  ],  {,  },  *,  &&,  %,  +.

Query Structure

A query is made up of a sequence of table operations (table_op),joined together by pipe operators (|). Each table operationtakes tables as inputs and produces tables asoutput. The tables output by one table operation are piped into the nexttable operation which consumes them to produce its own table output.

query : table_op { '|' table_op } .table_op : basic_table_op | grouped_table_op | shortcut_table_op .basic_table_op : ID [ arg { ',' arg } ] .arg : table_name | expr | map .grouped_table_op:  '{' query { ';' query } '}' .

There are three kinds of table operations(table_op):

• Abasic_table_opstarts with anID thatnames the kind of operation to be done (as describedhere). This is followed by arguments (arg) whichprovide details about what the table operation will do. Each kind ofbasic_table_op takes zero, one, or many tables as input and producesone table as output.

• Agrouped_table_opconsists of anordered list of queries. Each of the queries produces one table and theresult of thegrouped_table_op is an ordered list of these tables. Each ofthe queries takes as input the same zero or more input tables that are theinput to thegrouped_table_op.

• Ashortcut_table_opis a shortcutnotation (describedhere) for abasic_table_op.

The tables output by onetable_op are passed by the pipe operator (|) asinput to the nexttable_op. The following are the rules of passing tablesthat are output by one table operation to the left of a pipe operator (calledthe producer) to a table operation to the right of the pipe operator (calledthe consumer):

• A table operation that takes no table input cannot be a consumer.

• For a producer that outputs a single table and a consumer that takes asingle table, the producer output table is an input to the consumer.

• For a producer that outputs multiple tables and a consumer that takes asingle table, the consumer is applied separately to each input table and theoutput of the consumer table operation is one table for each input table.

• For a producer that outputs multiple tables and a consumer that takesmultiple tables, all the produced tables are input to the consumer.

• For a producer that produces a single table and a consumer that is agrouped_table_op, the single table is the input to the first tableoperation of eachquery in thegrouped_table_op.

• It is not valid for agrouped_table_op to be a consumer for a producerthat produces multiple tables.

• The lasttable_op in eachquery in agrouped_table_op must produceonly one table.

The table operation's 'arg' elements provide information to the table operationabout how it should process its input tables into an output table.Anarg can be one of three things:

• Atable name (table_name), which names a table or is partof the name of a table that is to be fetched from the Cloud Monitoring database.

• Anexpression (expr), which is a formula for computing avalue. This can be a literal value that is known statically or it can be avalue computed from the column values of one or more rows from the inputtable or tables of the table operation.

• Amap (map), which describes how to compute the columns in theoutput table of a table operation. Amap contains one or moreexpr thatcompute the values of the columns.

Table Names

Atable_name names amonitored-resource type, ametric type, a group, or atable. These are used intable operations that fetch tables from the time-series database for furtherprocessing.

table_name : name { '::' name } .name : string | BARE_NAME | ID .

A singlename refers to a monitored-resource type or a metric type, for examplethe monitored-resource typegce_instance oraws_dynamodb_table or the metric typeloadbalancing.googleapis.com/http/backend_latencies.

A monitored-resource type can also be named using a group name orby a monitored-resource typename followed by:: and a group name. The former can be used whenthe group specifies a single monitored-resource type and the latter is used when thegroup does not.

A stored table is given by a monitored-resource type name followed by:: and ametric type name. For examplegce_instance :: loadbalancing.googleapis.com/http/backend_latencies.

Expressions

An expression (expr) is a formula for computing a value. It is used as anargument to a table operation and helps describe the transformationthat the table operation will perform on its input table or tables. Anexprcan be a literal expression or it can be a dynamic expression.

If anexpr is literal, it is composed only of literal values and simplefunction calls whose arguments are literal values. The value of such anexpression is determined before the query is applied to any tables.

If anexpr is dynamic it can contain references to table columnsand is used to compute a value from one or more rows from the input table.There are three kinds of dynamic expressions:

• Value expression    A value expression produces a value foreach input table row that it is applied to. It may contain references totable columns and, when evaluated for one input row, those referencesevaluate to the corresponding column values in the row.

• Aggregating expression     An aggregatingexpression produces avalue for a set of input table rows. It can be decomposed into three parts:

  • One or more value expressions that are applied individually to eachinput row to produce a value for each row. These value expressions arearguments to aggregation functions.

  • One or moreaggregation functions which take acollection of input values produced by the value expression(s) andreduce them to a single resulting value.

  • An outer expression over the aggregation functions that take the valuesthat result from the aggregation functions and produce the value of theexpression as a whole.

  For example in the aggregating expressionsum(if(status >= 500, val(), 0)) / sum(val()) the parts are as follows:

  • The value expressions areif(status >= 500, val(), 0) andval().These will be applied to each input row to create two collections ofvalues.

  • The aggregators are the twosum function calls, eachtaking as input the collections of values produced by the valueexpression that is its argument.

  • The outer expression is the division operator (/) which will beapplied to the final output of each of thesum aggregation functionsto produce the value of the overall expression.

• Aligning expression;    An aligning expression consists of a single call onanaligning function. The aligning function producesan output value from an input time series and is used bythealign to produce analigned table.

Each expression is composed ofopnd elements (definedbelow)connected by operators.

expr : term { infix_op term } .term : { prefix_op } opnd .infix_op : '&&' | '||' | '^'         | '==' | '=' | '!=' | '<>' | '<' | '>' | '<=' | '>=' | '=~' | '!~'         | '+' | '-'         | '*' | '/' | '//' | '%' .prefix_op : '+' | '-' | '!' .

The operators behave in the usual way according to precedence. The followingtable arranges operators in five groups. All the operators in a group have thesame precedence, with higher groups bindingmore tightly. Operators of the same precedence are applied left to right.Each operator corresponds to a function, given in the table,which is applied to its operands.

The prefix operators+,-, and! correspond to the unary functionspos,neg, andnot respectivelyand are applied before any infix operator.

Thusa < b && a + b + c / -d == 5 is equivalent to(a < b) && (((a + b) + (c / (-d))) == 5), which in turn is equivalent toand(lt(a, b), eq(add(add(a, b), div(c, neg(d))), 5)).

The operators operate on operands (opnd).

opnd : literal | column_meta_name | '_' | '(' expr ')' | call_chain .literal : NUMBER [ unit ] | string | DURATION | DATE .unit : STRINGstring : STRING { STRING } .column_meta_name : id { '.' id } .id : ID | QUOTED_COLUMN .

Eachopnd corresponds to a particular way of computing a value.

• literal is the value of the given literal token.

  • A NUMBER literal can be followed by aunit which gives theunits of measure of the literal value, forexample33 'By' for 33 bytes.

  • Astring is made up of one or moreSTRING tokens that areconcatenated into one string value. Thus'a-' 'b' has the samevalue as'a-b'.

• column_meta_name names a column or a virtual metadata column in the inputtable and evaluates to the value of that column in the input row theexpression is applied to.

• _ represents the default value. This can only be given as an actualargument to an optional formal argument.

• '(' expr ')' is a parenthesized expression that is just the value of theexpr.

• call_chain is one or more chained function calls:

call_chain : [ ID arg_list ] { '.' call } .arg_list : '(' [ expr { ',' expr } [ ',' ] ] ')' .call : ID [ arg_list ] .

EachID in a call_chain names afunction that is applied tozero or more arguments. The arguments to a function call can come from thevalue columns of the input table, from the result of an earliercall in thecall chain, or from the value ofexpr in anarg_list.

• If the call chain starts with anID (and no. before it), then thearguments to the called function are given by theexpr in the followingarg_list.

  For example,add(error_count, 1) applies the functionadd to twoarguments: thecolumn_meta_nameerror_count and theliteral1. Thiswould be equivalent toerror_count + 1.

• If acall_chain starts with a'.' call, then the value columnsof the input table are the first argument to the called function. If thecall has anarg_list, then thearg_list provides additionalarguments.

  For example,.div applied to a table with value columnsnum anddenwould be equivalent todiv(num, den) or justnum / den.The expression.add(3) applied toa table with a single value columncount would be equivalent toadd(count, 3) or justcount + 3

• The function called by acall other than the first in a call chain takesas its first argument, the output of the previously called function in thecall chain. If thecall has anarg_list, then thearg_list providesadditional arguments.

  For example.mul(3).div(4) applied to a table with a single valuecolumnerror_count would be equivalent todiv(.mul(3), 4) which isequivalent todiv(mul(error_count, 3), 4) which is equivalent toerror_count * 3 / 4 or(error_count * 3) / 4.

Note that the end and start time columns in a table do not have column names.The value of the time columns are accessed using theendandstart functions.

Maps

Amap computes values for columns in an output row and gives them names.Depending on where themap is used, it will either be a time series identifiermap that computes the time series identifier columns of the output row or avaluemap that computes the value columns of the output row.

map : [ modifier ] '[' [ maplet { ',' maplet } ] ']' .modifier : ID .maplet : [ column_name ':' ] expr .column_name : ID | QUOTED_COLUMN .

Eachexpr in themaplet computes the value of an output column and thecolumn_name gives the name of the column. If nocolumn_name is given,one is constructed from theexpr. If theexpr is just the name of aninput column, thecolumn_name is the same. If functions are applied,these are added to the name. For examplesum(error_count / 3) would get thenameerror_count_div_sum.

The output columns that themap computes (time series identifier or value)come from themaplets in themap and from the corresponding kind of columns(time series identifier or value) in the input table. How this is done dependson themodifier:

• Nomodifier     The corresponding columns of the output rowconsist of exactly those columns specified by amaplet in themap. Thename of the column either is explicitly given by anID orQUOTED_COLUMNor is derived from the form of theexpr. The value of the column in theoutput row is the value of theexpr.

  Eachmaplet must have a column name (explicit or derived) that is uniqueamong all the columns in the output table.

  For example, applying[ratio: num/den] as a value columnmap to a tablewith value columnsnum andden would result in an output table withvalue columnratio, where theratio column value is the ratio of the twoinput colums.

  Applying[zone] as a time series identifiermap to a table with timeseries identifier columnsproject_id,zone, andinstance would resultin a table with just azone time series identifier column whose value isthe same as thezone input table column.

• add     All of the columns of the corresponding kind (timeseries identifier or value) of the input row are included in the output row.In addition, for eachmaplet in themap, there is an additional outputcolumn whose name and value are given by themaplet.

  Eachmaplet must have a column name (explicit or derived) that is uniqueamong all the columns in the output table.

  For example, applyingadd[ratio: num/den] as a valuemap to a table withvalue columnsnum andden would result in an output table with valuecolumnsnum,den, andratio, where theratio column value isthe ratio of the other two columns.

• update     All of the columns of the corresponding kind(time series identifier or value) of the input row whose column name is notthe same as that of amaplet in themap are included in the output row.In addition, for eachmaplet in themap, there is an additional outputcolumn whose name and value are given by themaplet.

  Eachmaplet must have a column name (explicit or derived) that is uniqueamong all the columns in the output table. It may name a column of thecorresponding kind in the input that it is replacing.

  For example, the following is a time series identifiermap:

    update[job: re_extract(job, '[^-]*-(.*)', r'\1'),         kind: re_extract(job, '([^-]*)-.*', r'\1')]

  When used on a table with time series identifiercolumnsuser,job, andzone would result in an output table with timeseries identifier columnuser,job,zone, andkind.

• drop     Eachmaplet must consist of anexpr thatis just the name of an input column of the corresponding kind. The outputcolumns consist of all the input columns of the corresponding kind exceptthose that are named in anexpr in themaplet.

  Eachmaplet must not have acolumn_name and theexpr must simply namea column of the corresponding kind in the input table.

  For example, applyingdrop [job, user] as a time series identifiermapto a table with time series identifier columnsuser,job, andzonewould result in an output table with time series identifier columnzone.

• ignore     Eachmaplet must consist of anexpr thatis just a column name. If the name is the name of an input column of thecorresponding kind, that column does not appear in the output columns. Ifthemaplet column name does not name an input table column of thecorresponding kind, thatmaplet has no effect. Thus, the outputcolumns consist of all the input columns of the corresponding kind exceptthose that are named in theexpr in themaplet.

  Eachmaplet must not have acolumn_name and theexpr must simply bea column name, but it does not have to be the name of a column in the inputtable. If themaplet does not name a column in the input table, it isignored.

  For example, applyingignore [job, instance] as a time series identifiermap to a table with time series identifier columnsuser,job, andzone would result in an output table with time series identifier columnsuser andzone. The columnjob is ignored by the mapletjob,and the mapletinstance has no effect.

• rename     Eachmaplet must have an explicitcolumn_name and must have anexpr that just references a column of thecorresponding kind in the input table. The output columns are all thecolumns of the corresponding kind in the input table but if referenced in amaplet with a new name given by thecolumn_name in themaplet.

  Thecolumn_name in eachmaplet must be unique among the column names ofthe output table.

  For example, applyingrename[numerator : num, denominator : den]as a value columnmap to an input table with value columnsnum,den, andratio would result in an output table with value columnsnumerator,denominator, andratio.

Units of Measure

Every numeric value (Int,Double, andDistribution) can have a unit ofmeasure associated with it indicating the unit of measurement used by thatvalue. Units are represented by strings that follow a subset of theUnified Code forUnits of Measure (UCUM). For example a valuedenoting a number of bytes will have unit 'By' and another, denoting a rate ofbytes transferred, unit 'By/s'.

Units attach to the columns of tables produced by table operations and to thevalue of expressions. They are statically associated with the column orexpression in the same way that the type is. Any column or expression with anumeric type can have units associated with it but does not have to.

The units attached to columns in tables come from these sources:

• Metric descriptors can specify the units for the value of a metric and theseare seen in the documentation that describes metrics (for example,here).The value columns of tables produced byfetch andmetric tableoperations have the units specified by the metric descriptor.

• Output table columns that are just a copy of the column from the input tablehave the same units as the input table column. So, for example, thefiltertable operation does not change the units on any columns of its input tableand passes them on to the output.

• Theunion table operation combines multiple tables into one, and allthe tables must have the same columns. Each value column in an input tablemust have either no units attached or units that are equivalent tothe units, if any, attached to that column in every other input table. Ifunits are given for a column in any of the input tables, that column hasthose units in the output table. If none of the input tables have unitsspecified for a column, that column has no units in the output.

• For table operations that contain anexpr that computes an output tablecolumn value, the units on the output column have the units attached to thatexpr as described below.

The units attached to anexpr depend on the form of theexpr:

• Literal values by themselves do not have units. But numeric (Int orDouble) literals can be given units by following the value with a stringspecifying the unit. Thus3 "By" is anexpr with value 3, whose typeisInt, and whose unit is bytes (By).

• Column reference expressions get units from the named column in the inputtable, if it has units.

• Functions and operators derive the unit of measurement for their outputvalues from the unit of their input values. So, ifamount has unitByandtime has units, thenamount / time has unitBy/s. Functionsthat take two numeric arguments typically require both arguments to haveunits or neither argument to have units. The documentation for each functiondescribes the treatment of units of measurement by that function.

  Many functions have a requirement about unit agreement. For exampleaddrequires both of its operands, if they have units, to have the same unit.These requirements are described in the documentation for each function.

• The functionsscale andcast_units have functionality specific to units.

  Thescale function will multiply a value with one unitby a scale factor that converts it to a value with a different unit.So forexprev with unit"KiBy" (kibi-bytes),scale(ev, "By") will result in multiplyingev by1024 and giving the result unitBy. It is equivalent toev * 1024'By/KiBy'.

  Thecast_units function returns its argument with agiven unit regardless of the argument's original unit, if any.Socast_units(ev, 'By/s') results in the value ofev,unchanged but with the unitBy/s.

The subset of UCUM units supported by MQL is given by string values that follow this grammar:

digit : '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'exponent : [ '+' | '-' ] { digit }simple_unit : [ PREFIX_SYMBOL ] ATOM_SYMBOLannotatable : '10^' exponent | simple_unitcomponent : annotatable [ annotation ] | '1'annotation : “{” ANNOTATION-STRING “}” | annotatable | annotationunit : component { '.' component } { '/' component }

Asimple_unit specifies a unit given by anATOM_SYMBOL optionally prefixedby a scaling factor given by aPREFIX_SYMBOL

AnATOM_SYMBOL gives a basic unit of measure:

APREFIX_SYMBOL gives a scale factor for the basic unit it precedes:

A dimensionless unit can be given as1 or as a power of 10 (10^ exponentsuch as10^2). The unit1 is the unit given to most counter metrics. Thisalso supports the dimensionless ratio scaled to percent%. So10^-2 and% are the same units. To put it another way, adding 3 to a percentage isthe same as adding .03 to the corresponding ratio. Theexponent is limited tothe range of -128 to 127.

Anannotation is a comment that may be attached to anannotatable(simple_unit or power of 10) and does not change the meaning of the unit. Anannotation not attached to a unit is treated as if it was attached to the unit1. Thus{queries}/s is equivalent to1/s, with the1 unit decoratedwith{queries}.

A unit string can be made up of multiplecomponent strings, connected by.or/. The. connector indicates multiplication of the units and the/connector, division. The multiplication and division are applied left toright. The subset of UCUM units that MQL supports requires all divisionconnectors to come after multiplication connectors. This avoids the problem ofwriting the units of acceleration asm/s.s whenm/s/s is what is wanted.Note that in UCUM units,m/s.s is the same asm.s/s or justm.

Two unit strings areequivalent if they have the samedimension andscale, regardless of annotations. The dimension and scale are determined inthe conventional way:

• Eachcomponent is either dimensionless or has a dimension that is somecombination oftime,length,data,mass, orcharge. For example bothbit andBy have dimensiondata. The dimensions of a unit string arefound by converting each annotatable to its dimension, multiplying anddividing these as given by the unit string, and canceling dimensions thatappear in the numerator and denominator. Thusb.h/s (bit-hour per second)has dimensiondata timestime divided bytime, and thetimedimension cancels to leave dimensiondata.

• Each annotatable has a scale relative to the basic units of its dimension.For exampleh (hour) has dimensiontime with basic units and a scalefactor of 3600 (every hour is 3600 seconds). The scale factor of a unitstring is the combination of the scale factors of eachcomponent combinedby multiplication and division.

Numeric literals can be given units by following the value with the string forthe desired unit of measurement. So3 "m/s" is the value3 with unitm/sand10.8 "km/h" represents the same speed as the value10.8 with unitkm/h.

A value with one unit can be scaled to have a different unit with the samedimension using thescale function. For example,MiBy andBy have the dimensiondata with scale factor 8*1024 and 8 respectively(relative to the base unit of dimensiondata, which isbit). A valuexhaving unitMiBy can be scaled to a value having unitBy by theexpressionscale(x, "By"). This multipliesx by 1024 and results in avalue with unitBy. It is equivalent to the expressionx * 1024 "By/MiBy",size * 1024 "By/MiBy" and the unit of the resulting expression isMiBy.By/MiBy or justBy.

Thescale function checks that the unit requested hasthe same dimension as the unit of the value being scaled.

Ifsize is a column whose value hasunit "KiBy", then the expressionscale(size, "By") is the same assize * 1024 "By/KiBy" and the unit of the resulting expression isMiBy.By/MiBy or justBy.

There are a limited number of cases where MQL will automaticallyadjust or supply units for a value.

• For a functionf that require two arguments with equivalent units (add,sub, any of the numeric comparison operators,if, andor_else),one of the arguments may be a call on thescale function without thesecond unit argument. If the unit of the other argument tof has thesame dimension as the unit of the argument to thescale function,then thescale function's second argument will be automatically set to theunits of the other argument tof. This causes the units of two argumentstof to be equivalent andf will be able to operate.

  For example, The+ operator requires its arguments to have equivalentunits because it makes no sense to add two numbers with different units.Ifcache_size has unitBy andheap_size has unitMiBy, then the expressionscale(cache_size) + heap_size is equivalentto the expressionscale(cache_size, "MiBy") + heap_size

• For any comparison function, if one argument is a literal witha unit having the same dimension but different scale than the otherargument, the literal is scaled to have the same scale.

  For example, if 'cache_size' has unitBy, the expressioncache_size < 3 "KiBy" is equivalent to the expressioncache_size < 3072 "By". Note that this is not the same ascache_size < scale(3 "KiBy", "By") ifcache_size istypeInt, becausescale will convert its result to typeDouble whichmight reduce the precision of the comparison. The integer scaling in thiscase takes into account proper rounding and handling of overflow for theparticular comparison done.

• For either argument ofmul or the divisor ofdiv, a literal without aunit will be given unit '1'. This takes into account scaling operationsthat arenot intended to change units (for example, asking what if therate were double what it is). To change units, it is best to usescale,which will automatically select the right scale factor for the conversion.

Unit errors are treated as warnings when evaluating a query, so the querywill still produce results. When defining an alert, unit errors are aretreated as real errors and will prevent the alert from being defined.

It is important to realize thatDuration andDate are NOT numeric types anddo not have units. TheDuration value60s is a non-numeric length of time,exactly the same length of time as1m or60000ms. The expression60s ==60000ms is valid and true.

A numeric value with unit of time is different. The numbers3 'min' and180 's' are two different numeric values (3 and 180) with different units. Withoutscaling, it is not valid to compare them.

Thescale function will convertDuration andDate values toDoublevalues with units. For examplescale(60s, "min"),scale(1m, "min"), andscale(60000ms, "min") will all return the double value1.0 with unitmin.

Table Operation Shortcuts

A shortcut is a simplified way of specifying a basic table operation.

shortcut_table_op : shortcut { ',' arg } .shortcut : table_name | '(' expr ')' | map | DURATION .

There are a number of forms of shortcut table operations, each of whichdesignates a kind of basic table operation:

• A function promotion shortcut looks like a normal table operation, but the table operation starts with anID that names a function instead of a table operation and thearg elements that follow (which are allexpr form) are the arguments to the function.

  The function ispromoted by providing a table operation that the function becomes an argument for. The value column or columns of the input table become the first arguments to the function, as if it had been preceded by a. operator. The specific promotions are as follows:

  • An ordinary function becomes the argument of avaluetable operation, computing the single value column of its output table.

    For example,  | add 3   is a shortcut for  value[.add(3)]   and  | div   is a shortcut for  |value [.div].

  • An aggregating function becomes the second argument of agroup_by table operation whose first argument isthe emptymap ([ ]). Thus the function computes the single valuecolumn of an output table with no time series identifier columns (a tablewith a single time series).

    For example  | min   is a shortcut for  | group_by[], [.min].

  • An aligning function becomes the argument to analigntable operation, thus performing its designated kind of alignment on thetime-series of the input table.

    For example,  | delta 10m   is a shortcut for the tableoperation  | align [.delta(10m)].

• A naming shortcut starts with atable_name which is used as the argument toresource,metric, orfetch table operation, depending on what kind of thing thetable_name names.

  For example,  | gce_instance   is a shortcut for the table operation  | resource gce_instance   and  | gce_instance :: compute/instance/cpu/usage_time   is shortcut for  | fetch gce_instance :: compute/instance/cpu/usage_time.

• A filtering shortcut consists of a parenthesizedexpr which becomes the predicate in afilter table operation.

  For example,  | (job == 'search')   is a shortcut for  | filter job == 'search'.

• A grouping shortcut starts with amap which becomes the first argument to agroup_by table operation. It may be followed by anarg that is amap that describes the aggregation that computes the value columns of the output table.

  For example,  | [zone]   is a shortcut for  | group_by [zone].

• A duration shortcut starts with aDURATION with no followingarg. It becomes afor table operation, giving the overall extent in time of the query operation.

  For example,  | 10m   is a shortcut for  | for 10m.

Table Operation and Function Descriptions

Each Monitoring Query Language table operation and function descriptionstarts with a documentation signature indicating the tableinputs (for table operations) and the types of arguments that can be given forthe table operation or function. This section describes the form ofthese signatures.

Note that these signatures are NOT part of the Monitoring Query Language itself.They are used to describe the Monitoring Query Language.

A table operation signature optionally starts with a type that describes theinput table(s) to the table operations followed by the name of the tableoperation followed by an argument list describing the valid arguments to thetable operation. For example, a signature of thegroup_by table operation:

Table  | group_by  tsid: RowToTSID,  window: lit-WindowDuration,  value: [ RowSetToVal ]

This table operation takes aTable as input (the most common case), and has 3potential arguments, described bytsid: RowToTSID,window:lit-WindowDuration, andvalue: [ RowSetToVal ].

The input table and| are optional and if not given the table operation doesnot take an input table. The input table specification is one of the following:

• Table   The input to the table operation is a single table.
• Table++   The table operation takes two or more tablesas input.
• Resource   The table operation takes a collection of tables specified by a monitored-resource type (all tables containing time series whose type includes a particular monitored-resource type).
• ResourceOrTable   EitherTable orResource is allowed as input.

Each argument descriptor in the argument list that follows the name of thetable operation has the following parts:

• It may be preceded by an argument name, e.g.tsid:, which gives a namethat the argument can be referenced by in descriptions.

• It may be enclosed in[], in which case it is optional and theactual argument can be given as_ or omitted if the actual argument ispositioned after all explicitly given arguments.

• It may have alit- prefix that indicates the argument value must bea constant value known before we evaluate the query.

• It always has the name of avalue type or a class of types(described below) that describes the allowed type of the actual argument.

• It may have a suffix giving atime series kind whichconstrains the time series kind of the input value.

The argument descriptor type name may be one of the actual types describedhere:Bool,Int,Double,Distribution,String,Duration,orDate. In that case the actual argument must be an expression of the sametype.

The following indicate that the actual argument must be atable_name thatnames a metric, monitored resource, or table, respectively:

• MetricName
• ResourceName
• TableName

An argument descriptor may name a category that indicates the actual argumentmay be an expression of one of various types:

• Num   Either anInt orDouble.
• Summable   Types of values that can be summed:Int,Double, orDistribution.
• Comparable: Types of values that can be compared:Int,Double,String,Bool,Duration,Date.
• ColumnValue: Types that are a valid column values:Int,Double,String,Bool, orDistribution.
• Windowed(Num)   ANum, potentiallyannotated bywithin,ago, orbottom functions.
• WindowDuration   ADuration,potentially annotated bywindow orsliding.
• BucketSpecification   A bucket specification for aDistribution.

A table operation may require amap argument specifying the outputrow time series identifier columns or value columns. This is indicated by oneof the following:

• RowToTSID   A map describing thetime series identifier columns of the output table.
• TSIDSel   A map namingtime series identifier columnsto be retained. Eachmaplet in themap must consist only of anexprthat names a column (ID orcolumn_name). For example,[zone, name]causes the output columns to consist only of the input time seriesidentifier columnszone andname, with all other input columns dropped.
• RowToVal   A map describing output tablevalue columns.If a non-map expression is given as an actual argument,it is promoted to be a single-element map with that expression.
• RowSetToVal   A map describing output tablevalue columns by aggregation.If a non-map expression is given as an actual argument,it is promoted to be a single-element map with that expression.
• DefaultColumns   A map describing default value columns for anouter_join.If a non-map expression is given as an actual argument,it is promoted to be a single-element map with that expression.

A function signature starts with the name of the function followed by aparenthesized argument list describing the valid arguments to the functionfollowed by a return type describing the value returned by the function. Forexample, the signature of thefraction_less_than function:

fraction_less_than(Summable,  lit-Num)   →Double

This function takes two arguments described bySummable andlit-Num andreturns a value of typeDouble. The argument list has the same elementsdescribed above for table operations. The return type can be a specificvalue type, indicating the returned value will be of that type,or one of the following:

• Num - If any of the arguments to the function areDouble,thenDouble, otherwise,Int.
• ColumnValue - The same type as the first actual argument to the function.
• LastArgType - The same type as the last actual argument to the function.
• Windowed() - The same type as theWindowed actual argument, annotatedwith theWindowed type. If theWindowed actual argument was typeInt, then the return type isWindowed(Int). (Seewithin,ago, orbottomfunctions.)

A function argument descriptor or return type may have an indicator controllingthe time series kind of the argument or result. These appear as one of thefollowing suffixes to the type:

• .Cumulative,.Delta, or.Gauge indicate the actual argument must havethe given time series kind.
• .CumulativeOK means that an actual argument can beCumulative.
• .FirstArgKind means, for return types only, the same time serieskind as the first argument to the function.

If an argument has no time series kind suffix, the argument must beGauge orDelta time series kind. If a return type has no time series kind suffix, itwill beGauge.

A function signature may also have one or more of the following notes:

• (implicit row input) This indicates the function takes the whole row asan implicit input. For example, thehash_tsid function produces a hash ofthe time series identifier columns of its input row, but does not takethose column values as explicit arguments.
• (temporal only) This is used on the signature ofaggregation functionsto indicate the function signature only applies when doingtemporal aggregation.(Other signatures for the function apply otherwise.)Note that this includes the case of both temporal aggregation andspatialaggregation are being done in the same tableoperation.
• (sliding temporal only) This is used on the signature ofaggregation functionsto indicate the function signature only applies when doingsliding temporal aggregation.(Other signatures for the function apply otherwise.)Note that this includes the case of both sliding temporal aggregation andspatial aggregation are being done in the same table operation.

Table Operations

This section describes each of the basic table operations in theMonitoring Query Language.

• Fetching
  • fetch   Produces a table from the database.
  • metric   Produces the table for a specific metric type from a set of tables.
  • fetch_cumulative   Produces a table ofCumulative time series from the database.
• Selection
  • filter   Filters rows from an input table by a predicate.
  • top   Selects the top time series by a sort-value expression.
  • bottom   Selects the bottom time series by a sort-value expression.
  • top_by   Selects time series by a sort-value expression in different groups.
  • bottom_by   Selects time series by a sort-value expression in different groups.
  • pick_bottom_rows   Picks rows by minimal sort-value expression.
  • pick_top_rows   Picks rows by maximal a sort-value expression.
• Row Modification
  • map   Rewrites the time-series identifier and value columns of each row in a table.
  • value   Rewrites the value columns of each row in a table.
  • time_shift   Shift time series forward in time.
• Time Series Alignment
  • align   Produces an aligned table using an alignment function.
• Aggregation
  • group_by   Aggregates rows by mapped time-series identifier and time window.
  • union_group_by   Aggregates rows from multiple tables.
  • unaligned_group_by   Aggregates rows by mapped time-series identifier without alignment.
• Union and Join
  • join   Natural join of multiple tables.
  • outer_join   Outer natural join of two tables.
  • union   Union of multiple tables.
• Time Horizon and Period
  • every   Specifies the period for aligned table output.
  • within   Specifies the time range of the query output.
  • graph_period   Specifies the preferred output period for drawing time series graphs.
  • window   Specifies the window for alignment operations.
• Alerting
  • condition   Add a boolean condition column to the input table.
  • absent_for   Create a condition for the absence of input.
• Miscellaneous
  • ident   Identity table operation: no change to the input table.
  • ratio   Computes the ratio of value columns of two aligned input tables.
  • filter_ratio   Computes the ratio of two filtered sums of the input value column.
  • filter_ratio_by   Computes a grouped ratio of two filtered sums of the input value column.

Fetching

The output of afetch table operation is a table retrieved by namefrom the Cloud Monitoring time series data base.

Theresource table operation's output is the set of all tablesthat have the named monitored-resource type in their name. Eachresourcemust eventually be followed by ametric table operation that selects thesingle table whose name contains that metric. Prior to themetric tableoperation, there may befilter table operations that restrict the rowsincluded in the resulting tables.

fetch   Produces a table from the database.

Signature:  fetch  name: lit-TableName

Thefetch operation fetches from the time series database the tablewhose name is thetable name given by thename argument.It is an error if the table name contains an unknown monitored-resource typeor metric type name.

This table will be empty if no metric of the given type was collected fromthe monitored resource of the given type.

If the metric isCumulative, the time series that make up the table areeffectively converted toDelta time series, where each point representsthe change in value since the next-earlier point.

Thefetch operation can also fetch the set of all tables that are based ona particular monitored resource by just giving the name of the monitored resource and notgiving a metric name. Such afetch operation must be followed by ametric operation that selects the specific tablecontaining the data for a specific metric. The only operation that may comebetween such afetch and the subsequentmetric is afilter operation, that filters based on the monitored resourcecolumns.

This form offetch is useful if we wish to fetch more than onemetric for a given monitored resource as in this example:

  fetch gce_instance | filter zone = 'asia-east1-a' |  { metric compute.googleapis.com/instance/cpu/utilization ;    metric compute.googleapis.com/instance/cpu/reserved_cores  } | join | div

This is equivalent to

  { fetch gce_instance :: compute.googleapis.com/instance/cpu/utilization ;    fetch gce_instance :: compute.googleapis.com/instance/cpu/reserved_cores  } | filter zone = 'asia-east1-a' | join | div

metric   Produces the table for a specific metric type from a set of tables.

Signature:  Resource  | metric  name: lit-MetricName

The table input to ametric table operation is a set of tables producedby afetch table operation that did not give a metricname.

Themetric table operation selects the one table from this set whosemetric name is given by thename argument and produces that table as itsoutput.

It is an error if there is no metric definition with the given name. Itproduces an empty table if there is no input table with data for the givenmetric name.

Themetric table operation is useful if we wish to fetch more than onemetric for a given monitored resource as in this example:

  fetch gce_instance | filter zone = 'asia-east1-a' |  { metric compute.googleapis.com/instance/cpu/utilization ;    metric compute.googleapis.com/instance/cpu/reserved_cores  } | join | div

This is equivalent to

  { fetch gce_instance :: compute.googleapis.com/instance/cpu/utilization ;    fetch gce_instance :: compute.googleapis.com/instance/cpu/reserved_cores  } | filter zone = 'asia-east1-a' | join | div

fetch_cumulative   Produces a table ofCumulative time series from the database.

Signature:  fetch_cumulative  name: lit-TableName

Thefetch_cumulative table operation is the same as thefetch table operation except thatCumulative metrics arenot automatically converted toDelta metrics when fetched.

Selection

The selection table operations select rows from the input table forinclusion in the output table. The type of the output table is exactly thesame as that of the input table.

filter   Filters rows from an input table by a predicate.

Signature:  ResourceOrTable  | filter  predicate: Bool

Thefilter operation evaluates itspredicate argument for eachrow in a single input table or in the collection of tables named byaresourceoperation. Exactly those rows in the input table or tables for whichpredicate evaluates to true are retained in the output table or tables.

If the input is a collection of tables, only the monitored resource labels (whichare common to all the tables) can be referenced in the predicate.

top   Selects the top time series by a sort-value expression.

Signature:  Table  | top  number: lit-Int,  sort_value: [ Windowed(Num) ]

Thetop table operation creates an output table with thenumber timeseries from the input table with the highest value computed by thesort_value argument.

Thesort_value argument is applied to rows in a time series that fallwithin a value time window. The default value time window is the same asthe query time window. Ifsort_value is an aggregating expression(e.g..min), it is an aggregation over all the rows whose end timestamp iswithin the value window. If the expression is a value expression(e.g..val(0)/.val(1)), it is applied to the youngest row, if any, withinthe value window. If there are no rows within the value windowfor a time series, or if thesort_value argument does not produce avalue for a time series, that time series is not considered for inclusionin the output.

Thewithin function can be used in thesort_valueargument to modify the value window by giving a starting time, a duration,and/or an ending time for the window.

Examples:

This selects 3 time series with the largest value for the most recent pointin the time series:

  | top 3

This selects 7 time series with the largest value for the maximum of all thepoints in the time series within the query window:

  | top 7, .max

This selects 3 time series with the largest value of themin reducerapplied to the rows in each time series that fall in a window starting 10hours ago and lasting for 1 hour:

  | top 3, .min.within(-10h, 1h)

bottom   Selects the bottom time series by a sort-value expression.

Signature:  Table  | bottom  number: lit-Int,  sort_value: [ Windowed(Num) ]

Thebottom table operation creates an output table with thenumber timeseries from the input table with the lowest value computed by thesort_value argument.

Thesort_value argument is applied to rows in a time series that fallwithin a value time window. The default value time window is the same asthe query time window. If the expression is an aggregating expression(e.g..min), it is an aggregation over all the rows whose end timestamp iswithin the value window. If the expression is a value expression(e.g..val(0)/.val(1)), it is applied to the most recent row, if any,within the value window. If there are no rows within the value windowfor a time series, or if thesort_value argument does not produce avalue for a time series, that time series is not considered for inclusionin the output.

Thewithin function can be used in thesort_valueargument to modify the value window by giving a a starting time, a duration,and/or an ending time for the window.

Examples:

  | bottom 3

Select 3 time series with the smallest value for the youngest point in thetime series.

  | bottom 7, .min

Select 7 time series with the smallest value for the minimum of all thepoints in the time series within the query window.

  | bottom 3, .max.within(10h)

This selects 3 time series with the smallest value of themax reducerapplied to the rows in each time series that fall in a window starting 10hours ago and lasting until now.

top_by   Selects time series by a sort-value expression in different groups.

Signature:  Table  | top_by  tsid: TSIDSel,  number: lit-Int,  sort_value: [ Windowed(Num) ]

Thetop_by table operation groups time series together that have the sametime-series identifier computed by thetsid argument. Within eachgroup it selects time series by the same method thattopdoes when giventhe samenumber andsort_value arguments. For each group, it computes asort value from thesort_value argument for each time series in a groupand selects thenumber time series with the largest value given bysort_value.

Thesort_value argument is applied to rows in a time series that fallwithin avalue time window. The default value time window is the same asthe query time window. If the expression is an aggregating expression (e.g..min), it is an aggregation over all the rows whose end timestamp iswithin the value window. If the expression is a value expression (e.g..val(0)/.val(1)), it is applied to the most recent row, if any, within thevalue window. If there are no rows within the value window for a timeseries, or if theWindowed(Num) argument does not produce a value for atime series, then that time series is not considered for inclusion in theoutput.

Thewithin function can be used in thesort_valueargument to modify the value window by giving a starting time, a duration,and/or an ending time for the window.

Examples:

For each group of time series with the same value of the 'zone' column, thisselects the three time series with the largest value for the most recentpoint in the time series:

  | top_by [zone], 3

The following computes the sort value for each time series as the maximumvalue of all the points in the time series. Then for each group of timeseries with the same value of theproject_id label, it selects the twotime series with the largest sort value. Note that the time seriesidentifier columns of the selected rows are not changed from the input.

  | top_by [project_id], 2, .max

The following computes the sort value for each time series as the minimumvalue of all the points in the time series whose end timestamp falls in theone-hour interval starting 10h ago. Then for each group of time series withthe same value of thezone label, it selects the time series with thelargest sort value. As above, the time series identifier columns of theselected rows are not changed from the input.

  | top_by [zone], 1, .min.within(-10h, 1h)

bottom_by   Selects time series by a sort-value expression in different groups.

Signature:  Table  | bottom_by  tsid: TSIDSel,  number: lit-Int,  sort_value: [ Windowed(Num) ]

Thebottom_by table operation groups time series together that have thesame time-series identifier computed by thetsid argument. Within eachgroup it selects time series by the same method thatbottom does when given the samenumber andsort_valuearguments. For each group, it computes thesort_value for each timeseries in a group and selectsnumber time series with the smallest sortvalue.

Thesort_value argument is applied to rows in a time series that fallwithin a value time window. The default value time window is the same asthe query time window. If the expression is an aggregating expression(e.g..min), it is an aggregation over all the rows whose end timestamp iswithin the value window. If the expression is a value expression(e.g..val(0)/.val(1)), it is applied to the youngest row, if any, withinthe value window. If there are no rows within the value windowfor a time series, or if thesort_value argument does not produce avalue for a time series, that time series is not considered for inclusionin the output.

Thewithin function can be used in thesort_valueargument to modify the value window by giving a starting time, a duration,and/or an ending time for the window.

Examples:

  | bottom_by [zone], 1

For each group of time series with the same value of the 'zone' column, thisselects the time series with the smallest value for the youngest point inthe time series.

  | bottom_by [project_id], 2, .max

For each group of time series with the same value of the 'project_id'column, this this selects the 2 time series with the smallest value for themaximum of all the points in the time series within the query window.

  | bottom_by [zone], 1, .min.within(1h)

For each group of time series with the same value of the 'zone' column, thisselects the time series with the smallest value of themin reducer appliedto the rows in each time series that fall in a window starting 10 hours agoand lasting for 1 hour.

pick_bottom_rows   Picks rows by minimal sort-value expression.

Signature:  Table  | pick_bottom_rows  number: lit-Int,  tsid: [ TSIDSel ],  sort_value: [ Num ]

Thepick_bottom_rows table operation groups rows together that have thesame time-series identifier computed by thetsid argument and the same endtime. A sort value is computed for each row by applying thesort_valueargument expression. Within each group of rows,number rows with thesmallest sort-value are selected and are added to the output unchanged.

pick_top_rows   Picks rows by maximal a sort-value expression.

Signature:  Table  | pick_top_rows  number: lit-Int,  tsid: [ TSIDSel ],  sort_value: [ Num ]

Thepick_top_rows table operation groups rows together that have the sametime-series identifier computed by thetsid argument and the same endtime. A sort value is computed for each row by applying thesort_valueargument expression. Within each group of rows,number rows with thelargest sort-value are selected and are added to the output unchanged.

Row Modification

map   Rewrites the time-series identifier and value columns of each row in a table.

Signature:  Table  | map  tsid: [ RowToTSID ],  value: [ RowToVal ]

Themap table operation applies two transformations to each of the rowsof a table, one at a time:

• If thetsid map argument is given, it is appliedto the time-series identifier columns of that row to produce thetime-series identifier columns of the corresponding output row. If thetsid map argument is not given (or given as_), then the outputtime-series identifier columns are the same as the input.

• If thevalue map argument is given, it is applied to the value columnsof the input row to produce the value columns of the output row. If theRowToVal map is not given, then the output value columns are the same asthe input.

It is a dynamic error if rows from two different time series in the inputhave the same time-series identifier columns after applying thetsid mapargument. In this case, all the rows derived from one of the two input timeseries are dropped from the output and an error message will be given.

If thetsid map contains references to value columns or time columns,then it is possible that it will split single input time series intomultiple output time series. For this reason, when thetsid mapcontains references to value columns or time columns, it is only allowed toapply it to tables whose value columns areGauge orDelta time serieskind.

value   Rewrites the value columns of each row in a table.

Signature:  Table  | value  value: RowToVal

For each row in the inputTable, theRowToVal map is applied to thecolumns of that row to produce the value columns of the corresponding outputrow. Each output row has the same time-series identifier and time columnsas the input row it was produced from and has the value columns produced bytheRowToVal map.

time_shift   Shift time series forward in time.

Signature:  Table  | time_shift  shift: lit-Duration

Each row in the input table has the amount given by theshift argumentadded to its time column or columns. This has the effect of shifting eachtime series in the table forward in time by the amount given byshift.

If the input table is aligned, then the shift amount must be an evenmultiple of the alignment period, which maintains the input table alignment.

Time Series Alignment

align   Produces an aligned table using an alignment function.

Signature:  Table  | align  aligner: [ Aligner ]

Thealign table operation uses thealignment functiongiven by itsaligner argumentto output an aligned version of its input table. Each time series in theinput table is aligned using thealigner function is applied to producean time series in the output table.

The alignment base time is the end time of the query window and thealignment period is set by one of the three following things:

• Anevery table operation that sets the period for thisalign table operation.

• The aligner function requires that the alignment period be equal to itswindow width (see thedelta).

• An external graphics interface requires a particular alignment period.

The particular method of producing aligned time series is described forthealignment function given by thealigner argument.

Aggregation

An aggregation table operation divides the rows of the input table intogroups.For each group of input rows it computes a common time-series identifierand time columns for the group, aggregate the input rows to create the valueoutput columns, and outputs a single row with the resulting time seriesidentifier, time, and value columns.

There are three kinds of aggregation

• Spatial aggregation.   This form ofaggregation computes new time series id columns for each input row andgroups all the rows with the same new time series id columns and endtime together. This kind of aggregation typically requiresalignedinput so that rows from different time series will line up in time tobe grouped together.

• Temporal aggregation.   Thisform of aggregation computes a set of valid aligned output times andcomputes a new end time for each row giving it the oldest aligned endtime that is no earlier than the row's original end time. Rows with thesame time-series identifier and end time are grouped together.

• Sliding temporal aggregation.  This form of aggregation is similar to temporal aggregation except thata row may be included in more than one group. This computes a set oftime windows, each having an later edge at a valid aligned end time andeach having the same fixed width. A row is given an end time that isthe later edge of each window it falls within and the row is groupedwith any other rows having the same time-series identifier and new endtime. When the windows overlap, a row may be given more than one newend time and thus may be included in more than one group.

It is possible to combine spatial aggregation with one of the two forms oftemporal aggregation in one table operation.

An important distinction between sliding and non-sliding temporalaggregation is that some aggregators (e.g.sum) will producevalues withDelta time-series kind for non-sliding temporal aggregationbutGauge kind for sliding temporal aggregation. The reason for this isthe time extents for two points in aDelta time series cannot overlap,so the overlapping input windows of sliding temporal aggregation cannot berepresented in the time columns ofDelta time series output rows.

When a new time-series identifier is computed for a row, the new time seriesidentifier is computed by amap argument. The value columns for theoutput row are computed by amap argument with anaggregating expression computing each value column.

group_by   Aggregates rows by mapped time-series identifier and time window.

Signature:  Table  | group_by  tsid: RowToTSID,  aggregator: [ RowSetToVal ]
         Table  | group_by  tsid: RowToTSID,  window: lit-WindowDuration,  aggregator: [ RowSetToVal ]
         Table  | group_by  window: lit-WindowDuration,  aggregator: [ RowSetToVal ]

Thegroup_by table operation groups rows together by mapping the timeseries-identifier columns, time columns, or both:

• If thetsid argument is given and thewindow argumentis not,group_by computes the time-series identifier produced by thetsid argument for each row in the input table and groups together allrows with the same produced time-series identifier and end time.

  In this casegroup_by requires an aligned table as input so thatdifferent time series have points with the same end time.If the input table is not aligned, then analign table operationwill automatically be inserted to provide alignment.

• If thewindow argument is given and thetsid argumentis not, a group of rows is produced for each time-series identifier andevery aligned period output point. The rows in one group are all therows with the given time-series identifier whose end time falls in awindow between the output time and the time that iswindow durationearlier.

  If thewindow argument has aslidingfunction call (e.g.sliding(1h)), then the window may be differentthan the alignment period. Otherwise, theDuration argument must bethe same as the alignment period. The expressionwindow() represents a duration that is the same as thealignment period. If a non-slidingDuration is given explicitly, itforces the period to be the same if no period was given explicitly.

• If both thetsid andwindow arguments are given,a new mapped time-series identifier is computed for each row and a groupis created for all the rows with the same mapped time-series identifierwhose end time falls in a window between the output time and the timethat iswindow duration earlier.

An output row is produced for each group with the common time seriesidentifier of the rows in the group and a timestamp that is the output pointtime of the group (window was given) or the common end time of therows in the group (window was not given). The value columns inthe group are produced by theaggregation argument. Each aggregatingexpression is applied to the rows in the set and the result is the outputrow value column.

Some aggregating expressions (e.g.sum) will produce outputvalue columns withDelta orGauge time-series kind, depending on thekind of aggregation being done. This depends on whether or not sliding ornon-sliding temporal aggregation is being done. For this purpose,aggregation is treated as temporal aggregation if it combines both temporaland spatial aggregation.

Agroup_by table operation always produces aligned output tables. If nowindow argument is given, then the input table must be aligned andthe output table will have the same alignment. If thewindowargument is given, then an output point is only produced at an alignmenttime point and the output table is aligned.

Note that if thetsid argument includes value or time columns inits expressions, it is possible that time series in the input table will befractured into multiple time series in the output table. This is becauseeach point or row in a time series can have different value or time columnsfrom any other point in the time series and if that value is copied to atime-series identifier column, then the point will be in a different timeseries.

union_group_by   Aggregates rows from multiple tables.

Signature:  Table++  | union_group_by  tsid: RowToTSID,  aggregator: [ RowSetToVal ]
         Table++  | union_group_by  tsid: RowToTSID,  window: lit-WindowDuration,  aggregator: [ RowSetToVal ]
         Table++  | union_group_by  window: lit-WindowDuration,  aggregator: [ RowSetToVal ]

Theunion_group_by function aggregates input rows exactly like thegroup_by function except that it takes its input rowsfrom multiple input tables.

All the input tables input to aunion_group_by must have the same columns(same name, same type, and, for value columns, same time-series kind). Ifaligned input tables are required by the arguments to 'union_group_by' (nowindow argument given), then all the input tables must be alignedwith the same period.

unaligned_group_by   Aggregates rows by mapped time-series identifier without alignment.

Signature:  Table  | unaligned_group_by  tsid: TSIDSel,  aggregator: [ RowSetToVal ]

Theunaligned_group_by table operation does the same thing as thegroup_by table operation, but does not require its input table to bealigned.

This computes the time-series identifier produced by thetsid mapargument for each row in the input table and groups together all rows withthe same resulting time-series identifier and end time. All the rows in thegroup have the same end time and should have the same start time. If anytwo rows in a group have different start time, issue a dynamic error andarbitrarily choose one of the rows and remove it from the group.

Produces an output row for each group of the above group of rows. Theoutput row has the time-series identifier produced bytsid map argumentand the same end time and (if present) start time as the input rows in thegroup. It has value columns produced by theaggregation map argumentapplied to all the rows in the group.

Theunaligned_group_by table operation does not require its input table tobe aligned, which may mean that it is unlikely for there to be multiple rowsin a group to aggregate. It does require that the rows collected into oneoutput time series (all having the same time-series identifier) do not haveend times whose density gives more than one row per second.

Union and Join

join   Natural join of multiple tables.

Signature:  Table++  | join

Thejoin table operation takes two or more input tables and combines therows in these table into rows in a single output table by doing a naturalinner join on the time-series identifier and end time columns of the inputtables.

Besides being aligned, the input tables must all be aligned with the sameperiod and must all be ofDelta orGauge time-series kind. If an inputtable is not aligned, then analign table operation will automatically beinserted to provide alignment.

The output table will have the following elements:

• One time-series identifier column for every unique time-series identifiercolumn in any of the input tables. Each column will have the same type asthe corresponding column in the input tables. If two tables havetime-series identifier columns with the same name but different types,that is an error.

• An end time column. If any of the input tables isDelta time serieskind, the output table will also beDelta time-series kind and have astart time column.

• A value column for each input table value columns. The order is the orderof the input tables in thegrouped_table_op thatproduced them. It is an error if two different input tables have valuecolumns with the same name.

The join considers every tuple consisting of one row from each input table.For each such tuple that meets the following conditions, an output row iscreated:

• For each time-series identifier column name that appears in any of theinput tables that column has the same value for each row in the tuple thathas that column.

• Every row in the tuple has the same end time.

Each such output row will have the following column values:

• Each time-series column will have the value for that column as eachrow in the tuple that has that column.

• Each time column will have the same value as the rows in the input tuple.

• Each value column will have the same value as the row in the tuple thatvalue column came from.

outer_join   Outer natural join of two tables.

Signature:  Table++  | outer_join  left_default_value: [ DefaultColumns ],  right_default_value: [ DefaultColumns ]

Theouter_join table operation takes two input tables and combines therows in these table into rows in a single output table by doing a naturalouter join on the time-series identifier and end time columns of the inputtables.

One or both of theleft_default_value andright_default_value argumentsmust be given. Each corresponds to one input table (the first, "left",table or the second "right" table) and, when given for a table, that tablewill have rows created if it does not have some row that matches a row inthe other table. Each argument specifies the value columns of the createdrow. If a default argument is given for a table, then the time seriesidentifier columns in that table must be a subset of the time series ofthose of the other table and it can only haveDelta time-series kind ifthe other table hasDelta time-series kind.

Besides being aligned, the input tables must all be aligned with the sameperiod and must all be ofDelta orGauge time-series kind. If an inputtable is not aligned, then analign table operation will automatically beinserted to provide alignment.

As withjoin the output table will have the following elements:

• One time-series identifier column for every unique time-series identifiercolumn in any of the input tables. Each column will have the same type asthe corresponding column in the input tables. If two tables havetime-series identifier columns with the same name but different types,that is an error.

• An end time column. If any of the input tables isDelta time serieskind, the output table will also beDelta time-series kind and have astart time column.

• A value column for each input table value columns. The order is the orderof the input tables in thegrouped_table_op thatproduced them. It is an error if two different input tables have valuecolumns with the same name.

The join considers every pair consisting of one row from each input table.For each such pair that meets the following conditions, an output row iscreated:

• For each time-series identifier column name that appears in either of theinput tables that column has the same value for each row in the pair thathas that column.

• Each row in the pair has the same end time.

Each such output row will have the following column values:

• Each time-series column will have the value for that column as eachrow in the pair that has that column.

• Each time column will have the same value as the rows in the input pair.

• Each value column will have the same value as the row in the pair thatvalue column came from.

In addition to the pairs above, if a row in one table does cannot form apair with any row in the other table and the other table has itscorresponding default columns argument given, then a pair is created withthe row that exists from one table table and a default row for the othertable. The default row is constructed as follows:

• Each of its time-series identifier columns and time columns has the samevalue as the corresponding column in the first table row.

• The default row's value columns are constructed by the correspondingdefault column argument. If the table has a single value column,that default column argument can be a single literal expression. Ifthe table has multiple value columns, the default column argument must bea map expression with one value for each value column, in the same orderas the value columns in the input table and without alabel: given.

union   Union of multiple tables.

Signature:  Table++  | union

Theunion table operation takes two or more input tables and produces asingle output table containing rows from all the input tables.

The input tables must have the same columns (same name, same type, and, forvalue columns, same time-series kind). The produced output table will havethe same columns as the input tables.

If any of the input tables are aligned, the output ofunion will bealigned. In this case any input table that is not aligned will have analign table operation automatically be inserted to provide alignment. Thealignment period of all the input tables must be the same and that is thealignment period of the output.

In none of the input tables to theunion operation are aligned, the outputof theunion operation will not be aligned.

It is a dynamic error if streams from two or more different tables have thesame time-series identifier. In this case, one of the streams with aduplicate time-series identifier is chosen arbitrarily to be included in theoutput and the remainder are dropped.

Time Horizon and Period

The period to use when aligning the time series in the table is set bytheevery command.

The query will produce all its results as points whose end time falls withinaquery window. The duration of the query window is set by thewithintable operation, which can specify any of a starting time, ending time, orduration.

every   Specifies the period for aligned table output.

Signature:  Table  | every  period: lit-Duration

Theevery table operation requires an input table that isaligned with aninput period given by theperiod argument. This is handled in one ofthe following ways:

• If the input table is aligned but does not have a specific requiredperiod, the query that is input to theevery table operation isadjusted to produce output with the alignment period given by theperiod argument. For examplefetch | align rate(1h) | every 10mwill set the output period of therate aligner to 10minutes so that points having the average rate over the previous 1hwindow are output every 10 minutes. For a query likefetch | group_by | every 10m, where the group_by causes an implicitalign table operation to be inserted, theevery 10m applies to thatimplicitalign table operation.

• It is an error if the input table is aligned with a specific period andthat period is different from the one specified by theperiodargument. For examplefetch | align delta(10m) | every 1h is an errorbecause the input to theevery table operation will have a fixedalignment period of 10 minutes according to the rules of thedelta aligner.

• If the input table is not aligned, then analign operation isinserted with an appropriatealigner function forthe input table. Theperiod argument to theevery functionspecifies the alignment period for the aligner. For examplefetch | every 10m will be rewritten tofetch | align | every 10mwhere thealign will use a suitable aligner forthe input table and produce output points every 10 minutes.

within   Specifies the time range of the query output.

Signature:  Table  | within  first: lit-DateOrDuration,  last: [ lit-DateOrDuration ]

Thewithin table operation specifies the query output window. The end time of every point output by the query containing thewithintable operation will fall within this range. This operation should beappended to the end of the query.

The query output window is specified by giving one or two of three values:the starting time of the window, the ending time of the window, and theduration of the window as thefirst andlast argument.

If either thefirst orlast argument is a positiveDuration, thenthat sets the width of the window. At most one of the arguments can bea positiveDuration.

If thefirst argument is given by aDate, then that specifies thestarting time of the query window. If thesecond argument is given by aDate, that specifies the ending time of the query window. If bothfirst andsecond are a date, thesecond argument must come after thefirst in time. For eitherfirst orsecond the valuecan be given as aDate literal or with a negativeDurationliteral. In the later case, the time is the specified amount of timeearlier than the time the query was issued (now).

If only one argument is given, thesecond argument (end time) defaults tothe time the query was issued (now). In this case, if thefirst argumentis given by aDate value, it must be earlier than the time the query isissued.

For example:

| within 1h                   # one hour ending when the query was given| within d'2020/08/19 23:20'  # from the date to when the query was given| within 1d, d'2020/02/21 10:15'    # one day, ending at the given date| within -2d, 1d                    # one day, starting 2 days ago| within 1, -2d                     # one day, ending 2 days ago| within d'2020/02/21', d'2020/08/19'  # the interval between the two dates

graph_period   Specifies the preferred output period for drawing time series graphs.

Signature:  Table  | graph_period  period: lit-Duration

Thegraph_period table operation transforms its input table to make itsuitable for presentation as a graph. Itsperiod argument indicatesthe period between points suitable for the graph.

This operation is automatically inserted in queries that are given toMetrics Explorer if the user does not explicitly add one to the query. Ineither event, Metrics Explorer sets the value of theperiod argument tobe appropriate for the actual time window of the chart. Explicitly givingaddinggraph_period as part of a query only makes sense if the query isbeing given to the API.

Thegraph_period operation compares itsperiod argument with theperiod of the input table and does one of the following:

• If the period of the input table is less than half theperiodargument, then thegraph_period operation acts as a temporal reducerwhose window and output period are given by theperiod argument.Each value column in the input table is aggregated according to itstype.

  • For a value column of numeric type, three columns are placed in theoutput table, each produced by aggregating the input column with themin,mean, andmax aggregators. The output column names arethe input column name with, respectively,.min,.mean, and.max appended.

  • For a value column of typeBool, three columns are placed in theoutput table, each produced by aggregating the input column with themin,mean, andmax aggregators. The output column names arethe input column name with, respectively,.all_true,.mean, and.any_true append.

  • For a column of typeDistribution, a single column with the samename is created usingdistribution aggregation to combine thepopulations of all the distribution input values that fall in eachgraph period window.

• If the input table period is more than twice theperiod argument,then for each point in the input table, copies are made for the timepoints required by the output period.

• If the input table period is less than twice theperiod argument andmore than half theperiod argument, the input table is just copiedto the output.

Note that if the input table has more than one value column or has aString value column, its behavior is undefined. Metrics Explorer mightonly display a single column or give an error if there is no displayablecolumn.

window   Specifies the window for alignment operations.

Signature:  Table  | window  window: lit-Duration

Thewindow table operation requires an input table that isaligned by analigner function whose windowDuration argument is the same as thewindow argument given onthiswindow table operation. This is handled in one of the following ways:

• If the input table is not aligned, then analignoperation is inserted with an appropriatealigner function for the input table. TheDurationargument to the aligner function is given by thiswindow tableoperation'sDuration argument.

• If the table is aligned but the table operation that aligned it doesnot have a specific alignment window, thewindow argument from thiswindow table operation is used as the aligner window argument.

• It is an error if the input table is aligned and the table operationthat aligned specifies a windowDuration that is different from theDuration argument of thiswindow table operation.

Alerting

Alerting operations are used to define alert policies. Use these operationsonly to install alerts, not as part of a query.

Abstractly, these operations provide ways to create queries that result in atable with two value columns: a boolean indicating whether or not the alertshould be in a firing state and a value of the same type as the input givingthe most recent value of the input.

condition   Add a boolean condition column to the input table.

Signature:  Table  | condition  predicate: Bool

Thecondition table operation adds a boolean value column to eachinput table row to create its output table. The value of this column isthe value produced by thepredicate argument applied to the row.

This can be used to create analerting query. The outputtable has a a boolean column indicating that the alert condition issatisfied. The alerting facility will use this to determine if and when analert should fire or stop firing.

Thecondition operation requires its input table to be aligned and to begenerated by a query with an explicit alignment window. This is suppliedby a window argument to an align operation (for example,| align delta(10m)), a temporalgroup_by with a sliding window(for example,| group_by sliding(10m), sum(val())), or by awindowtable operation. Awindow table operation sets the window for a prioraligning table operation.

Examples:

  fetch gce_instance :: compute.googleapis.com/instance/cpu/usage_time  | rate (5m)  | condition lt(val(), 0.5's{CPU}/min')

This query uses therate aligner to compute a trailing 5-minute average,and the resulting units ares{CPU}/s. The condition then specifies thelimit in terms of the seconds of CPU usage per minute. The result of thecondition clause is a table with two value columns. The first column is aBool column that will be true if the input tableusage_time valuecolumn is less than.5. The second column is a copy of theusage_timevalue column from the input.

  fetch gce_instance :: compute.googleapis.com/instance/cpu/usage_time  | delta 1m  | group_by 5m, mean(val())  | condition lt(val(), 0.5 's{CPU}')

This query uses thedelta aligner to ensure that the period for thevalues is 1 minute. Thegroup_by clause computes the average of thevalues over a 5-minute period. This exampleuses a non-slidingdelta clause, which isn't a problem because it'sfollowed by a sliding windowgroup_by clause.

absent_for   Create a condition for the absence of input.

Signature:  Table  | absent_for  duration: lit-Duration

Theabsent_for table operation generates a table with two value columns,active andsignal. Theactive column is true when there is datamissing from the table input and false otherwise. This is useful forcreating a condition query to be used to alert on the absence of inputs.

For each input time series,absent_for creates an aligned output timeseries with the same time-series identifier as the input. The alignmentperiod is either given by a followingevery or is thedefault period.

Theduration argument gives a time limit. Theactive column for anoutput point will be false if there is a point in the input time series thatis within this time limit earlier than the time of the output point. Ifthere is no such input point, theactive column will be true, indicatingan absence of input within the time limit.

If the input table has value columns, thesignal column will contain thevalue of first value column of the most recent input point(within the limit or not) in the input time series. If the input table hasno value columns, thesignal column in the output point will be an integergiving the number of minutes since the last input point.

For each output point time, theabsent_for table operation will look back24 hours before that time for an input point. If there is no input point inthe prior 24 hours no point will be output for that time.

Examples:

  fetch  gce_instance :: compute.googleapis.com/instance/cpu/usage_time  | absent_for 8h

For eachusage_time time series from a virtual machine (gce_instance)theabsent_for will generate an aligned time series whose output pointswill have anactive column that is true if there is an input point withinthe last 24 hours but no points within the last 8 hours (8h). This is asuitable alerting query.

  fetch  gce_instance :: compute.googleapis.com/instance/cpu/usage_time  | value [] | absent_for 8h

This is similar to the previous example, but the| value [] removes thevalue columns from the input to theabsent_for operation, so thesignalcolumn is set to the time (in minutes) since the last input point.

Miscellaneous

ident   Identity table operation: no change to the input table.

Signature:  Table  | ident

Theident table operation produces an input table, unchanged.

Example:

fetchgce_instance::compute.googleapis.com/instance/cpu/usage_time|{ident;group_by[zone]}|join|value[zone_fraction: val(0) / val(1)]

For each row in the given table, compute the ratio of its value to the totalof that value over all instances in the zone it is in.

ratio   Computes the ratio of value columns of two aligned input tables.

Signature:  Table++  | ratio

Theratio table operation takes two aligned input tables, the numeratortable input and the denominator table input, respectively. Both table inputsshould have exactly one value column of a numeric type.

The time-series identifier columns of the denominator table must be a subsetof the time-series identifier columns of the numerator table. If bothtables have the same time-series identifier columns (name and type) then adefault value of zero will be used for the numerator when calculatingratios. If the numerator has more time-series identifier columns than thedenominator, then an output point will only be produced when both numeratorand denominator have a value.

filter_ratio   Computes the ratio of two filtered sums of the input value column.

Signature:  Table  | filter_ratio  numerator_predicate: Bool,  denominator_predicate: [ Bool ]

Thefilter_ratio table operation takes one input table that has exactlyone value column of a numeric type. If the input table is not aligned, thenanalign table operation will automatically be inserted to providealignment.

Thefilter_ratio operation aggregates all input rows at a given timestamp,computes a numerator and denominator sum, and produces a time series withthe ratio of these sums at each timestamp. Thenumerator_predicateargumentcontrols what goes into the numerator sum and thedenominator_predicatecontrols what goes into the denominator sum. Thedenominator_predicateis optional and defaults totrue if not given.

Thenumerator_predicate anddenominator_predicate arguments areevaluated for each row and if true the value column for that row isincluded in the numerator (numerator_predicate) or denominator(denominator_predicate) sum.

filter_ratio_by   Computes a grouped ratio of two filtered sums of the input value column.

Signature:  Table  | filter_ratio_by  tsid: RowToTSID,  numerator_predicate: Bool,  denominator_predicate: [ Bool ]

Thefilter_ratio_by table operation takes one input table that has exactlyone value column of a numeric type. If the input table is not aligned, thenanalign table operation will automatically be inserted to providealignment.

Thefilter_ratio_by operation groups rows together that have the sametime-series identifier computed by thetsid argument. For each groupit computes a numerator and denominator sum, and produces a time series withthe ratio of these sums at each timestamp. Thenumerator_predicateargumentcontrols what goes into the numerator sum and thedenominator_predicateargumentcontrols what goes into the denominator sum. The second argument isoptional and defaults totrue if not given.

Thenumerator_predicate anddenominator_predicate arguments areevaluated for each row and if true the valuecolumn for that row is included in the numerator (numerator_predicate) ordenominator (denominator_predicate) sum.

One times series is computed for each group, with the time-series identifiercomputed by thetsid argument.

Functions

This section describes each of the functions that can be used in expressions(expr) in the Monitoring Query Language.

• Input Row Columns
  • val   A value column's value in the input point (row).
  • end   The ending time of the input point (row).
  • start   The starting time of the input point (row).
  • older   A value from the next-earlier point (row) in a time series.
  • adjacent_delta   The change in value between an input point and next-earlier point.
  • adjacent_rate   The rate of change between the input and next-earlier points (rows).
  • hash_tsid   Return a hash of the time series identifier columns.
• Logical
  • not   The logical negation of a boolean value.
  • and   The logical and of two boolean values.
  • or   The logical or of two boolean values.
  • true   The boolean value true.
  • false   The boolean value false.
  • has   True if a set argument contains a particular value.
  • has_value   True if an argument expression computes a value.
  • if   A value conditionally chosen from two values.
  • or_else   A value or, if it is not a value, another value.
• Comparison
  • eq   Equal.
  • ne   Not equal.
  • ge   Greater than or equal.
  • gt   Greater than.
  • le   Less than or equal.
  • lt   Less than.
• Arithmetic
  • add   The sum of two numbers.
  • sub   The difference of two numbers.
  • mul   The product of two numbers.
  • div   The ratio of two numbers.
  • int_div   The quotient from the division of two integers.
  • abs   Absolute value.
  • neg   The negative of a number.
  • pos   Identity for numeric inputs.
  • rem   The remainder from the division of two integers.
• Math
  • sqrt   Square root.
  • log   Natural logarithm.
  • exp   e raised to a power.
  • power   One number to the power of another.
  • int_round   Nearest integer.
  • int_floor   Lower bound integer.
  • int_ceil   Upper bound integer.
• String
  • concatenate   String concatenation.
  • string_to_double   ConvertString toDouble.
  • string_to_int64   ConvertString toInt.
  • ascii_to_lower   Change ASCII upper case letter characters to lower case.
  • ascii_to_upper   Change ASCII lower case letter characters to upper case.
  • format   FormatInt64,Double, orString as aString.
  • string_to_timestamp   ConvertString toDate using date format and optional timezone.
  • timestamp_to_string   ConvertTimestamp toString using date format and optional timezone.
  • utf8_normalize   Unicode string suitable for case-folding comparison.
• Regular Expressions
  • re_full_match   True if a regular expression matches the whole of a string value.
  • re_partial_match   True if a regular expression matches some part of string value.
  • re_extract   Extract values matched by a regular expression in another string.
  • re_replace   Replace the first match of a regular expression in another string.
  • re_global_replace   Replace all matches of a regular expression in another string.
• Aggregation
  • sum   The sum of a group of numeric values.
  • distribution   A distribution from a group of numeric or distribution values.
  • count   The count of the number of values in a group of values.
  • row_count   The number of input rows encountered.
  • count_true   The number of true values in a group of boolean values.
  • min   The minimum of a group of numeric values.
  • max   The maximum of a group of numeric values.
  • diameter   The maximum minus the minimum of a group of numeric values.
  • mean   The mean of a group of numeric values.
  • stddev   The standard deviation of a group of values.
  • variance   The variance of a group of numeric values.
  • covariance   The covariance of a group of pairs of values.
  • median   The median of a group of numeric or distribution values.
  • percentile   A percentile of a group of numeric or distribution values.
  • fraction_less_than   The fraction of a group of values less than a fixed value.
  • fraction_true   The fraction of a group of boolean values that are true.
  • any_true   The disjunction of a group of boolean values.
  • all_true   The conjunction of a group of boolean values.
  • pick_any   The value of any element of a group of values (chosen arbitrarily).
  • singleton   The value of the element of a group of values with only one element.
  • unique   The common value of a group of values (which must all be the same).
  • aggregate   Default aggregate value from a group of values of any type.
  • weighted_distribution   A distribution from a group of weighted values.
• Aligning
  • rate   Compute a rate of change at aligned points in time.
  • delta   Compute the change in value at aligned points in time.
  • any_true_aligner   Align aBool time series by finding any true value in a window.
  • count_true_aligner   Align aBool time series by counting the true values in a window.
  • delta_gauge   Compute the change in value at aligned points in time as aGauge time series.
  • fraction_true_aligner   Align aBool time series with the fraction of true values in a window.
  • int_mean_aligner   Align by finding the mean ofInt values in a window.
  • interpolate   Compute interpolated values at aligned points in time.
  • mean_aligner   Align by finding the mean of values in a window.
  • next_older   Aligned points in time by moving from an earlier to later time.
  • next_younger   Aligned points in time by moving from a later to earlier time.
• Manipulating Units
  • scale   Scale a value to a different unit of measure.
  • cast_units   Set the unit of measure of a value.
• Periodic Window
  • window   Indicates a window that is the same as the alignment period.
  • sliding   Indicates a window that is sliding (overlapping) rather than disjoint.
  • requested_period   The external requested output alignment period.
• Distribution
  • count_from   The number of values in a distribution value.
  • sum_from   The sum of the values in a distribution value.
  • mean_from   The mean of the values in a distribution value.
  • stddev_from   The standard deviation of the values in a distribution value.
  • variance_from   The variance of the values in a distribution value.
  • median_from   The median of the values in a distribution value.
  • percentile_from   A percentile of the values in a distribution value.
  • fraction_less_than_from   The fraction of values in a distribution that are less than a fixed value.
  • bounded_percentile_from   A percentile of the values within a bound in a distribution value.
  • rebucket   Distribution value converted to a new bucket specification.
• Bucket Specifier
  • powers_of   A bucket specification with exponentially increasing bucket boundaries.
  • fixed_width   A bucket specification with equal-sized buckets.
  • custom   A bucket specification from a list of bucket boundaries.
  • num_buckets   Sets the number of buckets in a bucket specification.
  • bounds   Sets the lower bound of the first bucket and upper bound of the last.
  • lower   Sets the lower bound of the first bucket in a bucket specification.
• Miscellaneous
  • cast_double   ConvertInt value toDouble.
  • cast_gauge   Cast aCumulative orDelta time series value toGauge.
  • within   Specifies the window of the sort value calculation.

Input Row Columns

The expressions in a query operate on the columns of an input row. Acolumn is normally accessed by giving its name.The functions in this section provide alternative ways to access columns.

The time columns do not have column names and are accessed by thestartandend functions.

The value columns can be accessed by name or by position using thevalfunction.

Theolder function gives access to a column in the next-earlier row in atime series.

val   A value column's value in the input point (row).

Signature:  ImplicitRowInput  val([ lit-Int ])   →  InputType    (implicit row input)

Theval function provides an alternative to using the column name whenaccessing thevalue columns of an input row. ItsIntargument (default value 0) indexes the ordered set of value columns(starting with 0 for the first value column) and returns the value ofthe indexed value column. This is the same value that results from usingthe value column name.

It is a static error if theval function indicates an index that isnegative or is the same or larger than or equal to the number of valuecolumns.

end   The ending time of the input point (row).

Signature:  ImplicitRowInput  end()   →  Date.Gauge    (implicit row input)

Theend function returns the Date value in the end time column of thecurrent input row.

start   The starting time of the input point (row).

Signature:  ImplicitRowInput  start()   →  Date.Gauge    (implicit row input)

Thestart function returns the Date value in the start time column of thecurrent input row. If the row does not have a start time (because itcontains onlyGauge data), start time returnsno-value.

older   A value from the next-earlier point (row) in a time series.

Signature:  older(ColumnValue.CumulativeOK)   →  FirstArgType.FirstArgKind
         older(Date)   →  Date.FirstArgKind

The argument toolder must be a column name or a function that designatesa column value (val,end,start). The value returned is the value ofthat column in the row that is next-earlier to the input row in thesame time series. If there is no such earlier row in the same time series,older returnsno-value.

The column referenced may be a value, time, or time series identifiercolumn. If it is a time series identifier columnolder will returnthe same value as the argument expression would even if there is noearlier row in the same time series.

adjacent_delta   The change in value between an input point and next-earlier point.

Signature:  ImplicitRowInput  adjacent_delta()   →  InputType    (implicit row input)

Theadjacent_delta function operates on tables with a single numeric(Int orDouble) or Distribution value column.

If applied to aGauge time series,adjacent_delta returnsthe difference between the value of the value column in current input rowand the value column in the next-earlier row in the same time series, ifany. If there is no next-earlier row in the same time series,adjacent_delta returnsno-value. The result hasGaugetime series kind.

If applied to aDelta time series,adjacent_delta returns the value ofthe value column, which remains aDelta time series kind. Each outputpoint has the same value, start time, and end time as the input point it wasgenerated from.

AlthoughCumulative time series are rarely used in queries, if applied toaCumulative time series,adjacent_delta returns one of two values:

• If the input point's start time is before the end time of the nextearlier point,adjacent_delta returns the value of the input pointminus the value of the next-earlier point.

• If the input point's start time is later than the end time of thenext-earlier point,adjacent_delta returns the input points value(effective subtracting a value of 0 at the start time).

The resulting time series has aDelta time series kind and each point astart time that is its original start time or the end time of the nextearlier input point, whichever is later.

adjacent_rate   The rate of change between the input and next-earlier points (rows).

Signature:  ImplicitRowInput  adjacent_rate()   →  Double.Gauge    (implicit row input)

Theadjacent_rate function operates on tables with a single numeric(Int orDouble) or Distribution value column.

If applied to aGauge orCumulative time series,adjacent_rate returnsthe rate of change between the value of the value column in current inputrow and the value column in the next-earlier row in the same time series, ifany. This is the difference in values divided by the difference in end timeof the two rows. If there is no next-earlier row in the same time series,adjacent_rate returnno-value. The result hasGauge timeseries kind.

If applied to aDelta time series,adjacent_rate returns the valuecolumn of the current input row divided by the difference between the starttime and the end time of that row.

hash_tsid   Return a hash of the time series identifier columns.

Signature:  ImplicitRowInput  hash_tsid([ lit-Int ])   →  Int    (implicit row input)

Thehash_tsid function returns a hash of the values in the fields ofthe time series identifier of the current input row. If it is given anargument, that is used as a seed to the hash.

Logical

not   The logical negation of a boolean value.

Signature:  not(Bool)   →  Bool

Thenot function takes a boolean value and returns true if that argumentis false and returns false if that argument is true. If the inputargument isno-value, that is the result.

and   The logical and of two boolean values.

Signature:  and(Bool,  Bool)   →  Bool

Theand function returns true if both of its inputs are true, and falseotherwise. If either input isno-value,and always returns no-value.

or   The logical or of two boolean values.

Signature:  or(Bool,  Bool)   →  Bool

Theor function returns true if either of its inputs are true, and falseotherwise. If either input isno-value,or always returns no-value.

true   The boolean value true.

Signature:  ImplicitRowInput  true()   →  lit-Bool    (implicit row input)

This function returns the literalBool valuetrue.

false   The boolean value false.

Signature:  ImplicitRowInput  false()   →  lit-Bool    (implicit row input)

This function returns the literalBool valuefalse.

has   True if a set argument contains a particular value.

Signature:  has(Set,  lit-ColumnValue)   →  Bool

Thehas function returns true if its first argument set has the secondargument as an element.

has_value   True if an argument expression computes a value.

Signature:  has_value(ColumnValue)   →  Bool

Thehas_value function returns true if its argument evaluates to a valueand returns false if it evaluates tono-value.

if   A value conditionally chosen from two values.

Signature:  if(Bool,  ColumnValue.Delta,  ColumnValue.Delta(same))   →  LastArgType.Delta
         if(Bool,  ColumnValue,  ColumnValue(same))   →  LastArgType

Theif function returns its second or third argument, depending on thevalue (true orfalse) of its first argument.

if evaluates its firstBool argument. If it isno-value,then no-value is the result. If the first argument is true, then thesecond argument is returned and if the first argument is false, thenthe third argument is returned.

Either the second or third argument may be no-value, but the result ofif will only be no-value if theBool argument is no-value or if theargument returned is no-value. The argument that is not selected may beno-value without the result being no-value.

If the second and third arguments ofif are numeric and either argumenthasunits, then both arguments must have units. If thearguments have units, they must either beequivalentor the rules givenhere must allow one of thearguments to be scaled before applyingif so the units are equivalent.It is an error if only one argument has units or if both arguments haveunits that cannot be made equivalent.

The result of theif has the unit of its second argument, possibly scaled.

or_else   A value or, if it is not a value, another value.

Signature:  or_else(ColumnValue,  ColumnValue(same))   →  LastArgType

Theor_else function returns the value of its first argument unless itisno-value, in which case the value of its second argument isreturned.

Theor_else function only returns no-value if both its arguments areno-value.

If the arguments ofor_else are numeric and either argument hasunits, then both arguments must have units. If thearguments have units, they must either beequivalentor the rules givenhere must allow one of thearguments to be scaled before applyingor_else so the units are equivalent.It is an error if only one argument has units or if both arguments haveunits that cannot be made equivalent.

The result of theor_else has the unit of the first argument, possibly scaled.

Comparison

The comparison operators compare two values of the same type or twonumeric (Int or *Double) values and return aBool value. Unlike mostfunctions, comparison operators never returnno-value. If an input isno-value, it is considered to be a specific value that is larger than anyother value.

eq   Equal.

Signature:  eq(Num,  Num)   →  Bool
         eq(Comparable,  Comparable(same))   →  Bool

This compares its firstComparable argument to the secondComparable argument and returnstrue if they are the same andfalse ifthey are not the same. If one argument isInt and the otherDouble,theInt argument is converted to aDouble value before comparing.

If either input isno-value, the comparison is done andaBool argument is returned,true if both values areno-value andfalse otherwise. (This treats no-value as equal to itself.)

For a comparison on numeric arguments, ifeither argument hasunits, then botharguments must have units and the units must beequivalent. The result, being typeBool will nothave units.If the arguments toeqhave non-equivalent units that have the samedimension,then one argument may have its unitscaledautomatically to make the units of both arguments beequivalent.

If the arguments ofeq are numeric and either argument hasunits, then both arguments must have units. If thearguments have units, they must either beequivalentor the rules givenhere must allow one of thearguments to be scaled before applyingeq so the units are equivalent.It is an error if only one argument has units or if both arguments haveunits that cannot be made equivalent.

The result of 'eq', being typeBool, will not have units.

A comparison between theresource.project_id column and a literal stringhas special treatment to deal with the difference between project numbersand project names, as described inMatching theresource.project_idcolumn.

ne   Not equal.

Signature:  ne(Num,  Num)   →  Bool
         ne(Comparable,  Comparable(same))   →  Bool

This compares its firstComparable argument to the secondComparable argument and returnsfalse if they are the same andtrue ifthey are not the same. If one argument isInt and the otherDouble,theInt argument is converted to aDouble value before comparing.

If either input isno-value, the comparison is done andaBool argument is returned,false if both values areno-value andfalse otherwise. (This treats no-value as equal to itself.)

If the arguments ofne are numeric and either argument hasunits, then both arguments must have units. If thearguments have units, they must either beequivalentor the rules givenhere must allow one of thearguments to be scaled before applyingne so the units are equivalent.It is an error if only one argument has units or if both arguments haveunits that cannot be made equivalent.

The result of 'ne', being typeBool, will not have units.

A comparison between theresource.project_id column and a literal stringhas special treatment to deal with the difference between project numbersand project names, as described inMatching theresource.project_idcolumn.

ge   Greater than or equal.

Signature:  ge(Num,  Num)   →  Bool
         ge(Comparable,  Comparable(same))   →  Bool

This compares its firstComparable argument to the secondComparableargument and returnstrue if the first is greater than or equal tothe secondandfalse otherwise. If one argument isInt and the otherDouble, theInt argument is converted to aDouble value before comparing.

If either input isno-value, the comparison is done andaBool argument is returned,true if the first value isno-value andfalse otherwise. (This treats no-value as greater than any other value.)

If the arguments ofge are numeric, then, if either argument hasunits, both arguments must have units. If thearguments have units, then the units must beequivalent. If the units are not equivalent but havethe samedimension, then one of the argumentsmay beautomatically scaled to have the same units as the other as describedhere. It is an error if only one of the arguments hasunits or if the arguments have non-equivalent units and no scaling is done.

The result of 'ge', being typeBool, will not have units.

gt   Greater than.

Signature:  gt(Num,  Num)   →  Bool
         gt(Comparable,  Comparable(same))   →  Bool

This compares its firstComparable argument to the secondComparableargument and returnstrue if the first is greater than the secondandfalse otherwise. If one argument isInt and the otherDouble, theInt argument is converted to aDouble value before comparing.

If either input isno-value, the comparison is done andaBool argument is returned,false if the second value isno-value andtrue otherwise. (This treats no-value as greater than any other value.)

If the arguments ofgt are numeric and either argument hasunits, then both arguments must have units. If thearguments have units, they must either beequivalentor the rules givenhere must allow one of thearguments to be scaled before applyinggt so the units are equivalent.It is an error if only one argument has units or if both arguments haveunits that cannot be made equivalent.

The result of 'gt', being typeBool, will not have units.

le   Less than or equal.

Signature:  le(Num,  Num)   →  Bool
         le(Comparable,  Comparable(same))   →  Bool

This compares its firstComparable argument to the secondComparableargument and returnstrue if the first is less than or equal to the secondandfalse otherwise. If one argument isInt and the otherDouble, theInt argument is converted to aDouble value before comparing.

If either input isno-value, the comparison is done andaBool argument is returned,true if the second value isno-value andfalse otherwise. (This treats no-value as greater than any other value.)

If the arguments ofle are numeric and either argument hasunits, then both arguments must have units. If thearguments have units, they must either beequivalentor the rules givenhere must allow one of thearguments to be scaled before applyingle so the units are equivalent.It is an error if only one argument has units or if both arguments haveunits that cannot be made equivalent.

The result of 'le', being typeBool, will not have units.

lt   Less than.

Signature:  lt(Num,  Num)   →  Bool
         lt(Comparable,  Comparable(same))   →  Bool

This compares its firstComparable argument to the secondComparable argument and returnstrue if the first is less than thesecond andfalse otherwise. If one argument isInt and the otherDouble, theInt argument is converted to aDouble value beforecomparing.

If either input isno-value, the comparison is done andaBool argument is returned,false if the first value isno-value andtrue otherwise. (This treats no-value as greater than any other value.)

If the arguments oflt are numeric and either argument hasunits, then both arguments must have units. If thearguments have units, they must either beequivalentor the rules givenhere must allow one of thearguments to be scaled before applyinglt so the units are equivalent.It is an error if only one argument has units or if both arguments haveunits that cannot be made equivalent.

The result of 'lt', being typeBool, will not have units.

Arithmetic

Functions implementing the arithmetic operators.

add   The sum of two numbers.

Signature:  add(Num.Delta,  Num.Delta)   →  Num.Delta
         add(Num,  Num)   →  Num
         add(Duration,  Duration)   →  Duration
         add(Date,  Duration)   →  Date
         add(Duration,  Date)   →  Date

Theadd function on twoNum arguments returns the sum of its arguments,as aDouble value if either input is aDouble value and as anIntvalue otherwise. If both inputs areDelta time series kind, then theoutput isDelta time series kind. Otherwise the output isGauge timeseries kind.

Theadd function on twoDuration arguments returns the duration that istheir sum.

Theadd function on aDate andDuration argument returns the Date thatis theDuration later than theDate argument. If theDuration isnegative, the result will be earlier than the inputDate (goes back intime).

If the arguments ofadd are numeric and either argument hasunits, then both arguments must have units. If thearguments have units, they must either beequivalentor the rules givenhere must allow one of thearguments to be scaled before applyingadd so the units are equivalent.It is an error if only one argument has units or if both arguments haveunits that cannot be made equivalent.

The result of theadd has the unit of the first argument, possibly scaled.

sub   The difference of two numbers.

Signature:  sub(Num.Delta,  Num.Delta)   →  Num.Delta
         sub(Num,  Num)   →  Num
         sub(Duration,  Duration)   →  Duration
         sub(Date,  Duration)   →  Date
         sub(Date,  Date)   →  Duration

Thesub function on twoNum arguments returns the first argument minusthe second argument, as aDouble value if either input is aDouble valueand as anInt otherwise. If both inputs areDelta time series kind,then the output isDelta time series kind. Otherwise the output isGauge time series kind.

Thesub function twoDuration arguments returns the duration that istheir numeric difference.

Thesub function on aDate andDuration argument returns the Datethat is theDuration earlier than theDate argument. If theDurationargument is negative, the result is later than theDate argument.

If the arguments ofsub are numeric and either argument hasunits, then both arguments must have units. If thearguments have units, they must either beequivalentor the rules givenhere must allow one of thearguments to be scaled before applyingsub so the units are equivalent.It is an error if only one argument has units or if both arguments haveunits that cannot be made equivalent.

The result of thesub has the unit of the first argument, possibly scaled.

mul   The product of two numbers.

Signature:  mul(Num.Delta,  lit-Num)   →  Num.Delta
         mul(lit-Num,  Num.Delta)   →  Num.Delta
         mul(Num,  Num)   →  Num
         mul(Duration,  Num)   →  Duration
         mul(Num,  Duration)   →  Duration

Themul function on twoNum arguments returns the product of the twoarguments, as aDouble value if either input is aDouble value and as anInt value otherwise. If one inputs isDelta time series kind and theotherinput is a literal, then the output isDelta time series kind. Otherwisethe output isGauge time series kind.

Themul function on aNum andDuration is theDuration multiplied bytheNum as aDuration type.

If either numeric argument hasunits, then botharguments must have units and the units must beequivalent. The unit of the result, if the argumentshave units, will be the product of the units of the two arguments. The oneexception is multiplication by a literal: the literal may not have a unit ofmeasure given explicitly, so if the other argument has a unit of measure,the unit1 will be given to the literal, causing the result to have theunits of the other argument.

div   The ratio of two numbers.

Signature:  div(Num.Delta,  lit-Num)   →  Double.Delta
         div(Num,  Num)   →  Double
         div(Duration,  Num)   →  Duration
         div(Duration,  Duration)   →  Double
         div(Date,  Duration)   →  Double

Thediv function divides its firstNum argument by its secondNumargument, returning the ratio as aDouble value.

Thediv function does not produce a result if the secondargument is 0.

If both arguments are numeric (Int orDouble) the result is theDoublevalue that is the ratio of the two numbers.

If the first argument isDuration and the second argument is numeric, thenthe result is aDuration which is the nearestDuration to the ratio ofthat duration and numeric value. So60m / 3.0 is20s and100us / 33is3us.

If the second argument todiv is aDuration value, the result is aDouble value with unit "1" representing the dimensionless ratio betweenthe time span represented by the first argument and the time spanrepresented by the second argument. If the first argument is aDatevalue, the time span is the difference between the data specified by thevalue and the Unix epoch (d'1970/01/01-00:00:00+00:00').

To convert aDate orDuration to aDouble value with a time unit, usethescale function.

If both arguments todiv are numeric and either hasunits, then both arguments must have units. The unitof the result, if the arguments have units, will be the division of the unitof the first argument by the unit of the second. The one exception isdivision by a literal if the literal does not have a unit of measure givenexplicitly. In this case the unit1 will be given to the literal, causingthe result to have the units of the other argument.

int_div   The quotient from the division of two integers.

Signature:  int_div(Int,  Int)   →  Int
         int_div(Duration,  Int)   →  Duration
         int_div(Duration,  Duration)   →  Int
         int_div(Date,  Duration)   →  Int

Theint_div function divides its first argument by its secondargument, returning the quotient as anInt value. When an argument is aDate orDuration, the value is represented as an integer value that istheDate orDuration in units that represent the full internal precisionof such values. If the result is a Date or Duration, the numeric quotientis interpreted as a value with the same units.

In the case of aDate value being divided by aDuration value, theresult is theInt value that is the number of thatDuration periodssince the Unix epoch (d'1970/01/01-00:00:00+00:00'). Sod'2020/06/01-01:20:03' / 1s is the number of seconds sinced'1970/01/01-00:00:00+00:00' atd'2020/06/01-01:20:03'.

Theint_div function does not produce a result if the secondargument is 0.

If both arguments areInt the result is theInt value that is thequotient of the division.

If the first argument isDuration and the second argument isInt, thenthe result is aDuration which is the nearestDuration to the quotientof that duration and numeric value. So60m / 7 is8s and100us / 33is3us.

If the second argument todiv is aDuration value, the result is anInt value with unit "1" representing the dimensionless quotient of thedivision of the time span represented by the first argument and the timespan represented by the second argument. If the first argument is aDatevalue, the time span is the difference between the data specified by thevalue and the Unix epoch (d'1970/01/01-00:00:00+00:00').

To convert aDate orDuration to anInt value with a time unit, usethescale function and apply theint_round function to the result to convert from thefloating output ofscale to anInt value. For examplescale(3d, "1s").int_round() to convert 2 days to anInt number ofseconds.

If both arguments areInt values and either argument hasunits, then both arguments must have units. The unitof the result, if the arguments have units, will be the division of the unitof the first argument by the unit of the second. The one exception isdivision by a literal if the literal does not have a unit of measure givenexplicitly. In this case the unit1 will be given to the literal, causingthe result to have the units of the other argument.

abs   Absolute value.

Signature:  abs(Num)   →  Num

Theabs function takes a numeric (Int or *Double) input and returns avalue of the same type that has the same magnitude as the input and isnon-negative.

The result ofabs has the sameunit of measure.

neg   The negative of a number.

Signature:  neg(Num)   →  Num
         neg(Duration)   →  Duration

Theneg function returns the negative of its argument.

pos   Identity for numeric inputs.

Signature:  pos(Num)   →  Num
         pos(Duration)   →  Duration

Thepos function returns its one argument

rem   The remainder from the division of two integers.

Signature:  rem(Int,  Int)   →  Int
         rem(Duration,  Duration)   →  Duration

Therem function divides its first argument by its secondargument, returning the remainder.

Therem function does not produce a result if the secondNum argument is0.

If the two arguments are of typeInt, then the result is theIntremainder of the division with the same unit, if any, as the first argument.

If the two arguments are of typeDuration, then the result is theis theDuration that is the remainder of the division.

Math

Some mathematical functions.

sqrt   Square root.

Signature:  sqrt(Num)   →  Double

Thesqrt function returns the square root of theNum argument asaDouble value.

Thesqrt does not produce a result if theNum argument is less than 0.

The result ofsqrt does not have a unit of measure.

log   Natural logarithm.

Signature:  log(Num)   →  Double

Thelog function returns the natural logarithm of theNum argument asaDouble value.

Thelog does not produce a result if theNum argument is less than orequal to 0.

The result oflog does not have a unit of measure.

exp   e raised to a power.

Signature:  exp(Num)   →  Double

Theexp returns e (the base of natural logarithms)raised to the power of theNum argument as aDouble value.

Theexp functions returns the Double value infinity on overflow.

The result ofexp does not have a unit of measure.

power   One number to the power of another.

Signature:  power(Num,  Num)   →  Double

This returns the value of the firstNum argument, raised to the powerof the secondNum argument, represented as aDouble value. If eitherargument is anInt, it is converted to aDouble before the operation.

The result ofpower does not have a unit of measure.

int_round   Nearest integer.

Signature:  int_round(Double)   →  Int

Theint_round function takes aDouble value, rounds it to the nearestinteger value and returns it as anInt value. If the input is not a valueor the result cannot be represent as anInt value, the result isno-value.

The result ofint_round has the sameunit of measureas its input.

int_floor   Lower bound integer.

Signature:  int_floor(Double)   →  Int

Theint_floor function takes aDouble value, rounds it toward minusinfinity to the nearest integer value and returns it as anInt value. Ifthe input is not a value or the result cannot be represent as anIntvalue, the result isno-value.

The result ofint_floor has the sameunit of measureas its input.

int_ceil   Upper bound integer.

Signature:  int_ceil(Double)   →  Int

Theint_ceil function takes aDouble value, rounds it toward infinity tothe nearest integer value and returns it as anInt value. If the inputisno-valueor the result cannot be represent as anInt value,the result is no-value.

The result ofint_ceil does not have a unit of measure.

String

Functions processingString values.

concatenate   String concatenation.

Signature:  concatenate(String,  String)   →  String

Theconcatenate function returns the concatenation of its twoStringarguments.

string_to_double   ConvertString toDouble.

Signature:  string_to_double(String)   →  Double

Thestring_to_double function parses its inputString argument as afloating point number and returns the result as aDouble value. The inputstring may contain leading whitespace, may contain a leading '+' or '-'prefix, may have a '0X' or '0x' prefix to indicate a hexadecimal value, maycontain leading 0s at the beginning of the numerical value, and may havedecimal point followed by a valid number. Decimal numbers may be followed bya base 10 exponent, indicated by "E" or "e" and a decimal number;Hexadecimal numbers may be followed by a base 2 exponent, indicated by "P"or "p" followed by a hexadecimal number. Invalidly formatted strings,overflow, and underflow all result inno-value.

The result ofstring_to_double does not have a unit of measure.

string_to_int64   ConvertString toInt.

Signature:  string_to_int64(String,  [ lit-Int ])   →  Int

Thestring_to_int64 function takes two arguments: a requiredString andan optionalInt. The function parses theString argument as an integernumber, using the optionalInt argument as a base, and returns the resultas anInt. The default value of the optional base is 10. Base value 0indicates thatStrings with prefix '0x' or '0X' shall be parsed ashexadecimal (e.g. 0x10 = 16),Strings with prefix '0' shall be parsed asoctal (e.g. '010' = 8), andStrings with no prefix shall be parsed asdecimal (e.g. '10' = 10). If the string is not a valid integer value orcannot be represented as anInt value, the result isno-value.

The result ofstring_to_int64 does not have a unit of measure.

ascii_to_lower   Change ASCII upper case letter characters to lower case.

Signature:  ascii_to_lower(String)   →  String

Theascii_to_upper function takes aString argument and returns aString value that is the same except that each upper-case ASCII letter hasbeen converted to the corresponding lower-case ASCII letter. All othercharacters are left unchanged.

ascii_to_upper   Change ASCII lower case letter characters to upper case.

Signature:  ascii_to_upper(String)   →  String

Theascii_to_upper function takes aString argument and returns aString value that is the same except that each lower-case ASCII letter hasbeen converted to the corresponding upper-case ASCII letter. All othercharacters are left unchanged.

format   FormatInt64,Double, orString as aString.

Signature:  format(Num,  lit-String)   →  String
         format(String,  lit-String)   →  String

Theformat function takes two required arguments: anInt,Double orString, and aString. The function formats the first argument as a string,using the format specified in the secondString argument,and returns the result as aString.

string_to_timestamp   ConvertString toDate using date format and optional timezone.

Signature:  string_to_timestamp(String,  lit-String,  [ lit-String ])   →  Date

Thestring_to_timestamp function parses its inputString argument as atimestamp and returns the result as aDate value.

Second argument is a time_format, which describes the format of the inputstring. Use strftime()-like formatting.

Third argument is a time zone and it is optional. Must be a string of TZidentifiers from the IANA Time Zone Database. If no time zone specified,UTC will be used. If time zone information is specified in the inputtimestamp string, this parameter will not be used.

If the string is not a valid date according to a provided format, the resultisno-value.

timestamp_to_string   ConvertTimestamp toString using date format and optional timezone.

Signature:  timestamp_to_string(Num,  lit-String,  [ lit-String ])   →  String
         timestamp_to_string(Date,  lit-String,  [ lit-String ])   →  String

Thetimestamp_to_string function converts inputTimestamp to its stringrepresentation. Input can be anInteger,Double orDate. If input isInteger orDouble then units are required.

Second argument is a time_format, which describes the format of the outputstring. Use strftime()-like formatting.

Third argument is a time zone and it is optional. Must be a string of TZidentifiers from the IANA Time Zone Database. If no time zone specified,UTC will be used.

utf8_normalize   Unicode string suitable for case-folding comparison.

Signature:  utf8_normalize(String)   →  String

Theutf8_normalize function takes aString argument and returns anString value suitable for case-folding comparison of the input value underthe assumption the input is a valid utf8-encoded string.

Regular Expressions

Functions that do matching, extraction, and modification usingRE2regular expressions.

re_full_match   True if a regular expression matches the whole of a string value.

Signature:  re_full_match(String,  lit-String)   →  Bool

There_full_match function takes a string input and a literal stringregular expression and returnstrue if the whole of the input string ismatched by the regular expression. It returnsfalse otherwise, even ifthe input string argument isno-value.

A regular expression match on theresource.project_id column has specialtreatment to deal with the difference between project numbers and projectnames, as described inMatching theresource.project_idcolumn.

re_partial_match   True if a regular expression matches some part of string value.

Signature:  re_partial_match(String,  lit-String)   →  Bool

There_partial_match function takes a string input and a literal stringregular expression and returnstrue if any part of the input string ismatched by the regular expression. It returnsfalse otherwise, even ifthe string argument isno-value.

re_extract   Extract values matched by a regular expression in another string.

Signature:  re_extract(String,  [ lit-String ],  [ lit-String ])   →  String

There_extract function takes an inputString argument and two literalString arguments: a regular expression and a replacement string. Theresult is formed by matching the input string to the regular expression andthe substituting capture groups in the expression in the replacement string.The replacement string with the capture groups substituted is the result.

If the regular expression argument is not given, it defaults to "(.*)",thus including the whole first argument string in one capture group.

If the replacement string argument is not given, it defaults to R"\1", thusmaking the first replacement group be the output string.

If the input string isno-value, if the regular expression did not match, orthe substitution of capture groups did not work, no-value is returned.

re_replace   Replace the first match of a regular expression in another string.

Signature:  re_replace(String,  lit-String,  lit-String)   →  String

There_replace function takes an inputString argument and two literalString arguments: a regular expression and a replacement value. If theregular expression matches any part of the input string, the returned valueis formed by replacing the first such match in the input string with thereplacement string.

If the input string isno-valueor if there is nomatch, the input string is the returned value.

re_global_replace   Replace all matches of a regular expression in another string.

Signature:  re_global_replace(String,  lit-String,  lit-String)   →  String

There_global_replace function takes an inputString argument and twoliteralString arguments: a regular expression and a replacement value.The result is formed from the input string by replacing each disjoint matchof the regular expression (from left to right) with the replacement string.

If the input string isno-valueor if there is no match, the input string isthe returned value.

Aggregation

An aggregation function combines a set of input values into a finaloutput value. They are used when a number of input rows aregrouped together and aggregated into a single output row.

An aggregation function maintains an internal aggregation state. Theargument expression to the aggregation function is evaluated once foreach of the grouped input rows and the resulting value (if any) is passedto the aggregation function to be accumulated in its internal state.Once this has been done for all rows in the group, the aggregationfunction produces its output value to be used in creating value columnsin the single output row.

For example,mean(memory_usage) applied to a set of rows with amemory_usage column, evaluates the argument expression,memory_usage, for each row, and incorporates the resulting value (ifone is produced) in the internal state of themean aggregationfunction (which might be a sum of values and a count of values).Once all the rows have been processed, themean reducer producesa value from its internal state (the sum divided by the count).

Most aggregation functions that operate on numeric orDistributionvalues give theunit of measure of their input tothe output. The exceptions are:

• count androw_count whose output has unit1.

• variance whose output is the square of input.

• covariance whose output is the product of the units of the twoinputs.

• fraction_less_than andfraction_true give unit10^2.% to their output.

sum   The sum of a group of numeric values.

Signature:  sum(Num)   →  Num.Delta    (temporal only)
         sum(Distribution)   →  Double.Delta    (temporal only)
         sum(Num)   →  Num.Gauge    (sliding temporal only)
         sum(Distribution)   →  Double.Gauge    (sliding temporal only)
         sum(Num)   →  Num.FirstArgKind
         sum(Distribution)   →  Double.FirstArgKind

If the argument expression is numeric (Int or *Double), this returns thesum of the values that are passed to it.

If the argument expression is aDistribution value, this returns the sumof the population values in all theDistribution values that are passed toit.

If, for some input row, the argument expression does not evaluate to a valueor evaluates to a non-finiteDouble value, that input row does not affectthe sum.

For numeric (Int orDouble) input, the result is the same type (Int* orDouble) as the input expression. ForDistribution input values, theresult type isDouble.

The output hasDelta time series kind ifnon-sliding temporal aggregationsis being done or if only spatial aggregation is being done and the inputtime series kind is alsoDelta.

Theunit of measure attached to the result ofsumis the same as the unit of the input.

distribution   A distribution from a group of numeric or distribution values.

Signature:  distribution(Num,  lit-BucketSpecification)   →  Distribution.Delta    (temporal only)
         distribution(Num,  lit-BucketSpecification)   →  Distribution.Gauge
         distribution(Distribution)   →  Distribution.Delta    (temporal only)
         distribution(Distribution)   →  Distribution.Gauge    (sliding temporal only)
         distribution(Distribution)   →  Distribution.FirstArgKind

If the first argument is aNum value, the input values are collectedinto a distribution result whose bucket specification is given by thelit-Bucketer argument.

If the first argument is aDistribution value, the distributions aremerged into a distribution result that includes the population of all theinput distributions. The resulting distribution bucket specification isdetermined from the input distribution bucket specifications. If the bucketspecifications are all the same, then that bucket specification is used. Ifthere are different bucket specification, a new merged bucket specificationis used. This merged specification is typically no more accurate thanleast-accurate input bucket specification.

If, for some input row, the first argument expression does not evaluate to avalue or evaluates to a non-finiteDouble, that input row does not affectthe percentile.

Theunit of measure attached to the result ofdistribution is the same as the unit of the input.

count   The count of the number of values in a group of values.

Signature:  count(ColumnValue)   →  Int.Delta    (temporal only)
         count(ColumnValue)   →  Int.Gauge

Returns the count of the number of values that have been passed to it. Ifthe argument expression does not evaluate to a value for some input row orevaluates to a non-finiteDouble value, it is not counted.

The output will haveDelta time series kind whennon-sliding temporalaggregation is being done.

Theunit of measure attached to the result ofcountis1.

row_count   The number of input rows encountered.

Signature:  ImplicitRowSetInput  row_count()   →  Int.Delta    (temporal only)
         ImplicitRowSetInput  row_count()   →  Int.Gauge

Therow_count aggregation function returns the count of the number ofrows that this is aggregating over. Unlikecount,row_count does nottake an argument and does not care if a value could be calculated fromthe row.

The output will haveDelta time series kind whennon-sliding temporalaggregation is being done.

Theunit of measure attached to the result ofcountis1.

count_true   The number of true values in a group of boolean values.

Signature:  count_true(Bool)   →  Int.Delta    (temporal only)
         count_true(Bool)   →  Int

The input boolean values are collected and the result isthe number of input values that are true.

If, for some input row, the argument expression does not evaluate to avalue, that input row does not affect the result.

The output will haveDelta time series kind whennon-sliding temporalaggregation is being done.

Theunit of measure attached to the result ofcount_true is1.

min   The minimum of a group of numeric values.

Signature:  min(Num)   →  Num

This collects the numeric values that are passed to it and returns theminimum value. If result type is the same as the input type.

If, for some input row, the argument expression does not evaluate to avalue, that input row does not affect the result.

Theunit of measure attached to the result ofmin is the same as the unit of the input.

max   The maximum of a group of numeric values.

Signature:  max(Num)   →  Num

This collects the numeric values that are passed to it and returns themaximum value. If result type is the same as the input type.

If, for some input row, the argument expression does not evaluate to avalue, that input row does not affect the result.

Theunit of measure attached to the result ofmax is the same as the unit of the input.

diameter   The maximum minus the minimum of a group of numeric values.

Signature:  diameter(Num)   →  Num

This collects the numeric values that are passed to it and returns thedifference between the maximum of the values and the minimum of the values.If result type is the same as the input type (Int orDouble).

If, for some input row, the argument expression does not evaluate to avalue, that input row does not affect the result.

Theunit of measure attached to the result ofdiameter is the same as the unit of the input.

mean   The mean of a group of numeric values.

Signature:  mean(Summable)   →  Double

If the argument expression is numeric (Int or *Double), this returns themean of the values that are passed to it.

If the argument expression is of typeDistribution, this returns the meanof all the values in all the distributions.

If, for some input row, the argument expression does not evaluate to a valueor evaluates to a non-finiteDouble value, that input row does not affectthe mean.

Theunit of measure attached to the result ofmeanis the same as the unit of the input.

stddev   The standard deviation of a group of values.

Signature:  stddev(Summable)   →  Double

If the argument expression is numeric (Int or *Double), this returns thestandard deviation of the values that are passed to it.

If the argument expression is aDistribution value, this returns thestandard deviation of all the values in all the distributions.

If, for some input row, the argument expression does not evaluate to a valueor evaluates to a non-finiteDouble value, that input row does not affectthe standard deviation.

Theunit of measure attached to the result ofstddevis the same as the unit of the input.

variance   The variance of a group of numeric values.

Signature:  variance(Summable)   →  Double

If the argument expression is numeric (Int or *Double), this returns thevariance of the values that are passed to it.

If the argument expression is of typeDistribution, this returns thevariance of all the values in all the distributions.

If, for some input row, the argument expression does not evaluate to a valueor evaluates to a non-finiteDouble value, that input row does not affectthe variance.

There is nounit of measure attached to the result ofvariance function.

covariance   The covariance of a group of pairs of values.

Signature:  covariance(Num,  Num)   →  Double

This returns the covariance of the pairs of numeric (Int or *Double)values that are passed to it.

If, for some input row, either argument expression does not evaluate to avalue or evaluates to a non-finiteDouble value, that input row does notaffect the covariance.

There is nounit of measure attached to the result ofcovariance function.

median   The median of a group of numeric or distribution values.

Signature:  median(Summable)   →  Double

If the argument expression is numeric (Int or *Double), this returns anestimate of the median of the population of values that are passed to it.The median is computed by creating a distribution value from the values inthe population with bucket boundaries that are 10% apart, which bounds theerror in the estimate by that amount.

The bucket specification used to accumlate aDistribution value fromnumeric input to estimate a median ispowers_of(1.05).num_buckets(500).lower(.01). This includes a range ofvalues from.01 to about4e+8. While this handles many use cases, itmight be necessary to use thescale function to adjust the input, forexample fromBy toMiBy or 'MBy' if the range of number of bytes isgoing to be in the gigabyte or terabyte range.

If the argument expression is aDistribution value, this returns anestimate of the median of the merged population of values from all thedistributions. The median is computed by merging all the inputdistributions into one distribution and estimating the median. The accuracyof the median will depend on the bucket boundaries of the inputdistributions.

If, for some input row, the argument expression does not evaluate to a valueor evaluates to a non-finiteDouble value, that input row does not affectthe standard deviation.

Theunit of measure attached to the result ofmedianis the same as the unit of the input.

percentile   A percentile of a group of numeric or distribution values.

Signature:  percentile(Summable,  lit-Num)   →  Double

Thelit-Num argument gives a percentile (in the range 0 to 100).

If the first argument expression is numeric (Int orDouble), thisreturns an estimate of that percentile of the population of values that arepassed to it. The percentile is computed by creating a distribution valuefrom the values in the population with bucket boundaries that are 10% apart,which bounds the error in the estimate by that amount.

The bucket specification used to accumlate aDistribution value fromnumeric input to estimate a percentile ispowers_of(1.05).num_buckets(500).lower(.01). This includes a range ofvalues from.01 to about4e+8. While this handles many use cases, itmight be necessary to use thescale function to adjust the input, forexample fromBy toMiBy or 'MBy' if the range of number of bytes isgoing to be in the gigabyte or terabyte range.

If the argument expression is aDistribution value, this returns anestimate of the percentile of the merged population of values from all thedistributions. The percentile is computed by merging all the inputdistributions into one distribution and estimating the percentile. Theaccuracy of the percentile will depend on the bucket boundaries of the inputdistributions.

If, for some input row, the first argument expression does not evaluate to avalue or evaluates to a non-finiteDouble, that input row does not affectthe percentile.

Theunit of measure attached to the result ofpercentile is the same as the unit of the input.

fraction_less_than   The fraction of a group of values less than a fixed value.

Signature:  fraction_less_than(Summable,  lit-Num)   →  Double

If the first argument is a numeric (Int or *Double) value, this returnsthe fraction of the collection of values passed to the first argument thatare less than thelit-Num argument. In computing this fraction, itignores non-finiteDouble values and not-a-valueInt andDoublevalues.

If the first argument is aDistribution value, this combines thepopulations of all the Distributions it is passed and makes an estimate ofthe fraction of the values in the population of that aggregated distributionthat are less than the value of thelit-Num argument.

Theunit of measure attached to the result offraction_less_than is10^2.%.

fraction_true   The fraction of a group of boolean values that are true.

Signature:  fraction_true(Bool)   →  Double

The input boolean values are collected and the result is aDouble in therange 0 to 1 that is the fraction of input values that are true.

If, for some input row, the argument expression does not evaluate to avalue, that input row does not affect the result.

Theunit of measure attached to the result offraction_true is10^2.%.

any_true   The disjunction of a group of boolean values.

Signature:  any_true(Bool)   →  Bool

Theany_true function calculates the valuetrue if all of its inputvalues aretrue and returnsfalse otherwise.

If, for some input row, the argument expression does not evaluate to avalue, that input row does not affect the result.

all_true   The conjunction of a group of boolean values.

Signature:  all_true(Bool)   →  Bool

Theall_true function calculates the valuetrue if all its input valuesaretrue and returnsfalse otherwise.

If, for some input row, the argument expression does not evaluate to avalue, that input row does not affect the result.

pick_any   The value of any element of a group of values (chosen arbitrarily).

Signature:  pick_any(ColumnValue)   →  FirstArgType

This functions returns one of the values given to it, chosen arbitrarily.

If, for some input row, the argument expression does not evaluate to avalue, that input row does not affect the result.

Theunit of measure attached to the result ofpick_any is the same as the unit of the input, if any.

singleton   The value of the element of a group of values with only one element.

Signature:  singleton(ColumnValue)   →  FirstArgType

This function returns its argument expression value as evaluated on asingle row. It is an error if its argument expression is evaluated andproduces a value for more than one row, even if it evaluates to a previouslyproduced value.

If, for some input row, the argument expression does not evaluate to avalue, that input row does not affect the result.

Theunit of measure attached to the result ofsingleton is the same as the unit of the input.

unique   The common value of a group of values (which must all be the same).

Signature:  unique(Comparable)   →  FirstArgType

Theunique function returns the value that is the same as every valuethat was given to it. If there is no such value (this was given at leasttwo different values), then it generates an error and returns one of thevalues given to it.

If, for some input row, the argument expression does not evaluate to avalue, that input row does not affect the result.

Theunit of measure attached to the result ofuniqueis the same as the unit of the input.

aggregate   Default aggregate value from a group of values of any type.

Signature:  aggregate(Num)   →  Num.Delta    (temporal only)
         aggregate(Distribution)   →  Distribution.Delta    (temporal only)
         aggregate(Num)   →  Num.Gauge    (sliding temporal only)
         aggregate(Distribution)   →  Distribution.Gauge    (sliding temporal only)
         aggregate(Num)   →  Num.FirstArgKind
         aggregate(Distribution)   →  Distribution.FirstArgKind
         aggregate(Bool)   →  Bool
         aggregate(String)   →  String

Theaggregate function does an aggregation that depends on the type ofthe input.

• ForInt andDouble input, it is the same as thesum aggregator.

• ForDistribution input, it is the same as thedistribution aggregator.

• ForBool input, it is the same as theany_trueaggregator.

• ForString input, it is the same as thepick_anyaggregator.

weighted_distribution   A distribution from a group of weighted values.

Signature:  weighted_distribution(Num,  Int,  lit-BucketSpecification)   →  Distribution.Delta    (temporal only)
         weighted_distribution(Num,  Int,  lit-BucketSpecification)   →  Distribution.Gauge

The input values are collected into a distribution result whose bucketspecification is given bylit-Bucketer argument. The first argument isthe value to be added to the distribution and the second argument is theweight of that value. A valueN with a weight ofM is represented byM instances of valueN in the distribution.

If, for some input row, the first or the second argument expression does notevaluate to a value or evaluates to a non-finiteDouble, that input rowdoes not affect the percentile.

Theunit of measure attached to the result ofweighted_distribution is the same as the unit of the input.

Aligning

Aligning functions are use by thealign table operationto produce analigned table, one whose timeseries have points with timestamps at regular intervals.

In addition to its explicitDuration argument, an aligner functiontakes an input time series and a point in timeand produces an output point for that particular time.

Theinterpolate alignment function produces a value at a given time byinterpolating a value from two adjacent input points whose timestampsstraddle the output timestamp.

Thenext_older andnext_younger alignment functions produce the valuefrom the single point in the input time series whose timestamp is nextis just prior to or just after the output timestamp.

Thedelta,rate, anddelta_gauge aligner functions compute theiroutput based on the change in the value of the input time series over thetime window between the output point end time and theDuration argumentearlier. That change in value is computed as follows:

• Thus the value of the input time series at any giventime can be computed by linear interpolation between the nearestpoint before and the nearest point after the output time. The changein value over a given window is the difference between theinterpolated value at the earlier edge of the window and the lateredge.

• The amount of changein the window is the sum of the value of all points whoseextent is entirely within the window and the pro-ratashare of the value of the points whose extent partially overlaps thewindow.

• For aCumulative time series, interpolation of a value between twoadjacent points with the same start time is done by linearinterpolation between the two values. Interpolation between twoadjacent points with different start times (so the start time of thelater point is between the end times of the two points) is handledthis way:

  • If the output time is between the earlier point's end time andthe later point's start time, the result is the earlier point'svalue. (No change between the earlier point and the reset time.)

  • If the output time is between the later points start and end time,then the value is the linear interpolation between zero (at thestart time) and the point's value.

  For aCumulative time series, the change in value over a givenwindow is the difference between the interpolated value at theearlier edge of the window and the later edge plus a correction forresets. For each reset time that falls within the window, the valueof the point just before that reset time is added to the change valueto account for the time series value being reset to 0 at that time.

  The aggregating aligner functions,mean_aligner,int_mean_aligner,apply an aggregation function to the input points that fall in a timewindow whose width is given by theDuration argument and whose lateredge is the timestamp of the output point. The result of thataggregation is the value of the output point.

  The unit of measure of the output of an aligning function is usuallythe same as that of the input. The exceptions are:

  • The output ofrate has the unit of its input divided by theunit 's'.

  • The output ofcount_true_aligner has unit1.

  • The output offraction_true_aligner has unit10^2.%

rate   Compute a rate of change at aligned points in time.

Signature:  ImplicitRowInput  rate([ lit-Duration ])   →  Double.Gauge    (implicit row input)

Therate aligner operates on input time series with a single value columnof numeric (Int or *Double) type. It always produces an output table witha single value column ofDouble type andGauge time series kind .

Therate aligner computes the change in value of the time series over itswindow (as describedhere) and divides that by thewidth of the window in seconds. The window extends from the output pointtime to theDuration parameter time earlier.

The default value for theDuration argument is the alignment period.Unlike the'delta' aligner function, there is no requirementthat the alignment period and window width match.

delta   Compute the change in value at aligned points in time.

Signature:  ImplicitRowInput  delta([ lit-Duration ])   →  InputType.Delta    (implicit row input)

Thedelta aligner operates on input time series with a single valuecolumn ofSummable type (Int,Double, orDistribution) and theoutput is a time series whose value column is of the same type but has aDelta time series kind.

Thedelta_gauge aligner computes the change in value of the input timeseries over the time window between the output time and theDurationargument earlier. The output point's start time is theDuration argumentearlier than the output time (the point's end time).

Thedelta aligner has the requirement that itsDuration argument is thesame as the alignment period it is used to align to. The default value fortheDuration argument is that alignment period.

Because alerting policies require that the alignment window be able tobe different from the alignment period, use thedelta_gauge aligner.

any_true_aligner   Align aBool time series by finding any true value in a window.

Signature:  ImplicitRowInput  any_true_aligner([ lit-Duration ])   →  Bool.Gauge    (implicit row input)

Theany_true_aligner function operates on an input table with a singlevalue column ofBool type and produces an output table with a single valuecolumn ofBool type andGauge time series kind.

TheDuration argument gives the width of a time window for each outputpoint that ends at the time of that output point. If theDurationargument is not given, it defaults to the alignment period. The value of anoutput point istrue if any input point in the window is true and isfalse otherwise.

count_true_aligner   Align aBool time series by counting the true values in a window.

Signature:  ImplicitRowInput  count_true_aligner([ lit-Duration ])   →  Int.Gauge    (implicit row input)

Thecount_true_aligner function operates on an input table with a singlevalue column ofBool type and produces an output table with a single valuecolumn ofInt type andGauge time series kind.

TheDuration argument gives the width of a time window for each outputpoint that ends at the time of that output point. If theDurationargument is not given, it defaults to the alignment period. The value of anoutput point is the number of input points in the window with valuetrue.

delta_gauge   Compute the change in value at aligned points in time as aGauge time series.

Signature:  ImplicitRowInput  delta_gauge([ lit-Duration ])   →  InputType.Gauge    (implicit row input)

Thedelta_gauge aligner operates on input time series with a single valuecolumn ofSummable type (Int,Double, orDistribution) and theoutput is a time series whose value column is of the same type but has aGauge time series kind.

Thedelta_gauge aligner computes the change in value of the input timeseries over its window (as describedhere). Thewindow extends from the output point time to theDuration parameter timeearlier.

The default value for theDuration argument is the alignment period.Unlike the'delta' aligner function, there is no requirementthat the alignment period and window width match.

fraction_true_aligner   Align aBool time series with the fraction of true values in a window.

Signature:  ImplicitRowInput  fraction_true_aligner([ lit-Duration ])   →  Double.Gauge    (implicit row input)

Thefraction_true_aligner function operates on an input table with asingle value column ofBool type and produces an output table with asingle value column ofDouble type andGauge time series kind.

TheDuration argument gives the width of a time window for each outputpoint that ends at the time of that output point. If theDurationargument is not given, it defaults to the alignment period. The value of anoutput point is the fraction of all input points in the window that havethe valuetrue.

int_mean_aligner   Align by finding the mean ofInt values in a window.

Signature:  ImplicitRowInput  int_mean_aligner([ lit-Duration ])   →  Int.Gauge    (implicit row input)

Theint_mean_aligner function operates on an input table with a singlevalue column ofInt type andGauge orDelta time series kind. Itproduces an output table with a single value column ofInt type andGauge time series kind.

TheDuration argument gives the width of a time window for each outputpoint that ends at the time of that output point. If theDurationargument is not given, it defaults to the alignment period. The value of anoutput point is the mean of the input table value points that fall withinthis above window, rounded to the nearest integer value.

interpolate   Compute interpolated values at aligned points in time.

Signature:  ImplicitRowInput  interpolate([ lit-Duration ])   →  InputType.Gauge    (implicit row input)

Theinterpolate aligner operates on an input table with a single valuecolumn of numeric (Int or *Double) type andGauge time series kind.It produces an output table with a singlevalue column of the same type and time series kind.

If the output time for theinterpolate aligner function is the same as theend time of a point in the input time series, that is used for the outputpoint. Otherwise, theinterpolate aligner considers the input pointswhose end time are are the nearest earlier and later points to the outputtime. If these points are within theDuration argument of one another, the output value is the linearinterpolation between those to points at the output time. If there is noinput point earlier than the output time or no input point later than theoutput time or if the two input points are not withinDuration argumentof each other, no output value is produced.

The default for theDuration argument is twice the alignment period.

mean_aligner   Align by finding the mean of values in a window.

Signature:  ImplicitRowInput  mean_aligner([ lit-Duration ])   →  Double.Gauge    (implicit row input)

Themean_aligner function operates on an input table with a single valuecolumn of numeric type. (Int orDouble) andGauge orDelta timeseries kind. It produces an output table with a single value column ofDouble type andGauge time series kind.

TheDuration argument gives the width of a time window for each outputpoint that ends at the time of that output point. If theDurationargument is not given, it defaults to the alignment period. The value of anoutput point is the mean of the input table value points that fall withinthis above window.

next_older   Aligned points in time by moving from an earlier to later time.

Signature:  ImplicitRowInput  next_older([ lit-Duration ])   →  InputType.Gauge    (implicit row input)

Thenext_older aligner operates on time series with any number of valuecolumns of any type, but all withGauge time series kind. Itproduces an output columns of the same type and time series kind.

Thenext_older aligner creates an output point at by finding thelatest input point whose end time is no later than the output time andwhose end time is no further away from the output time than theDurationargument. If there is no such input point, no output point is created.

The default for theDuration argument is twice the alignment period.

next_younger   Aligned points in time by moving from a later to earlier time.

Signature:  ImplicitRowInput  next_younger([ lit-Duration ])   →  InputType.Gauge    (implicit row input)

Thenext_younger aligner operates on time series with any number of valuecolumns of any type, but all withGauge time series kind. Itproduces an output columns of the same type and time series kind.

Thenext_younger aligner creates an output point at by finding theearliest input point whose end time is no earlier than the output time andwhose end time is no further away from the output time than theDurationargument. If there is no such input point, no output point is created.

The default for theDuration argument is twice the alignment period.

Manipulating Units

These functions change the units of the expressions they are appliedto.

scale   Scale a value to a different unit of measure.

Signature:  scale(value: Num,  unit: [ lit-String ])   →  Double
         scale(value: Duration,  unit: [ lit-String ])   →  Double
         scale(value: Date,  unit: [ lit-String ])   →  Double

Thescale function returns thevalue, converted todouble, if necessary, and possibly scaled so it has the units given by theunit argument.

If theunit argument is not given, then thescale function merelyconverts itsvalue argument to double, without changing its units exceptin cases where automatic scaling is invoked as describedhere. In that case, theunit argument is suppliedimplicitly, andscale behaves as it normally does with two arguments.

Theunit argument, if given, must be a validUCUM code string for the unit that thevalue argumentis to be scaled to. In this case,the returned value denotes the same physical quantity as thevalueargumentbut expressed in the units given by theunit argument. This is done bymultiplying the argument by the appropriate scaling factor.

For example, the expressionscale(3 "min", "s") will convert the value3with units minutes (min) to the value180 with units seconds (s). Thesame amount of time, expressed in different units.

It is an error if thevalue argument has no unit or if the unit of thevalueargument does not have the samedimension as the unitcode given as theunit argument, if given. If they do not have the samedimension, it is not possible to scale thevalue argument to have thedimension given by theunit argument.

For example, it is an error to sayscale(3 "km", "m/s"), which asksto scale 3 kilometers into some number of meters per second, becausekilometers has the dimension "distance" and meters per second has thedimension "distance per time" (speed). There is no scale factor that canturn distance into speed. One would need to divide the distance by somevalue with units of time to make this work. For examplescale(3 "km" / 10"min", "m/s") will scale.3 "km/min" to5 "m/s".

If thevalue argument is aDate orDuration argument, then theunitargument must give a unit of time (for example"s","h", or"wk").The returned value will be aDouble value designating the amount of timegiven by thevalue in the units given by theunit argument. ForaDate value, this will be the length of time since the Unix epoch.

For example,scale(1m, "s") will result in a value of60.0 with unitss, andscale(d'1970/01/01-01:00:00+00', "h") results in a value of1.0with units `h' (one hour into the Unix epoch).

cast_units   Set the unit of measure of a value.

Signature:  cast_units(Summable,  lit-String)   →  FirstArgType

Thecast_units function returns the unchanged value of the first argumentbut sets the unit of measure for that value to be that given by the secondargument string.

The string must be a valueUCUM code string for thedesired unit. Any unit the first argument may have had before applying thisfunction is ignored.

Periodic Window

The periodic window functions are used to annotate aDuration actualargument passed to aWindowDuration argumentthat specifies a window width used to select input points to a periodiccalculation. Such an argument is passed to thegroup_by table operation which outputsaligned time series. Thewindow andslidingfunctions constrain the input window width according to the outputalignment period.

Thewindow function indicates that the alignment period and the windowwidth must be the same, making the input point windows benon-overlapping. Because alerting policies require that the alignmentwindow be able to be different from the alignment period, don't usethewindow function in alerting policies.

Thesliding function indicates that the alignment period can be smallerthan the window width, causing input windows to overlap.

window   Indicates a window that is the same as the alignment period.

Signature:  window([ lit-Duration ])   →  lit-WindowDuration

Thewindow function annotates aDuration actualargument passed to aWindowDuration argumentthat specifies a window width used in a calculation that producesaligned time series. It requires that the window width andthe output alignment period both be the same as itsDuration argument.If theDuration argument is not given, then it specifies that the window widthbe the output alignment period, however that is defined.

Because alerting policies require that the alignment window be able to bedifferent from the alignment period, don't use thewindow function inalerting policies.

For example, the table operation|group_bywindow(5m), .mean producesoutput points that are the mean value of inputs points falling within a 5mwindow of the output end time. Thewindow function annotates the5mwindow width to require that the alignment period of thegroup_by be 5minutes as well. The table operation| group_by window(), .mean alsorequires the window width to be the same as the output alignment period, butdoes not specify what that must be.

sliding   Indicates a window that is sliding (overlapping) rather than disjoint.

Signature:  sliding(lit-Duration)   →  lit-WindowDuration

Thesliding function annotates aDuration actualargument passed to aWindowDuration argumentthat specifies a window width used in a calculation that producesaligned time series. It requires that the window width beitsDuration argument and requires that the alignment period be no larger(but allows it to be smaller).

For example, the table operation|group_bysliding(5m), .mean producesoutput points that are the mean value of inputs points falling within a 5mwindow of the output end time. Thesliding function annotating the5mwindow width indicates that alignment period of thegroup_by can be anytime no larger than 5 minutes. If there is an| every 1m table operationindicating 1 minute alignment, then the 4 minutes of each 5 minute windowwill overlap the window of the next-earlier output point.

requested_period   The external requested output alignment period.

Signature:  requested_period()   →  lit-Duration

If a query is given in an environment (such as Metrics Explorer or adashboard) which specifies the period of the query's output using a widgetthat is outside of the query itself,requested_period() returns the valueof the externally requested period.

If no externally requested period is given for the query, this will returnthe default period of1m.

Therequested_period() function can be used in any context in a query thataccepts a literal duration, including theevery tableoperation, the window argument ofaligner functions, andthe window argument of thegroup_by table operation.

Example, usingrequested_period() to specify the output period of a query:

  fetch  gce_instance :: compute.googleapis.com/instance/cpu/usage_time  | group_by [], mean(val())  | every requested_period()

Example, usingrequested_period() to specify the output period of a queryand an aligner window that is twice the output period, but at least2m:

  fetch  gce_instance :: compute.googleapis.com/instance/cpu/usage_time  | align rate(if(requested_period() < 1m, 2m, requested_period() * 2))  | group_by [], mean(val())  | every requested_period()

Distribution

count_from   The number of values in a distribution value.

Signature:  count_from(Distribution.CumulativeOK)   →  Int.FirstArgKind

Thecount_from function returns the size of the population of values inits input Distribution value.

Theunit of measure attached to the result ofcount_from is1.

sum_from   The sum of the values in a distribution value.

Signature:  sum_from(Distribution.CumulativeOK)   →  Double.FirstArgKind

Thesum_from function returns the sum of all the values contained inits input Distribution value.

The result ofsum_from has the sameunit ofmeasure as the input.

mean_from   The mean of the values in a distribution value.

Signature:  mean_from(Distribution)   →  Double

Themean_from function returns the arithmetic mean of all the valuescontained in its input Distribution value.

The result ofmean_from has the sameunit ofmeasure as the input.

stddev_from   The standard deviation of the values in a distribution value.

Signature:  stddev_from(Distribution)   →  Double

Thestddev_from function returns the variance of the population thevalues contained in its input Distribution value.

The result ofstddev_from has the sameunit ofmeasure as the input.

variance_from   The variance of the values in a distribution value.

Signature:  variance_from(Distribution)   →  Double

Thevariance_from function returns the variance of the population thevalues contained in its input Distribution value.

The result of the 'variance_from' function has nounit of measure.

median_from   The median of the values in a distribution value.

Signature:  median_from(Distribution)   →  Double

Themedian_from function returns an estimate of the median of thepopulation the values contained in its input Distribution value.

The result ofmedian_from has the sameunit ofmeasure as the input.

percentile_from   A percentile of the values in a distribution value.

Signature:  percentile_from(Distribution,  lit-Num)   →  Double

Thepercentile_from function returns an estimate of the percentile of thepopulation the values contained in its input Distribution value. TheNum argument gives the percentile to estimate as a number between 0 and100.

The result ofpercentile_from has the sameunit ofmeasure as the input.

fraction_less_than_from   The fraction of values in a distribution that are less than a fixed value.

Signature:  fraction_less_than_from(Distribution,  lit-Num)   →  Double

Thefraction_less_than_from function returns an estimate of the fractionof the population the values contained in its input Distribution valuethat are less than itsNum argument.

Theunit of measure attached to the result offraction_less_than is10^2.%.

bounded_percentile_from   A percentile of the values within a bound in a distribution value.

Signature:  bounded_percentile_from(Distribution,  lit-Num,  [ lit-Num ],  [ lit-Num ])   →  Double

Thebounded_percentile_from function operates on a subset of the valuecontained in the input Distribution. An estimate is made of the populationof values that are greater than the secondNum parameter, if given, andless than or equal to the thirdNum parameter, if given. At least oneor the other of the second and thirdNum arguments must be given and, ifboth are given, the second must be less than the third.

This returns an estimate of the percentile of that estimated population ofvalues. The firstNum argument gives the percentile to estimate as anumber between 0 and 100.

The result ofbounded_percentile_from has the sameunit ofmeasure as the input.

rebucket   Distribution value converted to a new bucket specification.

Signature:  rebucket(Distribution.Delta,  lit-BucketSpecification)   →  Distribution.Delta
         rebucket(Distribution,  lit-BucketSpecification)   →  Distribution

This converts the input Distribution value to a Distribution value whosebucket specification is that given in the second argumentBucketSpecification.

This distributes the counts from each bucket in the input Distribution tothe buckets of the output Distribution under the assumption that the valuescounted in a bucket are evenly distributed across the range of the bucket.The output Distribution has the same total count as the input Distributionbut the counts are distributed differently across the output Distributionbuckets. The output Distribution has the same sum, mean, and standarddeviation as the input Distribution.

Bucket Specifier

A Distribution value has a histogram made up of buckets. Each bucket isassociated with a range of values and contains a count of the values in theDistribution that fall within that range. Every Distribution has aBucket Specification that describes the boundaries for the buckets in aDistribution value. The functions in this section generate BucketSpecifications.

powers_of   A bucket specification with exponentially increasing bucket boundaries.

Signature:  powers_of(lit-Num)   →  lit-BucketSpecification

Thepowers_of function returns a bucket specifications where the upperbound of each bucket is fixed factor (given by theNum argument) times thelower bound. Thus the bucket size is exponentially increasing and the errorfor computing percentiles is a bounded by a constant factor of the truevalue.

This does not set the number of buckets or the lower bound of the firstbucket, both of which must either be specified (by 'num_buckets' and'lower') or will take the default values (30 buckets, lower bound of 1.0).If the bucket specification is given bypowers_of, the lower bound must begreater than 0.

The following example gives a bucket specification with 50 buckets whosesize grows exponentially at a rate of 1.1, starting at the value 100. Sothe bucket boundaries are 100, 110, 121, 133.1, and so on.

powers_of(1.1).num_buckets(30).lower(100.0)

fixed_width   A bucket specification with equal-sized buckets.

Signature:  fixed_width(lit-Num)   →  lit-BucketSpecification

Thefixed_width function returns a bucket specifications where the upperbound of each bucket is fixed amount (given by theNum argument) more thanthe lower bound. Thus the bucket size is fixed.

This does not set the number of buckets or the lower bound of the firstbucket, both of which must either be specified (by 'num_buckets' and'lower') or will take the default values (30 buckets, lower bound of 1.0).

The following example gives a bucket specification with 100 buckets of size1, staring at 1. This is a good specification for a distribution ofpercentage values.

fixed_width(1).num_buckets(100)

custom   A bucket specification from a list of bucket boundaries.

Signature:  custom(lit-Num...)   →  lit-BucketSpecification

Thecustom function returns a bucket specification with explicitly givenbucket bounds. The function takes multiple numeric arguments which must begiven in increasing order. The lower bound of the first bucket is given bythe first argument and the upper bound of the last bucket is given by thelast argument. Each intermediate argument gives the upper bound of theprevious bucket and the upper bound of the next bucket.

This completely determines the bucket specification, giving the number ofbuckets and the exact bound of each.

The following example gives a bucket specification with 3 buckets. Thefirst has boundary 3 and 27, the second 27 and 105, and the third 105 and277.

custom(3,27,105,277)

num_buckets   Sets the number of buckets in a bucket specification.

Signature:  num_buckets(lit-BucketSpecification,  lit-Num)   →  lit-BucketSpecification

When applied to a bucket specification that does not have the number ofbuckets determined, thenum_buckets function returns a bucketspecification with a number of buckets given by itsNum argument. All theother aspects of the input bucket specification are preserved.

It is an error to applynum_buckets to a bucket specification that alreadyhas the number of buckets determined.

bounds   Sets the lower bound of the first bucket and upper bound of the last.

Signature:  bounds(lit-BucketSpecification,  lit-Num,  lit-Num)   →  lit-BucketSpecification

When applied to a bucket specification that does not have the lower bound ofthe first bucket or the upper bound of the last bucket determined,thebounds function returns its argumentBucketSpecificationwith the lower bound of its first bucket given by its firstNum argument and the upper bound of its last bucket given by the secondNum argument. All the other aspects of the input bucket specification arepreserved.

It is an error to applybounds to a bucket specification that alreadyhas either the lower bound of the first bucket or upper bound of the lastbucket determined.

lower   Sets the lower bound of the first bucket in a bucket specification.

Signature:  lower(lit-BucketSpecification,  lit-Num)   →  lit-BucketSpecification

When applied to a bucket specification that does not have the lower bound ofthe first bucket determined, thelower function returns its argumentBucketSpecification with the lower bound of its first bucket given by itsNum argument. All the other aspects of the argument bucket specification arepreserved.

It is an error to applylower to a bucket specification that alreadyhas the lower bound of the first bucket determined.

Miscellaneous

cast_double   ConvertInt value toDouble.

Signature:  cast_double(Num.CumulativeOK)   →  Double.FirstArgKind

Thecast_double function takes a singleInt argument and returnsthe nearestDouble value.

The result ofcast_double has the sameunit ofmeasure as the input.

cast_gauge   Cast aCumulative orDelta time series value toGauge.

Signature:  cast_gauge(ColumnValue.CumulativeOK)   →  FirstArgType.Gauge

Thecast_gauge functions returns the value of its argument but changesthe time series kind of the value toGauge.

If this results in an output table without value columns that haveDeltatime series kind, the output table will have no start time column.

The result ofcast_gauge has the sameunit ofmeasure as the input.

within   Specifies the window of the sort value calculation.

Signature:  within(ColumnValue,  [ lit-DateOrDuration ],  [ lit-DateOrDuration ])   →  Windowed.FirstArgKind

Thewithin function decorates the expression bound to theWindowed(Num)sort value argument of thetop orbottomtable operation. It specifies the window in which the sort value expressionis evaluated by specifying one or two out of three of the values: theoldest (starting) time of the window, the youngest (ending) time of thewindow, or the duration of the window.

If either of the two arguments ofwithin is a positiveDuration, thenthat sets the width of the window. At most one of the arguments can be suchaDuration.

If the first argument is aDate, then that specifies the starting time.If the second argument is aDate, that specifies the ending time. If bothareDate values, the second must be later in time than the first. ADate argument can be given as aDate literal or with a negativeDuration literal. In the later case, the time is the specifiedDurationbefore the ending time of the outer query window (see thewithin table operation).

If the first argument is not given, it defaults to the starting time of theouter query window. If the second argument is not given, it defaults to theending time of the outer query window.

For example.mean().within(1h,-2h) indicates that themax reducershould be applied to all the points in the input time series whose end timeis within a window of 1 hour width, ending 2 hours ago.Themean aggregator is applied to all input points whoseend time is in this window.

For examplemax(val()).within(10m) indicates that themax reducershould be applied to all the in the input time series whose end time fallswithin the time range between the query end time and 10 minutes earlier.Themax aggregator is applied to all input points whoseend time is in this window.

Index of Table Operations and Functions

An index to all the table operations and functions.

• abs   Absolute value.
• absent_for   Create a condition for the absence of input.
• add   The sum of two numbers.
• adjacent_delta   The change in value between an input point and next-earlier point.
• adjacent_rate   The rate of change between the input and next-earlier points (rows).
• aggregate   Default aggregate value from a group of values of any type.
• align   Produces an aligned table using an alignment function.
• all_true   The conjunction of a group of boolean values.
• and   The logical and of two boolean values.
• any_true   The disjunction of a group of boolean values.
• any_true_aligner   Align aBool time series by finding any true value in a window.
• ascii_to_lower   Change ASCII upper case letter characters to lower case.
• ascii_to_upper   Change ASCII lower case letter characters to upper case.
• bottom   Selects the bottom time series by a sort-value expression.
• bottom_by   Selects time series by a sort-value expression in different groups.
• bounded_percentile_from   A percentile of the values within a bound in a distribution value.
• bounds   Sets the lower bound of the first bucket and upper bound of the last.
• cast_double   ConvertInt value toDouble.
• cast_gauge   Cast aCumulative orDelta time series value toGauge.
• cast_units   Set the unit of measure of a value.
• concatenate   String concatenation.
• condition   Add a boolean condition column to the input table.
• count   The count of the number of values in a group of values.
• count_from   The number of values in a distribution value.
• count_true   The number of true values in a group of boolean values.
• count_true_aligner   Align aBool time series by counting the true values in a window.
• covariance   The covariance of a group of pairs of values.
• custom   A bucket specification from a list of bucket boundaries.
• delta   Compute the change in value at aligned points in time.
• delta_gauge   Compute the change in value at aligned points in time as aGauge time series.
• diameter   The maximum minus the minimum of a group of numeric values.
• distribution   A distribution from a group of numeric or distribution values.
• div   The ratio of two numbers.
• end   The ending time of the input point (row).
• eq   Equal.
• every   Specifies the period for aligned table output.
• exp   e raised to a power.
• false   The boolean value false.
• fetch   Produces a table from the database.
• fetch_cumulative   Produces a table ofCumulative time series from the database.
• filter   Filters rows from an input table by a predicate.
• filter_ratio   Computes the ratio of two filtered sums of the input value column.
• filter_ratio_by   Computes a grouped ratio of two filtered sums of the input value column.
• fixed_width   A bucket specification with equal-sized buckets.
• format   FormatInt64,Double, orString as aString.
• fraction_less_than   The fraction of a group of values less than a fixed value.
• fraction_less_than_from   The fraction of values in a distribution that are less than a fixed value.
• fraction_true   The fraction of a group of boolean values that are true.
• fraction_true_aligner   Align aBool time series with the fraction of true values in a window.
• ge   Greater than or equal.
• graph_period   Specifies the preferred output period for drawing time series graphs.
• group_by   Aggregates rows by mapped time-series identifier and time window.
• gt   Greater than.
• has   True if a set argument contains a particular value.
• has_value   True if an argument expression computes a value.
• hash_tsid   Return a hash of the time series identifier columns.
• ident   Identity table operation: no change to the input table.
• if   A value conditionally chosen from two values.
• int_ceil   Upper bound integer.
• int_div   The quotient from the division of two integers.
• int_floor   Lower bound integer.
• int_mean_aligner   Align by finding the mean ofInt values in a window.
• int_round   Nearest integer.
• interpolate   Compute interpolated values at aligned points in time.
• join   Natural join of multiple tables.
• le   Less than or equal.
• log   Natural logarithm.
• lower   Sets the lower bound of the first bucket in a bucket specification.
• lt   Less than.
• map   Rewrites the time-series identifier and value columns of each row in a table.
• max   The maximum of a group of numeric values.
• mean   The mean of a group of numeric values.
• mean_aligner   Align by finding the mean of values in a window.
• mean_from   The mean of the values in a distribution value.
• median   The median of a group of numeric or distribution values.
• median_from   The median of the values in a distribution value.
• metric   Produces the table for a specific metric type from a set of tables.
• min   The minimum of a group of numeric values.
• mul   The product of two numbers.
• ne   Not equal.
• neg   The negative of a number.
• next_older   Aligned points in time by moving from an earlier to later time.
• next_younger   Aligned points in time by moving from a later to earlier time.
• not   The logical negation of a boolean value.
• num_buckets   Sets the number of buckets in a bucket specification.
• older   A value from the next-earlier point (row) in a time series.
• or   The logical or of two boolean values.
• or_else   A value or, if it is not a value, another value.
• outer_join   Outer natural join of two tables.
• percentile   A percentile of a group of numeric or distribution values.
• percentile_from   A percentile of the values in a distribution value.
• pick_any   The value of any element of a group of values (chosen arbitrarily).
• pick_bottom_rows   Picks rows by minimal sort-value expression.
• pick_top_rows   Picks rows by maximal a sort-value expression.
• pos   Identity for numeric inputs.
• power   One number to the power of another.
• powers_of   A bucket specification with exponentially increasing bucket boundaries.
• rate   Compute a rate of change at aligned points in time.
• ratio   Computes the ratio of value columns of two aligned input tables.
• re_extract   Extract values matched by a regular expression in another string.
• re_full_match   True if a regular expression matches the whole of a string value.
• re_global_replace   Replace all matches of a regular expression in another string.
• re_partial_match   True if a regular expression matches some part of string value.
• re_replace   Replace the first match of a regular expression in another string.
• rebucket   Distribution value converted to a new bucket specification.
• rem   The remainder from the division of two integers.
• requested_period   The external requested output alignment period.
• row_count   The number of input rows encountered.
• scale   Scale a value to a different unit of measure.
• singleton   The value of the element of a group of values with only one element.
• sliding   Indicates a window that is sliding (overlapping) rather than disjoint.
• sqrt   Square root.
• start   The starting time of the input point (row).
• stddev   The standard deviation of a group of values.
• stddev_from   The standard deviation of the values in a distribution value.
• string_to_double   ConvertString toDouble.
• string_to_int64   ConvertString toInt.
• string_to_timestamp   ConvertString toDate using date format and optional timezone.
• sub   The difference of two numbers.
• sum   The sum of a group of numeric values.
• sum_from   The sum of the values in a distribution value.
• time_shift   Shift time series forward in time.
• timestamp_to_string   ConvertTimestamp toString using date format and optional timezone.
• top   Selects the top time series by a sort-value expression.
• top_by   Selects time series by a sort-value expression in different groups.
• true   The boolean value true.
• unaligned_group_by   Aggregates rows by mapped time-series identifier without alignment.
• union   Union of multiple tables.
• union_group_by   Aggregates rows from multiple tables.
• unique   The common value of a group of values (which must all be the same).
• utf8_normalize   Unicode string suitable for case-folding comparison.
• val   A value column's value in the input point (row).
• value   Rewrites the value columns of each row in a table.
• variance   The variance of a group of numeric values.
• variance_from   The variance of the values in a distribution value.
• weighted_distribution   A distribution from a group of weighted values.
• window   Specifies the window for alignment operations.
• window   Indicates a window that is the same as the alignment period.
• within   Specifies the window of the sort value calculation.
• within   Specifies the time range of the query output.