# Create Timeseries table

This endpoint creates one or more Timeseries tables.

Method Path Operation*
POST /account/services/timeseries create_timeseries_table

*

In order for a user to perform the "create_timeseries_table" operation, the "create_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
dimensions
required		 dictionary body
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 strings, value is "bigint", "bool", "boolean", "character varying", "date", "double precision", "geography", "geometry", "int", "integer", "interval", "numeric", "real", "smallint", "text", "time", "timestamp", "timestamptz", "varchar", or "uuid". Data types of the corresponding dimensions.
measurements
required		 dictionary body
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 strings, value is "bigint", "bool", "boolean", "character varying", "date", "double precision", "geography", "geometry", "int", "integer", "interval", "json", "jsonb", "numeric", "real", "smallint", "text", "time", "timestamp", "timestamptz", "varchar", or "uuid". Data types of the corresponding measurement columns.
defaults
optional *		 dictionary, DEFAULT=null 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 str.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 str.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 str.format() convention (see Format String Syntax(opens new window)).
timestamp string Template that determines the value of the timestamp.
retention
optional *		 string, DEFAULT=null 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, DEFAULT=null body Chunk length. It must match the regular expression(opens new window) ^([1-9][0-9]{0,2}[DWMY])|(INF)$.
database
optional *		 string, DEFAULT="default" body Database UUID of the database where the Timeseries table should be created. If not provided, the Timeseries table will be created in the default database.

*

The "defaults", "retention", "chunk", and "database" parameters are optional and do not need to be included in the request body when creating Timeseries tables. If they are not included in the request body, their default values are used.

TIP

The Trusted Twin platform provides you with the flexibility to use the double asterisk ** to unpack a dictionary passed as a value of the "value" attribute of a Ledger Entry.

# Response

The response returns a list of Timeseries tables with their attributes.

Attribute Type Description
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 s value is "bigint", "bool", "boolean", "character varying", "date", "double precision", "geography", "geometry", "int", "integer", "interval", "numeric", "real", "smallint", "text", "time", "timestamp", "timestamptz", "varchar", 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 strings, value is "bigint", "bool", "boolean", "character varying", "date", "double precision", "geography", "geometry", "int", "integer", "interval", "json", "jsonb", "numeric", "real", "smallint", "text", "time", "timestamp", "timestamptz", "varchar", 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 str.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 str.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 str.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)$.
database string Database UUID.

# Response ('Table already exists')

NOTE

If you try to create a Timeseries table that already exists, you will receive the message "error": "Table already exists." for this table in the response. However, the response itself will return the 201 Created status code (see example below).

In our example, we send a request to create two Timeseries tables:

  • "water_pollution": A Timeseries table with the name "water_pollution" does not exists in the account yet.
  • "air_quality_index": A Timeseries table with the name "air_quality_index" already exists in the account.

The response returns the details of the Timeseries table "water_polution" and the message "error": "Table already exists." for the Timeseries table "air_quality_index".

# Status codes

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

Status code Message Comment
201 Created If a Timeseries table that you are trying to create already exists, you will receive the error: "error": "Table already exists." for this table in the response.

← Get Timeseries table →

Was this article helpful?