Work with records

A record type is a set of key-value pairs (also known as properties). Keys (also known as labels) are strings. Values can be any data type. Each property can have a different value type.

• Record syntax
• Reference values in a record
• Operate on records

Record syntax

A record literal contains a set of key-value pairs (properties) enclosed in curly brackets ({}). Properties are comma-delimited. Property keys must be strings and can optionally be enclosed in double quotes ("). If a property key contains whitespace characters or only numeric characters, you must enclose the property key in double quotes. Property keys are associated to values by a colon (:). Values can be any type.

Example records

{foo: "bar", baz: 123.4, quz: -2}

{"Company Name": "ACME", "Street Address": "123 Main St.", id: 1123445}

Reference values in a record

Flux records are key-indexed. To reference values in a record, use dot notation or bracket notation and specify the key to reference.

• Dot notation
• Bracket notation
• Reference nested records
• Reference keys statically

Dot notation

Specify the record to access followed by a period (.) and the property key.

c = {name: "John Doe", address: "123 Main St.", id: 1123445}

c.name
// Returns John Doe

c.id
// Returns 1123445

Bracket notation

Specify the record to access followed by the property key enclosed in double quotes and square brackets ([""]).

c = {"Company Name": "ACME", "Street Address": "123 Main St.", id: 1123445}

c["Company Name"]
// Returns ACME

c["id"]
// Returns 1123445

Reference nested records

To reference nested records, use chained dot or bracket notation for each nested level.

customer = 
    {
        name: "John Doe",
        address: {
            street: "123 Main St.",
            city: "Pleasantville",
            state: "New York"
        }
    }

customer.address.street
// Returns 123 Main St.

customer["address"]["city"]
// Returns Pleasantville

customer["address"].state
// Returns New York

Reference keys statically

Record keys can only be referenced statically, meaning you cannot dynamically specify a key to access. For example:

key = "foo"
o = {foo: "bar", baz: 123.4}

o.key
// Error: type error: record is missing label key

To dynamically reference keys in a composite type, consider using a dictionary.

Operate on records

• Extend a record
• List keys in a record
• Compare records
• Return the string representation of a record
• Include the string representation of a record in a table

Extend a record

Use the with operator to extend a record. The with operator overwrites record properties if the specified keys exists or adds the new properties if the keys do not exist.

c = {name: "John Doe", id: 1123445}

{c with spouse: "Jane Doe", pet: "Spot"}
// Returns {id: 1123445, name: John Doe, pet: Spot, spouse: Jane Doe}

List keys in a record

1. Import the experimental package.
2. Use experimental.objectKeys to return an array of keys in a record.

import "experimental"

c = {name: "John Doe", id: 1123445}

experimental.objectKeys(o: c)
// Returns [name, id]

Compare records

Use the == comparison operator to check if two records are equal. Equality is based on keys, their values, and types.

{id: 1, msg: "hello"} == {id: 1, msg: "goodbye"}
// Returns false

{foo: 12300.0, bar: 34500.0} == {bar: float(v: "3.45e+04"), foo: float(v: "1.23e+04")}
// Returns true

Return the string representation of a record

Use display() to return the Flux literal representation of a record as a string.

x = {a: 1, b: 2, c: 3}

display(v: x)

// Returns "{a: 1, b: 2, c: 3}"

Include the string representation of a record in a table

Use display() to return the Flux literal representation of a record as a string and include it as a column value.

import "sampledata"

sampledata.string()
    |> map(fn: (r) => ({_time: r._time, exampleRecord: display(v: {tag: r.tag, value:r._value})}))

Output