DocumentationGrafana AgentFlow modeConceptsConfiguration languageExpressionsTypes and values

Types and values

River uses the following types for its values:

• number: Any numeric value, like 3 or 3.14.
• string: A sequence of Unicode characters representing text, like "Hello, world!".
• bool: A boolean value, either true or false.
• array: A sequence of values, like [1, 2, 3]. Elements within the list are indexed by whole numbers, starting with zero.
• object: A group of values identified by named labels, like { name = "John" }.
• function: A value representing a routine that runs with arguments to compute another value, like env("HOME"). Functions take zero or more arguments as input and always return a single value as output.
• null: A type that has no value.

Naming convention

In addition to the preceding types, the [component reference][] documentation uses the following conventions for referring to types:

• any: A value of any type.

• map(T): an object with the value type T. For example, map(string) is an object where all the values are strings. The key type of an object is always a string or an identifier converted into a string.

• list(T): an array with the value typeT. For example, list(string) is an array where all the values are strings.

• duration: a string denoting a duration of time, such as "1d", "1h30m", "10s". Valid units are:

  • d for days.
  • h for hours.
  • m for minutes.
  • s for seconds.
  • ms for milliseconds.
  • ns for nanoseconds.

  You can combine values of descending units to add their values together. For example, "1h30m" is the same as "90m".

Numbers

River handles integers, unsigned integers, and floating-point values as a single ’number’ type, simplifying writing and reading River configuration files.

river Copy

3    == 3.00     // true
5.0  == (10 / 2) // true
1e+2 == 100      // true
2e-3 == 0.002    // true

Strings

Strings are represented by sequences of Unicode characters surrounded by double quotes "".

river Copy

"Hello, world!"

A \ in a string starts an escape sequence to represent a special character. The following table shows the supported escape sequences.

Raw strings

Raw strings are represented by sequences of Unicode characters surrounded by backticks ``. Raw strings don’t support any escape sequences.

river Copy

`Hello, "world"!`

Within the backticks, any character may appear except a backtick. You can include a backtick by concatenating a double-quoted string that contains a backtick using +.

A multiline raw string is interpreted exactly as written.

river Copy

`Hello,
"world"!`

The preceding multiline raw string is interpreted as a string with the following value.

string Copy

Hello,
"world"!

Bools

Bools are represented by the symbols true and false.

Arrays

You construct arrays with a sequence of comma-separated values surrounded by square brackets [].

river Copy

[0, 1, 2, 3]

You can place values in array elements on separate lines for readability. A comma after the final value must be present if the closing bracket ] is on a different line than the final value.

river Copy

[
  0,
  1,
  2,
]

Objects

You construct objects with a sequence of comma-separated key-value pairs surrounded by curly braces {}.

river Copy

{
  first_name = "John",
  last_name  = "Doe",
}

You can omit the comma after the final key-value pair if the closing curly brace } is on the same line as the final pair.

river Copy

{ name = "John" }

If the key isn’t a valid identifier, you must wrap it in double quotes like a string.

river Copy

{
  "app.kubernetes.io/name"     = "mysql",
  "app.kubernetes.io/instance" = "mysql-abcxyz",
  namespace                    = "default",
}

Functions

You can’t construct function values. You can call functions from the standard library or export them from a component.

Null

The null value is represented by the symbol null.

Special types

Secrets

A secret is a special type of string that’s never displayed to the user. You can assign string values to an attribute expecting a secret, but never the inverse. It’s impossible to convert a secret to a string or assign a secret to an attribute expecting a string.

Capsules

A capsule is a special type that represents a category of internal types used by Grafana Agent Flow. Each capsule type has a unique name and is represented to the user as capsule("<SOME_INTERNAL_NAME>"). You can’t construct capsule values. You can use capsules in expressions as any other type. Capsules aren’t inter-compatible, and an attribute expecting a capsule can only be given a capsule of the same internal type. If an attribute expects a capsule("prometheus.Receiver"), you can only assign a capsule("prometheus.Receiver") type. The specific type of capsule expected is explicitly documented for any component that uses or exports them.

In the following example, the prometheus.remote_write component exports a receiver, which is a capsule("prometheus.Receiver") type. You can use this capsule in the forward_to attribute of prometheus.scrape, which expects an array of capsule("prometheus.Receiver").

river Copy

prometheus.remote_write "default" {
  endpoint {
    url = "http://localhost:9090/api/v1/write"
  }
}

prometheus.scrape "default" {
  targets    = [/* ... */]
  forward_to = [prometheus.remote_write.default.receiver]
}