# Update a Timeseries table

This endpoint updates the "defaults" template, the "retention" and "chunk" attributes of the given Timeseries table.

Method Path Operation*
PATCH /account/services/timeseries/{timeseries} update_timeseries_table

*

In order for a user to perform the "update_timeseries_table" operation, the "update_timeseries_table" permission must be included in the list of allowed actions in the statement of the user's role.

# Request

Parameter Type In Description
timeseries
required
string path Name of the Timeseries table. It must be unique in the context of an Account and must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,63}$.
defaults
optional *
dictionary body
Dictionary containing templates for "measurement" (to determine the name of the measurement column to store the Entry value) and "dimensions" (to determine the value for each of the dimensions). Provided default templates are used if no default templates are defined in the "timeseries" property of a Ledger's Entry. The templates follow the Python string format() convention (see Format String Syntax (opens new window)).
Attribute Type In Description
measurement string body Template that determines the name of the measurement column to store the Entry value. Provided default template is used if no default template is defined in the "timeseries" property of a Ledger's Entry. The template follows the Python string format() convention (see Format String Syntax (opens new window)).
dimensions dictionary body Template that determines the value for each of the dimensions. Provided default template is used if no default template is defined in the "timeseries" property of a Ledger's Entry. The template follows the Python string format() convention (see Format String Syntax (opens new window)).
timestamp string Template that determines the value of the timestamp.
retention
optional *
string body Time for which the data is to be stored. It must match the regular expression (opens new window) ^([1-9][0-9]{0,2}[DWMY])|(INF)$.
chunk
optional *
string body Chunk length. It must match the regular expression (opens new window) ^([1-9][0-9]{0,2}[DWMY])|(INF)$.
measurements
optional **
dictionary body
Dictionary containing a list of measurement column names and a list of data types of the corresponding measurement columns. You can add a new measurement or update the name of an exiting measurement. Please note that the entire measurements dictionary must be included in the request body when adding new measurements or updating the name of an existing measurement as the new measurements content will replace the old content. When adding a new measurement, add a new measurement after the existing one(s) and a data type for this measurement to the "types" list.. When updating a measurement, add a list containing the old and the new measurement (e.g. ["ozone", "ozone_new"])
Attribute Type Description
names list of strings Name(s) of the measurement column(s). Each of the names must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,63}$.
types list of string, value is "int", "bigint", "smallint", "integer", "numeric", "double precision", "json", "jsonb", "bool", "boolean", "character varying", "varchar", "text", "date", "time", "interval", "timestamp", "timestamptz", or "uuid". Data types of the corresponding measurement columns.
dimensions
optional ***
dictionary body
Dictionary containing a list of dimension names and a list of data types of the corresponding dimensions. You can add a new dimension or update the name of an exiting dimension. Please note that the entire dimensions dictionary must be included in the request body when adding new dimensions or updating the name of an existing dimension as the new dimensions content will replace the old content. When adding a new dimension, add a new dimension after the existing one(s) and a data type for this dimension to the "types" list. When updating a dimension, add a list containing the old and the new dimension (e.g. ["city", "region"]) .
Attribute Type Description
names list of strings Name(s) of the dimension(s). Each of the names must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,63}$.
types list of string, value is "int", "bigint", "smallint", "integer", "numeric", "double precision", "json", "jsonb", "bool", "boolean", "character varying", "varchar", "text", "date", "time", "interval", "timestamp", "timestamptz", or "uuid". Data types of the corresponding dimensions.

*

Any optional parameters not provided in the request will be left unchanged. Any optional parameters provided in the request will replace current parameters.

**

If the "measurements" dictionary with attributes is provided in the request body, the "measurements" dictionary from the request body will replace the current "measurements" dictionary.

If no attributes are provided in the request body of "measurements" ("measurements": {}), or if "measurements" with the value null is provided in the request body, the response will return an error, because "measurements" columns cannot be removed.
If the request body does not contain "measurements", no changes will be made to the "measurements" field.

**

If the "dimensions" dictionary with attributes is provided in the request body, the "dimensions" dictionary from the request body will replace the current "dimensions" dictionary.

If no attributes are provided in the request body of "dimensions" ("dimensions": {}), or if "dimensions" with the value null is provided in the request body, the response will return an error, because "dimensions" columns cannot be removed.
If the request body does not contain "dimensions", no changes will be made to the "dimensions" field.

In our example, we send a request to update the "defaults" so that the dimension value of the "dimension" "city" defaults to "Gdańsk" if not provided, we set the "retention" to 3 months ("retention":"3M") and the "chunk" to 1 week ("chunk":"1W").

# Response

Attribute Type Description
stats dictionary
Timeseries table stats.
Attribute Type Description
table_size integer Size of the Timeseries table in bytes.
index_size integer Size of all indexes attached to the Timeseries table in bytes.
toast_size integer TOAST size in bytes.
total_size integer Total size in bytes.
dimensions dictionary
Dictionary containing a list of dimension names and a list of data types of the corresponding dimensions.
Attribute Type Description
names list of strings Name(s) of the dimension(s). Each of the names must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,63}$.
types list of string, value is "int", "bigint", "smallint", "integer", "numeric", "double precision", "json", "jsonb", "bool", "boolean", "character varying", "varchar", "text", "date", "time", "interval", "timestamp", "timestamptz", or "uuid". Data types of the corresponding dimensions.
measurements dictionary
Dictionary containing a list of measurement column names and a list of data types of the corresponding measurement columns.
Attribute Type Description
names list of strings Name(s) of the measurement column(s). Each of the names must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,63}$.
types list of string, value is "int", "bigint", "smallint", "integer", "numeric", "double precision", "json", "jsonb", "bool", "boolean", "character varying", "varchar", "text", "date", "time", "interval", "timestamp", "timestamptz", or "uuid". Data types of the corresponding measurement columns.
defaults dictionary
Dictionary containing templates for "measurement" (to determine the name of the measurement column to store the Entry value) and "dimensions" (to determine the value for each of the dimensions). Provided default templates are used if no default templates are defined in the "timeseries" property of a Ledger's Entry. The templates follow the Python string format() convention (see Format String Syntax (opens new window)).
Attribute Type Description
measurement string Template that determines the name of the measurement column to store the Entry value. Provided default template is used if no default template is defined in the "timeseries" property of a Ledger's Entry. The template follows the Python string format() convention (see Format String Syntax (opens new window)).
dimensions dictionary Template that determines the value for each of the dimensions. Provided default template is used if no default template is defined in the "timeseries" property of a Ledger's Entry. The template follows the Python string format() convention (see Format String Syntax (opens new window)).
timestamp string Template that determines the value of the timestamp.
retention string Time for which the data is to be stored. It must match the regular expression (opens new window) ^([1-9][0-9]{0,2}[DWMY])|(INF)$.
chunk string Chunk length. It must match the regular expression (opens new window) ^([1-9][0-9]{0,2}[DWMY])|(INF)$.

# Status codes

Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status Codes section.