awswrangler.timestream.write

awswrangler.timestream.write(df: DataFrame, database: str, table: str, time_col: str | None = None, measure_col: str | List[str | None] | None = None, dimensions_cols: List[str | None] | None = None, version: int = 1, num_threads: int = 32, measure_name: str | None = None, common_attributes: Dict[str, Any] | None = None, boto3_session: Session | None = None) List[Dict[str, str]]

Store a Pandas DataFrame into a Amazon Timestream table.

If the Timestream service rejects a record(s), this function will not throw a Python exception. Instead it will return the rejection information.

Note

Values in common_attributes take precedence over all other arguments and data frame values. Dimension attributes are merged with attributes in record objects. Example: common_attributes = {“Dimensions”: {“Name”: “device_id”, “Value”: “12345”}, “MeasureValueType”: “DOUBLE”}.

Note

If the time_col column is supplied it must be of type timestamp. TimeUnit is set to MILLISECONDS by default.

Parameters:
  • df (pandas.DataFrame) – Pandas DataFrame https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html

  • database (str) – Amazon Timestream database name.

  • table (str) – Amazon Timestream table name.

  • time_col (Optional[str]) – DataFrame column name to be used as time. MUST be a timestamp column.

  • measure_col (Union[str, List[str], None]) – DataFrame column name(s) to be used as measure.

  • dimensions_cols (Optional[List[str]]) – List of DataFrame column names to be used as dimensions.

  • version (int) – Version number used for upserts. Documentation https://docs.aws.amazon.com/timestream/latest/developerguide/API_WriteRecords.html.

  • measure_name (Optional[str]) – Name that represents the data attribute of the time series. Overrides measure_col if specified.

  • common_attributes (Optional[Dict[str, Any]]) – Dictionary of attributes that is shared across all records in the request. Using common attributes can optimize the cost of writes by reducing the size of request payloads.

  • num_threads (str) – Number of thread to be used for concurrent writing.

  • boto3_session (boto3.Session(), optional) – Boto3 Session. The default boto3 Session will be used if boto3_session receive None.

Returns:

Rejected records. Possible reasons for rejection are described here: https://docs.aws.amazon.com/timestream/latest/developerguide/API_RejectedRecord.html

Return type:

List[Dict[str, str]]

Examples

Store a Pandas DataFrame into a Amazon Timestream table.

>>> import awswrangler as wr
>>> import pandas as pd
>>> df = pd.DataFrame(
>>>     {
>>>         "time": [datetime.now(), datetime.now(), datetime.now()],
>>>         "dim0": ["foo", "boo", "bar"],
>>>         "dim1": [1, 2, 3],
>>>         "measure": [1.0, 1.1, 1.2],
>>>     }
>>> )
>>> rejected_records = wr.timestream.write(
>>>     df=df,
>>>     database="sampleDB",
>>>     table="sampleTable",
>>>     time_col="time",
>>>     measure_col="measure",
>>>     dimensions_cols=["dim0", "dim1"],
>>> )
>>> assert len(rejected_records) == 0

Return value if some records are rejected.

>>> [
>>>     {
>>>         'ExistingVersion': 2,
>>>         'Reason': 'The record version 1 is lower than the existing version 2. A '
>>>                   'higher version is required to update the measure value.',
>>>         'RecordIndex': 0
>>>     }
>>> ]