> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# /aggregate/unpivot

```
URL: http://<db.host>:<db.port>/aggregate/unpivot
```

Rotate the column values into rows values.

For unpivot details and examples, see [Unpivot](../../concepts/unpivot/).
For limitations, see
[Unpivot Limitations](../../concepts/unpivot/#limitations).

Unpivot is used to normalize tables that are built for cross tabular reporting
purposes. The unpivot operator rotates the column values for all the pivoted
columns. A variable column, value column and all columns from the source table
except the unpivot columns are projected into the result table. The variable
column and value columns in the result table indicate the pivoted column name
and values respectively.

The response is returned as a dynamic schema. For details see:
[dynamic schemas documentation](../../api/concepts/#dynamic-schemas).

## Input Parameter Description

<ParamField body="table_name" type="string">
  Name of the table on which the operation will be performed. Must be an existing table/view, in \[schema\_name.]table\_name format, using standard [name resolution rules](../../concepts/tables/#table-name-resolution).
</ParamField>

<ParamField body="column_names" type="array of strings">
  List of column names or expressions. A wildcard '\*' can be used to include all the non-pivoted columns from the source table.
</ParamField>

<ParamField body="variable_column_name" type="string">
  Specifies the variable/parameter column name.

  The default value is ''.
</ParamField>

<ParamField body="value_column_name" type="string">
  Specifies the value column name.

  The default value is ''.
</ParamField>

<ParamField body="pivoted_columns" type="array of strings">
  List of one or more values typically the column names of the input table. All the columns in the source table must have the same data type.
</ParamField>

<ParamField body="encoding" type="string">
  Specifies the encoding for returned records.

  The default value is `binary`.

  * **binary**: Indicates that the returned records should be binary encoded.
  * **json**: Indicates that the returned records should be JSON-encoded.
</ParamField>

<ParamField body="options" type="map of string to strings">
  Optional parameters.

  The default value is an empty map ( \{} ).

  <Expandable title="options">
    <ParamField body="create_temp_table">
      If *true*, a unique temporary table name will be generated in the sys\_temp schema and used in place of *result\_table*. If *result\_table\_persist* is *false* (or unspecified), then this is always allowed even if the caller does not have permission to create tables. The generated name is returned in *qualified\_result\_table\_name*.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="collection_name">
      \[DEPRECATED--please specify the containing schema as part of *result\_table* and use [/create/schema](/content/api/rest/create_schema_rest) to create the schema if non-existent] Name of a schema which is to contain the table specified in *result\_table*. If the schema is non-existent, it will be automatically created.
    </ParamField>

    <ParamField body="result_table">
      The name of a table used to store the results, in \[schema\_name.]table\_name format, using standard [name resolution rules](../../concepts/tables/#table-name-resolution) and meeting [table naming criteria](../../concepts/tables/#table-naming-criteria). If present, no results are returned in the response.
    </ParamField>

    <ParamField body="result_table_persist">
      If *true*, then the result table specified in *result\_table* will be persisted and will not expire unless a *ttl* is specified.   If *false*, then the result table will be an in-memory table and will expire unless a *ttl* is specified otherwise.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="expression">
      Filter expression to apply to the table prior to unpivot processing.
    </ParamField>

    <ParamField body="order_by">
      Comma-separated list of the columns to be sorted by; e.g. 'timestamp asc, x desc'.  The columns specified must be present in input table.  If any alias is given for any column name, the alias must be used, rather than the original column name.

      The default value is ''.
    </ParamField>

    <ParamField body="chunk_size">
      Indicates the number of records per chunk to be used for the result table. Must be used in combination with the *result\_table* option.
    </ParamField>

    <ParamField body="chunk_column_max_memory">
      Indicates the target maximum data size for each column in a chunk to be used for the result table. Must be used in combination with the *result\_table* option.
    </ParamField>

    <ParamField body="chunk_max_memory">
      Indicates the target maximum data size for all columns in a chunk to be used for the result table. Must be used in combination with the *result\_table* option.
    </ParamField>

    <ParamField body="compression_codec">
      The default [compression codec](../../concepts/column_compression/) for the result table's columns.
    </ParamField>

    <ParamField body="limit">
      The number of records to keep.

      The default value is ''.
    </ParamField>

    <ParamField body="ttl">
      Sets the [TTL](../../concepts/ttl/) of the table specified in *result\_table*.
    </ParamField>

    <ParamField body="view_id">
      View this result table is part of.

      The default value is ''.
    </ParamField>

    <ParamField body="create_indexes">
      Comma-separated list of columns on which to create indexes on the table specified in *result\_table*. The columns specified must be present in output column names. If any alias is given for any column name, the alias must be used, rather than the original column name.
    </ParamField>

    <ParamField body="result_table_force_replicated">
      Force the result table to be replicated (ignores any sharding). Must be used in combination with the *result\_table* option.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>
  </Expandable>
</ParamField>

## Output Parameter Description

The Kinetica server embeds the endpoint response inside a standard response structure which contains status information and the actual response to the query.  Here is a description of the various fields of the wrapper:

<ResponseField name="status" type="String">
  'OK' or 'ERROR'
</ResponseField>

<ResponseField name="message" type="String">
  Empty if success or an error message
</ResponseField>

<ResponseField name="data_type" type="String">
  'aggregate\_unpivot\_response' or 'none' in case of an error
</ResponseField>

<ResponseField name="data" type="String">
  Empty string
</ResponseField>

<ResponseField name="data_str" type="JSON or String">
  This embedded JSON represents the result of the /aggregate/unpivot endpoint:

  <Expandable title="data_str">
    <ResponseField name="table_name" type="string">
      Typically shows the result-table name if provided in the request (Ignore otherwise).
    </ResponseField>

    <ResponseField name="response_schema_str" type="string">
      Avro schema of output parameter *binary\_encoded\_response* or output parameter *json\_encoded\_response*.
    </ResponseField>

    <ResponseField name="binary_encoded_response" type="bytes">
      Avro binary encoded response.
    </ResponseField>

    <ResponseField name="json_encoded_response" type="string">
      Avro JSON encoded response.
    </ResponseField>

    <ResponseField name="total_number_of_records" type="long">
      Total/Filtered number of records.
    </ResponseField>

    <ResponseField name="has_more_records" type="boolean">
      Too many records. Returned a partial set.
    </ResponseField>

    <ResponseField name="info" type="map of string to strings">
      Additional information.

      The default value is an empty map ( \{} ).

      <Expandable title="info">
        <ResponseField name="qualified_result_table_name">
          The fully qualified name of the table (i.e. including the schema) used to store the results.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  Empty string in case of an error.
</ResponseField>