--- title: pivot() function description: The `pivot()` function collects values stored vertically (column-wise) in a table and aligns them horizontally (row-wise) into logical sets. aliases: - /v2.0/reference/flux/functions/transformations/pivot menu: v2_0_ref: name: pivot parent: built-in-transformations weight: 401 --- The `pivot()` function collects values stored vertically (column-wise) in a table and aligns them horizontally (row-wise) into logical sets. _**Function type:** Transformation_ _**Output data type:** Object_ ```js pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") ``` The group key of the resulting table is the same as the input tables, excluding columns found in the [`columnKey`](#columnkey) and [`valueColumn`](#valuecolumn) parameters. This is because these columns are not part of the resulting output table. Every input row should have a 1:1 mapping to a particular row + column in the output table, determined by its values for the [`rowKey`](#rowkey) and [`columnKey`](#columnkey) parameters. In cases where more than one value is identified for the same row + column pair, the last value encountered in the set of table rows is used as the result. Every input row should have a 1:1 mapping to a particular row/column pair in the output table, determined by its values for the `rowKey` and `columnKey`. In cases where more than one value is identified for the same row/column pair in the output, the last value encountered in the set of table rows is used as the result. The output is constructed as follows: - The set of columns for the new table is the `rowKey` unioned with the group key, but excluding the columns indicated by the `columnKey` and the `valueColumn`. - A new column is added to the set of columns for each unique value identified in the input by the `columnKey` parameter. - The label of a new column is the concatenation of the values of `columnKey` using `_` as a separator. If the value is `null`, `"null"` is used. - A new row is created for each unique value identified in the input by the `rowKey` parameter. - For each new row, values for group key columns stay the same, while values for new columns are determined from the input tables by the value in `valueColumn` at the row identified by the `rowKey` values and the new column's label. If no value is found, the value is set to `null`. ## Parameters ### rowKey List of columns used to uniquely identify a row for the output. _**Data type:** Array of strings_ ### columnKey List of columns used to pivot values onto each row identified by the rowKey. _**Data type:** Array of strings_ ### valueColumn The single column that contains the value to be moved around the pivot. _**Data type:** String_ ## Examples ### Align fields within each measurement that have the same timestamp ```js from(bucket:"test") |> range(start: 1970-01-01T00:00:00.000000000Z) |> pivot( rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value" ) ``` ###### Input | _time | _value | _measurement | _field | |:------------------------------:|:------:|:------------:|:------:| | 1970-01-01T00:00:00.000000001Z | 1.0 | "m1" | "f1" | | 1970-01-01T00:00:00.000000001Z | 2.0 | "m1" | "f2" | | 1970-01-01T00:00:00.000000001Z | null | "m1" | "f3" | | 1970-01-01T00:00:00.000000001Z | 3.0 | "m1" | null | | 1970-01-01T00:00:00.000000002Z | 4.0 | "m1" | "f1" | | 1970-01-01T00:00:00.000000002Z | 5.0 | "m1" | "f2" | | null | 6.0 | "m1" | "f2" | | 1970-01-01T00:00:00.000000002Z | null | "m1" | "f3" | | 1970-01-01T00:00:00.000000003Z | null | "m1" | "f1" | | 1970-01-01T00:00:00.000000003Z | 7.0 | "m1" | null | | 1970-01-01T00:00:00.000000004Z | 8.0 | "m1" | "f3" | ###### Output | _time | _measurement | f1 | f2 | f3 | null | |:------------------------------:|:------------:|:----:|:----:|:----:|:----:| | 1970-01-01T00:00:00.000000001Z | "m1" | 1.0 | 2.0 | null | 3.0 | | 1970-01-01T00:00:00.000000002Z | "m1" | 4.0 | 5.0 | null | null | | null | "m1" | null | 6.0 | null | null | | 1970-01-01T00:00:00.000000003Z | "m1" | null | null | null | 7.0 | | 1970-01-01T00:00:00.000000004Z | "m1" | null | null | 8.0 | null | ### Align fields and measurements that have the same timestamp {{% note %}} Note the effects of: - Having null values in some `columnKey` value; - Having more values for the same `rowKey` and `columnKey` value (the 11th row overrides the 10th, and so does the 15th with the 14th). {{% /note %}} ```js from(bucket:"test") |> range(start: 1970-01-01T00:00:00.000000000Z) |> pivot( rowKey:["_time"], columnKey: ["_measurement", "_field"], valueColumn: "_value" ) ``` ###### Input | _time | _value | _measurement | _field | |:------------------------------:|:------:|:------------:|:------:| | 1970-01-01T00:00:00.000000001Z | 1.0 | "m1" | "f1" | | 1970-01-01T00:00:00.000000001Z | 2.0 | "m1" | "f2" | | 1970-01-01T00:00:00.000000001Z | 3.0 | null | "f3" | | 1970-01-01T00:00:00.000000001Z | 4.0 | null | null | | 1970-01-01T00:00:00.000000002Z | 5.0 | "m1" | "f1" | | 1970-01-01T00:00:00.000000002Z | 6.0 | "m1" | "f2" | | 1970-01-01T00:00:00.000000002Z | 7.0 | "m1" | "f3" | | 1970-01-01T00:00:00.000000002Z | 8.0 | null | null | | null | 9.0 | "m1" | "f3" | | 1970-01-01T00:00:00.000000003Z | 10.0 | "m1" | null | | 1970-01-01T00:00:00.000000003Z | 11.0 | "m1" | null | | 1970-01-01T00:00:00.000000003Z | 12.0 | "m1" | "f3" | | 1970-01-01T00:00:00.000000003Z | 13.0 | null | null | | null | 14.0 | "m1" | null | | null | 15.0 | "m1" | null | ###### Output | _time | m1_f1 | m1_f2 | null_f3 | null_null | m1_f3 | m1_null | |:------------------------------:|:-----:|:-----:|:---------:|:---------:|:-----:|:-------:| | 1970-01-01T00:00:00.000000001Z | 1.0 | 2.0 | 3.0 | 4.0 | null | null | | 1970-01-01T00:00:00.000000002Z | 5.0 | 6.0 | null | 8.0 | 7.0 | null | | null | null | null | null | null | 9.0 | 15.0 | | 1970-01-01T00:00:00.000000003Z | null | null | null | 13.0 | 12.0 | 11.0 |