values(column_1, ..., column_n, tuple(...), ...)

Builds a small Table from literal rows. values() is a dataset function: it is legal only as a dataset binding, @name <- values(...) or <- values(...). It is not a verb and not a scalar function.

values() is enabled per account. On an account without it, every call fails with "values" input is not enabled for this customer. The stage that calls values() must also declare at least one dataset input, even when <- values(...) replaces that input. A stage with no input fails with stage must define at least one data input.

The call names the columns first, then one tuple(...) per row:

@countries <- values("code", "name", tuple("US", "United States"), tuple("JP", "Japan"))

Each tuple(...) argument is a cell: any storable expression that does not reference a column. Examples include literals, arithmetic, durations, calls such as parse_json, parse_isotime, and ipv4, and typed nulls. Aggregation and window functions are rejected, because a cell has no row set to compute over. The number of arguments must match the number of column names, and the cells in one column must share a type. An int64 cell and a float64 cell in the same column widen that column to float64.

The result is a Table. It has no valid_from, no valid_to, and no declared key. A column may contain the same value on more than one row; a later lookup or join then matches every such row. A call may contain at most 16384 rows.

Bind values() and use it as a reference table:

  • Look up a label, including a composite key (region and service together) and a chain of lookups.
  • Attach a threshold or a latency band, then filter on the attached column.
  • Keep rows that match an allow list by looking the key up, attaching a column other than the key, and dropping the rows where that column is null.

A pipeline that reads only from values() stays a Table. Publishing a dataset requires a time column, so turn the table into an event or interval first:

<- values("tsns", "name", tuple(10, "ada"), tuple(20, "alan"))
make_col ts:from_nanoseconds(tsns)
make_event ts

union requires both sides to have the same dataset kind. values() is a Table, so make it an event or interval before unioning it with an event or interval dataset.

Examples

<- values("name", "age", tuple("ada", 36), tuple("alan", 41))

A binding with no name replaces the stage input with the literal table.

Before values(), the same two rows had to be built from a real dataset. Aggregate it down to one row, store the rows as a JSON array of objects, flatten the array into one row per element, then cast each field back out of the variant value:

statsby c:count(1), group_by()
make_col rows:parse_json('[{"name":"ada","age":36},{"name":"alan","age":41}]')
flatten_single rows
make_col name:string(_c_rows_value.name), age:int64(_c_rows_value.age)
pick_col name, age

That workaround scans the input dataset only to get one row, and loses the column types until every field is cast. values() does not read rows from the stage input (the stage must still declare one) and types each column from its cells.

<- values(
    "host", "country_code",
    tuple("web-1", "US"),
    tuple("web-2", "JP"),
    tuple("web-3", "DE")
)
@countries <- values("code", "name", tuple("US", "United States"), tuple("JP", "Japan"))
lookup on(country_code=@countries.code), country:@countries.name

Attach a label from a literal table. web-1 gets United States and web-2 gets Japan. DE is not in the table, so web-3 keeps its row with a null country: lookup never drops rows.

Before values(), this mapping was commonly written as a case(country_code = "US", "United States", country_code = "JP", "Japan") expression in every query that needed it. With a dataset as the stage input instead of the first values() call, the input keeps its time column, so the lookup stays accelerable.

<- values(
    "service", "requests",
    tuple("api", 900),
    tuple("web", 450),
    tuple("debug", 5),
    tuple("canary", 12)
)
@deny <- values("service", "reason", tuple("debug", "internal"), tuple("canary", "synthetic"))
lookup on(service=@deny.service), reason:@deny.reason
filter is_null(reason)
drop_col reason

Drop the rows on a deny list, the inverse of an allow list. lookup fills reason only for debug and canary, so filter is_null(reason) keeps api and web, and drop_col removes the helper column. The reason column documents why each entry is on the list.

Before values(), this was a filter service != "debug" and service != "canary" expression that grew by one clause per entry.

@expected <- values("service", tuple("api"), tuple("db"), tuple("web"))
@expected_events <- @expected {
    make_col valid_from:parse_isotime("2026-01-01T00:00:00Z")
    make_event valid_from
}
union @expected_events
statsby max_latency_ms:max(latency_ms), group_by(service)

Make every expected service appear in the result, even one with no data. The stage input is an Event dataset with service and latency_ms columns. union requires both sides to have the same dataset kind, so the second binding turns the values() Table into an Event dataset first. The placeholder rows have no latency_ms, so a service with no events gets a null max_latency_ms instead of a missing row.

values() cannot take a { ... } block itself. Bind it, then shape it in a second binding as shown.

<- values(
    "start", "end", "service", "reason",
    tuple(parse_isotime("2026-10-01T02:00:00Z"), parse_isotime("2026-10-01T04:00:00Z"), "db", "upgrade"),
    tuple(parse_isotime("2026-10-08T02:00:00Z"), parse_isotime("2026-10-08T03:00:00Z"), "api", "deploy")
)
make_interval start, end

Record maintenance windows as an Interval dataset. parse_isotime cells give start and end the timestamp type, and make_interval uses them as valid-from and valid-to.

Before values(), a short list of windows had to be ingested as data or built with the parse_json and flatten_single workaround from example 0.

<- values(
    "host", "team", "env",
    tuple("web-1", "frontend", "prod"),
    tuple("web-2", "frontend", "staging"),
    tuple("db-1", "data", "prod")
)
make_col valid_from:parse_isotime("2026-01-01T00:00:00Z")
make_event valid_from
make_resource team, env, primary_key(host)

Build a small inventory as a Resource dataset keyed by host. make_resource needs an Event dataset, so make_event comes first. The primary key makes the result usable as a link target from other datasets.

<- values(
    "client_ip", "latency",
    tuple(ipv4("10.0.0.7"), 120ms),
    tuple(ipv4("10.1.4.2"), 2s),
    tuple(ipv4("192.168.1.9"), duration_null())
)
@sites <- values("network", "site", tuple("10.0.0.0/16", "us-west"), tuple("10.1.0.0/16", "eu-west"))
lookup on(ipv4_address_in_network(client_ip, @sites.network)), site:@sites.site

Map client addresses to sites by network. ipv4(...) cells type client_ip as ipv4, duration literals such as 120ms type latency as duration, and duration_null() is a typed null in that column. 10.0.0.7 maps to us-west and 10.1.4.2 to eu-west. 192.168.1.9 is in neither network, so its site is null.

Before values(), each network was another ipv4_address_in_network branch in a case expression.

<- values(
    "region", "service", "errors",
    tuple("us-west", "api", 12),
    tuple("eu-west", "api", 3),
    tuple("eu-west", "db", 8)
)
@owners <- values(
    "region", "service", "team",
    tuple("us-west", "api", "platform"),
    tuple("eu-west", "api", "eu-platform"),
    tuple("eu-west", "db", "data")
)
lookup on(region=@owners.region and service=@owners.service), team:@owners.team

Match on two columns together. api belongs to platform in us-west and to eu-platform in eu-west, which a lookup on service alone cannot express. Both equalities have to hold for a row to receive team.

Before values(), each region-and-service combination required another branch in a case expression or a separately uploaded reference dataset.

@countries <- values("code", "name", tuple("US", "United States"), tuple("JP", "Japan"))
@tiers <- values("id", "label", tuple(1, "free"), tuple(2, "paid"))
lookup on(country_code=@countries.code), country:@countries.name
lookup on(tier_id=@tiers.id), tier:@tiers.label

Two bindings, two lookups. Before values(), each small mapping needed a repeated case expression or a persistent reference dataset. Here, each values() call is its own reference table.

<- values(
    "service", "latency_ms",
    tuple("api", 42),
    tuple("api", 180),
    tuple("db", 7),
    tuple("web", 950),
    tuple("web", 2400)
)
@bands <- values(
    "low", "high", "label",
    tuple(0, 100, "fast"),
    tuple(100, 1000, "ok"),
    tuple(1000, 9223372036854775807, "slow")
)
lookup on(latency_ms >= @bands.low and latency_ms < @bands.high), band:@bands.label

Put each row in a range bucket. 42 and 7 are fast, 180 and 950 are ok, and 2400 is slow. Each band is a row with a lower and an upper bound. The lookup uses >= and <, so each latency falls in at most one band when the bounds do not overlap: 100 is ok, not both. The last band's upper bound is the largest int64, so it has no ceiling.

Before values(), latency bands were commonly encoded as a case(latency_ms < 100, "fast", latency_ms < 1000, "ok", true, "slow") expression, which depends on the order of its branches and is repeated in every query.

<- values(
    "service", "latency_ms",
    tuple("api", 120),
    tuple("api", 400),
    tuple("db", 30),
    tuple("db", 75),
    tuple("web", 5000)
)
@limits <- values("service", "max_ms", tuple("api", 250), tuple("db", 50))
lookup on(service=@limits.service), max_ms:@limits.max_ms
filter latency_ms > max_ms

Attach a per-service limit, then keep the rows that exceed it. The result is api at 400 and db at 75. web has no limit in the table, so its max_ms is null and the comparison drops it, even at 5000.

Before values(), different limits usually meant a case expression in the query or a separate monitor rule for each service.

<- values(
    "service", "requests",
    tuple("api", 900),
    tuple("web", 450),
    tuple("batch", 30),
    tuple("debug", 5)
)
@allow <- values("service", "owner", tuple("api", "platform"), tuple("web", "frontend"))
lookup on(service=@allow.service), owner:@allow.owner
filter not is_null(owner)

Keep the rows on an allow list and attach an attribute to them. The result is api owned by platform and web owned by frontend. lookup fills owner only on a match, so filter not is_null(owner) drops batch and debug.

Attach a column other than the key: attaching @allow.service itself returns the input's own service value on every row, so the filter would keep every row.

Before values(), this allow list was a filter service = "api" or service = "web" expression, which could not carry attributes for the matching services.

<- values(
    "ts_ns", "service", "latency_ms",
    tuple(1730000000000000000, "api", 42),
    tuple(1730000060000000000, "api", 180),
    tuple(1730000120000000000, "db", 7),
    tuple(1730000180000000000, "api", 95)
)
make_col ts:from_nanoseconds(ts_ns)
make_event ts
statsby requests:count(1), p95_ms:percentile(latency_ms, 0.95), group_by(service)

Build test data to try a verb on known rows. values() returns a Table, and make_event turns it into an Event dataset whose valid-from is ts, one minute apart. statsby then counts three api requests and one db request.

<- values("group", "n", tuple("a", 1), tuple("a", 2.5), tuple("b", 3))
statsby total:sum(n), group_by(group)

Mixing int64 and float64 in n widens the column to float64 before sum runs.

<- values("name", "score", "meta", tuple("ada", 1 + 2, parse_json("{"ok":true}")), tuple("alan", int64_null(), parse_json("null")))

A cell may be an expression. 1 + 2 and int64_null() share the score column. parse_json supplies the variant column, including a JSON null.


Did this page help you?