AWS SDK for PHP 3.x

Client: Aws\TimestreamWrite\TimestreamWriteClient

Service ID: timestream-write

Version: 2018-11-01

This page describes the parameters and results for the operations of the Amazon Timestream Write (2018-11-01), and shows how to use the Aws\TimestreamWrite\TimestreamWriteClient object to call the described operations. This documentation is specific to the 2018-11-01 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

CreateDatabase ( array $params = [] )
Creates a new Timestream database.
CreateTable ( array $params = [] )
The CreateTable operation adds a new table to an existing database in your account.
DeleteDatabase ( array $params = [] )
Deletes a given Timestream database.
DeleteTable ( array $params = [] )
Deletes a given Timestream table.
DescribeDatabase ( array $params = [] )
Returns information about the database, including the database name, time that the database was created, and the total number of tables found within the database.
DescribeEndpoints ( array $params = [] )
DescribeEndpoints returns a list of available endpoints to make Timestream API calls against.
DescribeTable ( array $params = [] )
Returns information about the table, including the table name, database name, retention duration of the memory store and the magnetic store.
ListDatabases ( array $params = [] )
Returns a list of your Timestream databases.
ListTables ( array $params = [] )
A list of tables, along with the name, status and retention properties of each table.
ListTagsForResource ( array $params = [] )
List all tags on a Timestream resource.
TagResource ( array $params = [] )
Associate a set of tags with a Timestream resource.
UntagResource ( array $params = [] )
Removes the association of tags from a Timestream resource.
UpdateDatabase ( array $params = [] )
Modifies the KMS key for an existing database.
UpdateTable ( array $params = [] )
Modifies the retention duration of the memory store and magnetic store for your Timestream table.
WriteRecords ( array $params = [] )
The WriteRecords operation enables you to write your time series data into Timestream.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

ListDatabases
ListTables

Operations

CreateDatabase

$result = $client->createDatabase([/* ... */]);
$promise = $client->createDatabaseAsync([/* ... */]);

Creates a new Timestream database. If the KMS key is not specified, the database will be encrypted with a Timestream managed KMS key located in your account. Refer to Amazon Web Services managed KMS keys for more info. Service quotas apply. See code sample for details.

Parameter Syntax

$result = $client->createDatabase([
    'DatabaseName' => '<string>', // REQUIRED
    'KmsKeyId' => '<string>',
    'Tags' => [
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members

DatabaseName

Required: Yes
Type: string

The name of the Timestream database.

KmsKeyId

Type: string

The KMS key for the database. If the KMS key is not specified, the database will be encrypted with a Timestream managed KMS key located in your account. Refer to Amazon Web Services managed KMS keys for more info.

Tags

Type: Array of Tag structures

A list of key-value pairs to label the table.

Result Syntax

[
    'Database' => [
        'Arn' => '<string>',
        'CreationTime' => <DateTime>,
        'DatabaseName' => '<string>',
        'KmsKeyId' => '<string>',
        'LastUpdatedTime' => <DateTime>,
        'TableCount' => <integer>,
    ],
]

Result Details

Members

Database

Type: Database structure

The newly created Timestream database.

Errors

ConflictException:
Timestream was unable to process this request because it contains resource that already exists.
ValidationException:
Invalid or malformed request.
AccessDeniedException:
You are not authorized to perform this action.
ServiceQuotaExceededException:
Instance quota of resource exceeded for this account.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
InvalidEndpointException:
The requested endpoint was invalid.
InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
InvalidEndpointException:
The requested endpoint was invalid.

CreateTable

$result = $client->createTable([/* ... */]);
$promise = $client->createTableAsync([/* ... */]);

The CreateTable operation adds a new table to an existing database in your account. In an Amazon Web Services account, table names must be at least unique within each Region if they are in the same database. You may have identical table names in the same Region if the tables are in separate databases. While creating the table, you must specify the table name, database name, and the retention properties. Service quotas apply. See code sample for details.

Parameter Syntax

$result = $client->createTable([
    'DatabaseName' => '<string>', // REQUIRED
    'MagneticStoreWriteProperties' => [
        'EnableMagneticStoreWrites' => true || false, // REQUIRED
        'MagneticStoreRejectedDataLocation' => [
            'S3Configuration' => [
                'BucketName' => '<string>',
                'EncryptionOption' => 'SSE_S3|SSE_KMS',
                'KmsKeyId' => '<string>',
                'ObjectKeyPrefix' => '<string>',
            ],
        ],
    ],
    'RetentionProperties' => [
        'MagneticStoreRetentionPeriodInDays' => <integer>, // REQUIRED
        'MemoryStoreRetentionPeriodInHours' => <integer>, // REQUIRED
    ],
    'TableName' => '<string>', // REQUIRED
    'Tags' => [
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members

DatabaseName

Required: Yes
Type: string

The name of the Timestream database.

MagneticStoreWriteProperties

Type: MagneticStoreWriteProperties structure

Contains properties to set on the table when enabling magnetic store writes.

RetentionProperties

Type: RetentionProperties structure

The duration for which your time series data must be stored in the memory store and the magnetic store.

TableName

Required: Yes
Type: string

The name of the Timestream table.

Tags

Type: Array of Tag structures

A list of key-value pairs to label the table.

Result Syntax

[
    'Table' => [
        'Arn' => '<string>',
        'CreationTime' => <DateTime>,
        'DatabaseName' => '<string>',
        'LastUpdatedTime' => <DateTime>,
        'MagneticStoreWriteProperties' => [
            'EnableMagneticStoreWrites' => true || false,
            'MagneticStoreRejectedDataLocation' => [
                'S3Configuration' => [
                    'BucketName' => '<string>',
                    'EncryptionOption' => 'SSE_S3|SSE_KMS',
                    'KmsKeyId' => '<string>',
                    'ObjectKeyPrefix' => '<string>',
                ],
            ],
        ],
        'RetentionProperties' => [
            'MagneticStoreRetentionPeriodInDays' => <integer>,
            'MemoryStoreRetentionPeriodInHours' => <integer>,
        ],
        'TableName' => '<string>',
        'TableStatus' => 'ACTIVE|DELETING',
    ],
]

Result Details

Members

Table

Type: Table structure

The newly created Timestream table.

Errors

ConflictException:
Timestream was unable to process this request because it contains resource that already exists.
ValidationException:
Invalid or malformed request.
AccessDeniedException:
You are not authorized to perform this action.
ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
ServiceQuotaExceededException:
Instance quota of resource exceeded for this account.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
InvalidEndpointException:
The requested endpoint was invalid.
InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
InvalidEndpointException:
The requested endpoint was invalid.

DeleteDatabase

$result = $client->deleteDatabase([/* ... */]);
$promise = $client->deleteDatabaseAsync([/* ... */]);

Deletes a given Timestream database. This is an irreversible operation. After a database is deleted, the time series data from its tables cannot be recovered.

All tables in the database must be deleted first, or a ValidationException error will be thrown.

Due to the nature of distributed retries, the operation can return either success or a ResourceNotFoundException. Clients should consider them equivalent.

See code sample for details.

Parameter Syntax

$result = $client->deleteDatabase([
    'DatabaseName' => '<string>', // REQUIRED
]);

Parameter Details

Members

DatabaseName

Required: Yes
Type: string

The name of the Timestream database to be deleted.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
ValidationException:
Invalid or malformed request.
AccessDeniedException:
You are not authorized to perform this action.
InvalidEndpointException:
The requested endpoint was invalid.

DeleteTable

$result = $client->deleteTable([/* ... */]);
$promise = $client->deleteTableAsync([/* ... */]);

Deletes a given Timestream table. This is an irreversible operation. After a Timestream database table is deleted, the time series data stored in the table cannot be recovered.

Due to the nature of distributed retries, the operation can return either success or a ResourceNotFoundException. Clients should consider them equivalent.

See code sample for details.

Parameter Syntax

$result = $client->deleteTable([
    'DatabaseName' => '<string>', // REQUIRED
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members

DatabaseName

Required: Yes
Type: string

The name of the database where the Timestream database is to be deleted.

TableName

Required: Yes
Type: string

The name of the Timestream table to be deleted.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
ValidationException:
Invalid or malformed request.
ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
AccessDeniedException:
You are not authorized to perform this action.
InvalidEndpointException:
The requested endpoint was invalid.

DescribeDatabase

$result = $client->describeDatabase([/* ... */]);
$promise = $client->describeDatabaseAsync([/* ... */]);

Returns information about the database, including the database name, time that the database was created, and the total number of tables found within the database. Service quotas apply. See code sample for details.

Parameter Syntax

$result = $client->describeDatabase([
    'DatabaseName' => '<string>', // REQUIRED
]);

Parameter Details

Members

DatabaseName

Required: Yes
Type: string

The name of the Timestream database.

Result Syntax

[
    'Database' => [
        'Arn' => '<string>',
        'CreationTime' => <DateTime>,
        'DatabaseName' => '<string>',
        'KmsKeyId' => '<string>',
        'LastUpdatedTime' => <DateTime>,
        'TableCount' => <integer>,
    ],
]

Result Details

Members

Database

Type: Database structure

The name of the Timestream table.

Errors

ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
ValidationException:
Invalid or malformed request.
AccessDeniedException:
You are not authorized to perform this action.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
InvalidEndpointException:
The requested endpoint was invalid.

DescribeEndpoints

$result = $client->describeEndpoints([/* ... */]);
$promise = $client->describeEndpointsAsync([/* ... */]);

DescribeEndpoints returns a list of available endpoints to make Timestream API calls against. This API is available through both Write and Query.

Because the Timestream SDKs are designed to transparently work with the service’s architecture, including the management and mapping of the service endpoints, it is not recommended that you use this API unless:

You are using VPC endpoints (Amazon Web Services PrivateLink) with Timestream
Your application uses a programming language that does not yet have SDK support
You require better control over the client-side implementation

For detailed information on how and when to use and implement DescribeEndpoints, see The Endpoint Discovery Pattern.

Parameter Syntax

$result = $client->describeEndpoints([
]);

Parameter Details

Members

Result Syntax

[
    'Endpoints' => [
        [
            'Address' => '<string>',
            'CachePeriodInMinutes' => <integer>,
        ],
        // ...
    ],
]

Result Details

Members

Endpoints

Required: Yes
Type: Array of Endpoint structures

An Endpoints object is returned when a DescribeEndpoints request is made.

Errors

InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
ValidationException:
Invalid or malformed request.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.

DescribeTable

$result = $client->describeTable([/* ... */]);
$promise = $client->describeTableAsync([/* ... */]);

Returns information about the table, including the table name, database name, retention duration of the memory store and the magnetic store. Service quotas apply. See code sample for details.

Parameter Syntax

$result = $client->describeTable([
    'DatabaseName' => '<string>', // REQUIRED
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members

DatabaseName

Required: Yes
Type: string

The name of the Timestream database.

TableName

Required: Yes
Type: string

The name of the Timestream table.

Result Syntax

[
    'Table' => [
        'Arn' => '<string>',
        'CreationTime' => <DateTime>,
        'DatabaseName' => '<string>',
        'LastUpdatedTime' => <DateTime>,
        'MagneticStoreWriteProperties' => [
            'EnableMagneticStoreWrites' => true || false,
            'MagneticStoreRejectedDataLocation' => [
                'S3Configuration' => [
                    'BucketName' => '<string>',
                    'EncryptionOption' => 'SSE_S3|SSE_KMS',
                    'KmsKeyId' => '<string>',
                    'ObjectKeyPrefix' => '<string>',
                ],
            ],
        ],
        'RetentionProperties' => [
            'MagneticStoreRetentionPeriodInDays' => <integer>,
            'MemoryStoreRetentionPeriodInHours' => <integer>,
        ],
        'TableName' => '<string>',
        'TableStatus' => 'ACTIVE|DELETING',
    ],
]

Result Details

Members

Table

Type: Table structure

The Timestream table.

Errors

ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
ValidationException:
Invalid or malformed request.
AccessDeniedException:
You are not authorized to perform this action.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
InvalidEndpointException:
The requested endpoint was invalid.

ListDatabases

$result = $client->listDatabases([/* ... */]);
$promise = $client->listDatabasesAsync([/* ... */]);

Returns a list of your Timestream databases. Service quotas apply. See code sample for details.

Parameter Syntax

$result = $client->listDatabases([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members

MaxResults

Type: int

The total number of items to return in the output. If the total number of items available is more than the value specified, a NextToken is provided in the output. To resume pagination, provide the NextToken value as argument of a subsequent API invocation.

NextToken

Type: string

The pagination token. To resume pagination, provide the NextToken value as argument of a subsequent API invocation.

Result Syntax

[
    'Databases' => [
        [
            'Arn' => '<string>',
            'CreationTime' => <DateTime>,
            'DatabaseName' => '<string>',
            'KmsKeyId' => '<string>',
            'LastUpdatedTime' => <DateTime>,
            'TableCount' => <integer>,
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members

Databases

Type: Array of Database structures

A list of database names.

NextToken

Type: string

The pagination token. This parameter is returned when the response is truncated.

Errors

InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
ValidationException:
Invalid or malformed request.
AccessDeniedException:
You are not authorized to perform this action.
InvalidEndpointException:
The requested endpoint was invalid.

ListTables

$result = $client->listTables([/* ... */]);
$promise = $client->listTablesAsync([/* ... */]);

A list of tables, along with the name, status and retention properties of each table. See code sample for details.

Parameter Syntax

$result = $client->listTables([
    'DatabaseName' => '<string>',
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members

DatabaseName

Type: string

The name of the Timestream database.

MaxResults

Type: int

NextToken

Type: string

The pagination token. To resume pagination, provide the NextToken value as argument of a subsequent API invocation.

Result Syntax

[
    'NextToken' => '<string>',
    'Tables' => [
        [
            'Arn' => '<string>',
            'CreationTime' => <DateTime>,
            'DatabaseName' => '<string>',
            'LastUpdatedTime' => <DateTime>,
            'MagneticStoreWriteProperties' => [
                'EnableMagneticStoreWrites' => true || false,
                'MagneticStoreRejectedDataLocation' => [
                    'S3Configuration' => [
                        'BucketName' => '<string>',
                        'EncryptionOption' => 'SSE_S3|SSE_KMS',
                        'KmsKeyId' => '<string>',
                        'ObjectKeyPrefix' => '<string>',
                    ],
                ],
            ],
            'RetentionProperties' => [
                'MagneticStoreRetentionPeriodInDays' => <integer>,
                'MemoryStoreRetentionPeriodInHours' => <integer>,
            ],
            'TableName' => '<string>',
            'TableStatus' => 'ACTIVE|DELETING',
        ],
        // ...
    ],
]

Result Details

Members

NextToken

Type: string

A token to specify where to start paginating. This is the NextToken from a previously truncated response.

Tables

Type: Array of Table structures

A list of tables.

Errors

InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
ValidationException:
Invalid or malformed request.
ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
AccessDeniedException:
You are not authorized to perform this action.
InvalidEndpointException:
The requested endpoint was invalid.

ListTagsForResource

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

List all tags on a Timestream resource.

Parameter Syntax

$result = $client->listTagsForResource([
    'ResourceARN' => '<string>', // REQUIRED
]);

Parameter Details

Members

ResourceARN

Required: Yes
Type: string

The Timestream resource with tags to be listed. This value is an Amazon Resource Name (ARN).

Result Syntax

[
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

Tags

Type: Array of Tag structures

The tags currently associated with the Timestream resource.

Errors

ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
ValidationException:
Invalid or malformed request.
InvalidEndpointException:
The requested endpoint was invalid.

TagResource

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Associate a set of tags with a Timestream resource. You can then activate these user-defined tags so that they appear on the Billing and Cost Management console for cost allocation tracking.

Parameter Syntax

$result = $client->tagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'Tags' => [ // REQUIRED
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members

ResourceARN

Required: Yes
Type: string

Identifies the Timestream resource to which tags should be added. This value is an Amazon Resource Name (ARN).

Tags

Required: Yes
Type: Array of Tag structures

The tags to be assigned to the Timestream resource.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
ServiceQuotaExceededException:
Instance quota of resource exceeded for this account.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
ValidationException:
Invalid or malformed request.
InvalidEndpointException:
The requested endpoint was invalid.

UntagResource

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Removes the association of tags from a Timestream resource.

Parameter Syntax

$result = $client->untagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'TagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members

ResourceARN

Required: Yes
Type: string

The Timestream resource that the tags will be removed from. This value is an Amazon Resource Name (ARN).

TagKeys

Required: Yes
Type: Array of strings

A list of tags keys. Existing tags of the resource whose keys are members of this list will be removed from the Timestream resource.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ValidationException:
Invalid or malformed request.
ServiceQuotaExceededException:
Instance quota of resource exceeded for this account.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
InvalidEndpointException:
The requested endpoint was invalid.

UpdateDatabase

$result = $client->updateDatabase([/* ... */]);
$promise = $client->updateDatabaseAsync([/* ... */]);

Modifies the KMS key for an existing database. While updating the database, you must specify the database name and the identifier of the new KMS key to be used (KmsKeyId). If there are any concurrent UpdateDatabase requests, first writer wins.

See code sample for details.

Parameter Syntax

$result = $client->updateDatabase([
    'DatabaseName' => '<string>', // REQUIRED
    'KmsKeyId' => '<string>', // REQUIRED
]);

Parameter Details

Members

DatabaseName

Required: Yes
Type: string

The name of the database.

KmsKeyId

Required: Yes
Type: string

The identifier of the new KMS key (KmsKeyId) to be used to encrypt the data stored in the database. If the KmsKeyId currently registered with the database is the same as the KmsKeyId in the request, there will not be any update.

You can specify the KmsKeyId using any of the following:

Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
Key ARN: arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
Alias name: alias/ExampleAlias
Alias ARN: arn:aws:kms:us-east-1:111122223333:alias/ExampleAlias

Result Syntax

[
    'Database' => [
        'Arn' => '<string>',
        'CreationTime' => <DateTime>,
        'DatabaseName' => '<string>',
        'KmsKeyId' => '<string>',
        'LastUpdatedTime' => <DateTime>,
        'TableCount' => <integer>,
    ],
]

Result Details

Members

Database

Type: Database structure

A top level container for a table. Databases and tables are the fundamental management concepts in Amazon Timestream. All tables in a database are encrypted with the same KMS key.

Errors

ValidationException:
Invalid or malformed request.
AccessDeniedException:
You are not authorized to perform this action.
ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
ServiceQuotaExceededException:
Instance quota of resource exceeded for this account.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
InvalidEndpointException:
The requested endpoint was invalid.

UpdateTable

$result = $client->updateTable([/* ... */]);
$promise = $client->updateTableAsync([/* ... */]);

Modifies the retention duration of the memory store and magnetic store for your Timestream table. Note that the change in retention duration takes effect immediately. For example, if the retention period of the memory store was initially set to 2 hours and then changed to 24 hours, the memory store will be capable of holding 24 hours of data, but will be populated with 24 hours of data 22 hours after this change was made. Timestream does not retrieve data from the magnetic store to populate the memory store.

See code sample for details.

Parameter Syntax

$result = $client->updateTable([
    'DatabaseName' => '<string>', // REQUIRED
    'MagneticStoreWriteProperties' => [
        'EnableMagneticStoreWrites' => true || false, // REQUIRED
        'MagneticStoreRejectedDataLocation' => [
            'S3Configuration' => [
                'BucketName' => '<string>',
                'EncryptionOption' => 'SSE_S3|SSE_KMS',
                'KmsKeyId' => '<string>',
                'ObjectKeyPrefix' => '<string>',
            ],
        ],
    ],
    'RetentionProperties' => [
        'MagneticStoreRetentionPeriodInDays' => <integer>, // REQUIRED
        'MemoryStoreRetentionPeriodInHours' => <integer>, // REQUIRED
    ],
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members

DatabaseName

Required: Yes
Type: string

The name of the Timestream database.

MagneticStoreWriteProperties

Type: MagneticStoreWriteProperties structure

Contains properties to set on the table when enabling magnetic store writes.

RetentionProperties

Type: RetentionProperties structure

The retention duration of the memory store and the magnetic store.

TableName

Required: Yes
Type: string

The name of the Timestream table.

Result Syntax

[
    'Table' => [
        'Arn' => '<string>',
        'CreationTime' => <DateTime>,
        'DatabaseName' => '<string>',
        'LastUpdatedTime' => <DateTime>,
        'MagneticStoreWriteProperties' => [
            'EnableMagneticStoreWrites' => true || false,
            'MagneticStoreRejectedDataLocation' => [
                'S3Configuration' => [
                    'BucketName' => '<string>',
                    'EncryptionOption' => 'SSE_S3|SSE_KMS',
                    'KmsKeyId' => '<string>',
                    'ObjectKeyPrefix' => '<string>',
                ],
            ],
        ],
        'RetentionProperties' => [
            'MagneticStoreRetentionPeriodInDays' => <integer>,
            'MemoryStoreRetentionPeriodInHours' => <integer>,
        ],
        'TableName' => '<string>',
        'TableStatus' => 'ACTIVE|DELETING',
    ],
]

Result Details

Members

Table

Type: Table structure

The updated Timestream table.

Errors

InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
ValidationException:
Invalid or malformed request.
ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
AccessDeniedException:
You are not authorized to perform this action.
InvalidEndpointException:
The requested endpoint was invalid.

WriteRecords

$result = $client->writeRecords([/* ... */]);
$promise = $client->writeRecordsAsync([/* ... */]);

The WriteRecords operation enables you to write your time series data into Timestream. You can specify a single data point or a batch of data points to be inserted into the system. Timestream offers you with a flexible schema that auto detects the column names and data types for your Timestream tables based on the dimension names and data types of the data points you specify when invoking writes into the database. Timestream support eventual consistency read semantics. This means that when you query data immediately after writing a batch of data into Timestream, the query results might not reflect the results of a recently completed write operation. The results may also include some stale data. If you repeat the query request after a short time, the results should return the latest data. Service quotas apply.

See code sample for details.

Upserts

You can use the Version parameter in a WriteRecords request to update data points. Timestream tracks a version number with each record. Version defaults to 1 when not specified for the record in the request. Timestream will update an existing record’s measure value along with its Version upon receiving a write request with a higher Version number for that record. Upon receiving an update request where the measure value is the same as that of the existing record, Timestream still updates Version, if it is greater than the existing value of Version. You can update a data point as many times as desired, as long as the value of Version continuously increases.

For example, suppose you write a new record without indicating Version in the request. Timestream will store this record, and set Version to 1. Now, suppose you try to update this record with a WriteRecords request of the same record with a different measure value but, like before, do not provide Version. In this case, Timestream will reject this update with a RejectedRecordsException since the updated record’s version is not greater than the existing value of Version. However, if you were to resend the update request with Version set to 2, Timestream would then succeed in updating the record’s value, and the Version would be set to 2. Next, suppose you sent a WriteRecords request with this same record and an identical measure value, but with Version set to 3. In this case, Timestream would only update Version to 3. Any further updates would need to send a version number greater than 3, or the update requests would receive a RejectedRecordsException.

Parameter Syntax

$result = $client->writeRecords([
    'CommonAttributes' => [
        'Dimensions' => [
            [
                'DimensionValueType' => 'VARCHAR',
                'Name' => '<string>', // REQUIRED
                'Value' => '<string>', // REQUIRED
            ],
            // ...
        ],
        'MeasureName' => '<string>',
        'MeasureValue' => '<string>',
        'MeasureValueType' => 'DOUBLE|BIGINT|VARCHAR|BOOLEAN|TIMESTAMP|MULTI',
        'MeasureValues' => [
            [
                'Name' => '<string>', // REQUIRED
                'Type' => 'DOUBLE|BIGINT|VARCHAR|BOOLEAN|TIMESTAMP|MULTI', // REQUIRED
                'Value' => '<string>', // REQUIRED
            ],
            // ...
        ],
        'Time' => '<string>',
        'TimeUnit' => 'MILLISECONDS|SECONDS|MICROSECONDS|NANOSECONDS',
        'Version' => <integer>,
    ],
    'DatabaseName' => '<string>', // REQUIRED
    'Records' => [ // REQUIRED
        [
            'Dimensions' => [
                [
                    'DimensionValueType' => 'VARCHAR',
                    'Name' => '<string>', // REQUIRED
                    'Value' => '<string>', // REQUIRED
                ],
                // ...
            ],
            'MeasureName' => '<string>',
            'MeasureValue' => '<string>',
            'MeasureValueType' => 'DOUBLE|BIGINT|VARCHAR|BOOLEAN|TIMESTAMP|MULTI',
            'MeasureValues' => [
                [
                    'Name' => '<string>', // REQUIRED
                    'Type' => 'DOUBLE|BIGINT|VARCHAR|BOOLEAN|TIMESTAMP|MULTI', // REQUIRED
                    'Value' => '<string>', // REQUIRED
                ],
                // ...
            ],
            'Time' => '<string>',
            'TimeUnit' => 'MILLISECONDS|SECONDS|MICROSECONDS|NANOSECONDS',
            'Version' => <integer>,
        ],
        // ...
    ],
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members

CommonAttributes

Type: Record structure

A record containing the common measure, dimension, time, and version attributes shared across all the records in the request. The measure and dimension attributes specified will be merged with the measure and dimension attributes in the records object when the data is written into Timestream. Dimensions may not overlap, or a ValidationException will be thrown. In other words, a record must contain dimensions with unique names.

DatabaseName

Required: Yes
Type: string

The name of the Timestream database.

Records

Required: Yes
Type: Array of Record structures

An array of records containing the unique measure, dimension, time, and version attributes for each time series data point.

TableName

Required: Yes
Type: string

The name of the Timestream table.

Result Syntax

[
    'RecordsIngested' => [
        'MagneticStore' => <integer>,
        'MemoryStore' => <integer>,
        'Total' => <integer>,
    ],
]

Result Details

Members

RecordsIngested

Type: RecordsIngested structure

Information on the records ingested by this request.

Errors

InternalServerException:
Timestream was unable to fully process this request because of an internal server error.
ThrottlingException:
Too many requests were made by a user exceeding service quotas. The request was throttled.
ValidationException:
Invalid or malformed request.
ResourceNotFoundException:
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
AccessDeniedException:
You are not authorized to perform this action.
RejectedRecordsException:
WriteRecords would throw this exception in the following cases:
- Records with duplicate data where there are multiple records with the same dimensions, timestamps, and measure names but:
  - Measure values are different
  - Version is not present in the request or the value of version in the new record is equal to or lower than the existing value
  In this case, if Timestream rejects data, the ExistingVersion field in the RejectedRecords response will indicate the current record’s version. To force an update, you can resend the request with a version for the record set to a value greater than the ExistingVersion.
- Records with timestamps that lie outside the retention duration of the memory store
- Records with dimensions or measures that exceed the Timestream defined limits.
For more information, see Quotas in the Timestream Developer Guide.
InvalidEndpointException:
The requested endpoint was invalid.

Shapes

AccessDeniedException

Description

You are not authorized to perform this action.

Members

Message

Required: Yes
Type: string

ConflictException

Description

Timestream was unable to process this request because it contains resource that already exists.

Members

Message

Required: Yes
Type: string

Database

Description

A top level container for a table. Databases and tables are the fundamental management concepts in Amazon Timestream. All tables in a database are encrypted with the same KMS key.

Members

Arn

Type: string

The Amazon Resource Name that uniquely identifies this database.

CreationTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time when the database was created, calculated from the Unix epoch time.

DatabaseName

Type: string

The name of the Timestream database.

KmsKeyId

Type: string

The identifier of the KMS key used to encrypt the data stored in the database.

LastUpdatedTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The last time that this database was updated.

TableCount

Type: long (int|float)

The total number of tables found within a Timestream database.

Dimension

Description

Dimension represents the meta data attributes of the time series. For example, the name and availability zone of an EC2 instance or the name of the manufacturer of a wind turbine are dimensions.

Members

DimensionValueType

Type: string

The data type of the dimension for the time series data point.

Name

Required: Yes
Type: string

Dimension represents the meta data attributes of the time series. For example, the name and availability zone of an EC2 instance or the name of the manufacturer of a wind turbine are dimensions.

For constraints on Dimension names, see Naming Constraints.

Value

Required: Yes
Type: string

The value of the dimension.

Endpoint

Description

Represents an available endpoint against which to make API calls agaisnt, as well as the TTL for that endpoint.

Members

Address

Required: Yes
Type: string

An endpoint address.

CachePeriodInMinutes

Required: Yes
Type: long (int|float)

The TTL for the endpoint, in minutes.

InternalServerException

Description

Timestream was unable to fully process this request because of an internal server error.

Members

Message

Required: Yes
Type: string

InvalidEndpointException

Description

The requested endpoint was invalid.

Members

Message

Type: string

MagneticStoreRejectedDataLocation

Description

The location to write error reports for records rejected, asynchronously, during magnetic store writes.

Members

S3Configuration

Type: S3Configuration structure

Configuration of an S3 location to write error reports for records rejected, asynchronously, during magnetic store writes.

MagneticStoreWriteProperties

Description

The set of properties on a table for configuring magnetic store writes.

Members

EnableMagneticStoreWrites

Required: Yes
Type: boolean

A flag to enable magnetic store writes.

MagneticStoreRejectedDataLocation

Type: MagneticStoreRejectedDataLocation structure

The location to write error reports for records rejected asynchronously during magnetic store writes.

MeasureValue

Description

MeasureValue represents the data attribute of the time series. For example, the CPU utilization of an EC2 instance or the RPM of a wind turbine are measures. MeasureValue has both name and value.

MeasureValue is only allowed for type MULTI. Using MULTI type, you can pass multiple data attributes associated with the same time series in a single record

Members

Name

Required: Yes
Type: string

Name of the MeasureValue.

For constraints on MeasureValue names, refer to Naming Constraints in the Timestream developer guide.

Type

Required: Yes
Type: string

Contains the data type of the MeasureValue for the time series data point.

Value

Required: Yes
Type: string

Value for the MeasureValue.

Record

Description

Record represents a time series data point being written into Timestream. Each record contains an array of dimensions. Dimensions represent the meta data attributes of a time series data point such as the instance name or availability zone of an EC2 instance. A record also contains the measure name which is the name of the measure being collected for example the CPU utilization of an EC2 instance. A record also contains the measure value and the value type which is the data type of the measure value. In addition, the record contains the timestamp when the measure was collected that the timestamp unit which represents the granularity of the timestamp.

Records have a Version field, which is a 64-bit long that you can use for updating data points. Writes of a duplicate record with the same dimension, timestamp, and measure name but different measure value will only succeed if the Version attribute of the record in the write request is higher than that of the existing record. Timestream defaults to a Version of 1 for records without the Version field.

Members

Dimensions

Type: Array of Dimension structures

Contains the list of dimensions for time series data points.

MeasureName

Type: string

Measure represents the data attribute of the time series. For example, the CPU utilization of an EC2 instance or the RPM of a wind turbine are measures.

MeasureValue

Type: string

Contains the measure value for the time series data point.

MeasureValueType

Type: string

Contains the data type of the measure value for the time series data point. Default type is DOUBLE.

MeasureValues

Type: Array of MeasureValue structures

Contains the list of MeasureValue for time series data points.

This is only allowed for type MULTI. For scalar values, use MeasureValue attribute of the Record directly.

Time

Type: string

Contains the time at which the measure value for the data point was collected. The time value plus the unit provides the time elapsed since the epoch. For example, if the time value is 12345 and the unit is ms, then 12345 ms have elapsed since the epoch.

TimeUnit

Type: string

The granularity of the timestamp unit. It indicates if the time value is in seconds, milliseconds, nanoseconds or other supported values. Default is MILLISECONDS.

Version

Type: long (int|float)

64-bit attribute used for record updates. Write requests for duplicate data with a higher version number will update the existing measure value and version. In cases where the measure value is the same, Version will still be updated . Default value is 1.

Version must be 1 or greater, or you will receive a ValidationException error.

RecordsIngested

Description

Information on the records ingested by this request.

Members

MagneticStore

Type: int

Count of records ingested into the magnetic store.

MemoryStore

Type: int

Count of records ingested into the memory store.

Total

Type: int

Total count of successfully ingested records.

RejectedRecord

Description

Records that were not successfully inserted into Timestream due to data validation issues that must be resolved prior to reinserting time series data into the system.

Members

ExistingVersion

Type: long (int|float)

The existing version of the record. This value is populated in scenarios where an identical record exists with a higher version than the version in the write request.

Reason

Type: string

The reason why a record was not successfully inserted into Timestream. Possible causes of failure include:

Records with duplicate data where there are multiple records with the same dimensions, timestamps, and measure names but:
- Measure values are different
- Version is not present in the request or the value of version in the new record is equal to or lower than the existing value
If Timestream rejects data for this case, the ExistingVersion field in the RejectedRecords response will indicate the current record’s version. To force an update, you can resend the request with a version for the record set to a value greater than the ExistingVersion.
Records with timestamps that lie outside the retention duration of the memory store

When the retention window is updated, you will receive a RejectedRecords exception if you immediately try to ingest data within the new window. To avoid a RejectedRecords exception, wait until the duration of the new window to ingest new data. For further information, see Best Practices for Configuring Timestream and the explanation of how storage works in Timestream.
Records with dimensions or measures that exceed the Timestream defined limits.

For more information, see Access Management in the Timestream Developer Guide.

RecordIndex

Type: int

The index of the record in the input request for WriteRecords. Indexes begin with 0.

RejectedRecordsException

Description

WriteRecords would throw this exception in the following cases:

Records with duplicate data where there are multiple records with the same dimensions, timestamps, and measure names but:
- Measure values are different
- Version is not present in the request or the value of version in the new record is equal to or lower than the existing value
In this case, if Timestream rejects data, the ExistingVersion field in the RejectedRecords response will indicate the current record’s version. To force an update, you can resend the request with a version for the record set to a value greater than the ExistingVersion.
Records with timestamps that lie outside the retention duration of the memory store
Records with dimensions or measures that exceed the Timestream defined limits.

For more information, see Quotas in the Timestream Developer Guide.

Members

Message

Type: string

RejectedRecords

Type: Array of RejectedRecord structures

ResourceNotFoundException

Description

The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.

Members

Message

Type: string

RetentionProperties

Description

Retention properties contain the duration for which your time series data must be stored in the magnetic store and the memory store.

Members

MagneticStoreRetentionPeriodInDays

Required: Yes
Type: long (int|float)

The duration for which data must be stored in the magnetic store.

MemoryStoreRetentionPeriodInHours

Required: Yes
Type: long (int|float)

The duration for which data must be stored in the memory store.

S3Configuration

Description

Configuration specifing an S3 location.

Members

BucketName

Type: string

>Bucket name of the customer S3 bucket.

EncryptionOption

Type: string

Encryption option for the customer s3 location. Options are S3 server side encryption with an S3-managed key or KMS managed key.

KmsKeyId

Type: string

KMS key id for the customer s3 location when encrypting with a KMS managed key.

ObjectKeyPrefix

Type: string

Object key preview for the customer S3 location.

ServiceQuotaExceededException

Description

Instance quota of resource exceeded for this account.

Members

Message

Type: string

Table

Description

Table represents a database table in Timestream. Tables contain one or more related time series. You can modify the retention duration of the memory store and the magnetic store for a table.

Members

Arn

Type: string

The Amazon Resource Name that uniquely identifies this table.

CreationTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time when the Timestream table was created.

DatabaseName

Type: string

The name of the Timestream database that contains this table.

LastUpdatedTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time when the Timestream table was last updated.

MagneticStoreWriteProperties

Type: MagneticStoreWriteProperties structure

Contains properties to set on the table when enabling magnetic store writes.

RetentionProperties

Type: RetentionProperties structure

The retention duration for the memory store and magnetic store.

TableName

Type: string

The name of the Timestream table.

TableStatus

Type: string

The current state of the table:

DELETING - The table is being deleted.
ACTIVE - The table is ready for use.

Tag

Description

A tag is a label that you assign to a Timestream database and/or table. Each tag consists of a key and an optional value, both of which you define. Tags enable you to categorize databases and/or tables, for example, by purpose, owner, or environment.

Members

Key

Required: Yes
Type: string

The key of the tag. Tag keys are case sensitive.

Value

Required: Yes
Type: string

The value of the tag. Tag values are case-sensitive and can be null.

ThrottlingException

Description

Too many requests were made by a user exceeding service quotas. The request was throttled.

Members

Message

Required: Yes
Type: string

ValidationException

Description

Invalid or malformed request.

Members

Message

Required: Yes
Type: string

Namespaces

Classes

Interfaces

Traits

Exceptions

Functions

Amazon Timestream Write 2018-11-01

Operation Summary

Paginators

Operations

CreateDatabase

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

CreateTable

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

DeleteDatabase

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Errors

DeleteTable

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Errors

DescribeDatabase

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

DescribeEndpoints

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

DescribeTable

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

ListDatabases

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

ListTables

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors