Amazon Timestream Write 2018-11-01
- 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:
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
-
Timestream was unable to process this request because it contains resource that already exists.
-
Invalid or malformed request.
-
You are not authorized to perform this action.
-
ServiceQuotaExceededException:
Instance quota of resource exceeded for this account.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
The requested endpoint was invalid.
-
Timestream was unable to fully process this request because of an internal server error.
-
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
-
Timestream was unable to process this request because it contains resource that already exists.
-
Invalid or malformed request.
-
You are not authorized to perform this action.
-
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.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
The requested endpoint was invalid.
-
Timestream was unable to fully process this request because of an internal server error.
-
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
Result Syntax
[]
Result Details
Errors
-
Timestream was unable to fully process this request because of an internal server error.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
-
Invalid or malformed request.
-
You are not authorized to perform this action.
-
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
Result Syntax
[]
Result Details
Errors
-
Timestream was unable to fully process this request because of an internal server error.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
Invalid or malformed request.
-
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
-
You are not authorized to perform this action.
-
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
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
-
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
-
Invalid or malformed request.
-
You are not authorized to perform this action.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
Timestream was unable to fully process this request because of an internal server error.
-
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
Endpointsobject is returned when aDescribeEndpointsrequest is made.
Errors
-
Timestream was unable to fully process this request because of an internal server error.
-
Invalid or malformed request.
-
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
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
-
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
-
Invalid or malformed request.
-
You are not authorized to perform this action.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
Timestream was unable to fully process this request because of an internal server error.
-
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
-
Timestream was unable to fully process this request because of an internal server error.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
Invalid or malformed request.
-
You are not authorized to perform this action.
-
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
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
[
'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
-
Timestream was unable to fully process this request because of an internal server error.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
Invalid or malformed request.
-
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
-
You are not authorized to perform this action.
-
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
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
-
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
Invalid or malformed request.
-
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
Errors
-
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.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
Invalid or malformed request.
-
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
Errors
-
Invalid or malformed request.
-
ServiceQuotaExceededException:
Instance quota of resource exceeded for this account.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
-
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 theKmsKeyIdcurrently registered with the database is the same as theKmsKeyIdin the request, there will not be any update.You can specify the
KmsKeyIdusing 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
-
Invalid or malformed request.
-
You are not authorized to perform this action.
-
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.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
Timestream was unable to fully process this request because of an internal server error.
-
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
-
Timestream was unable to fully process this request because of an internal server error.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
Invalid or malformed request.
-
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
-
You are not authorized to perform this action.
-
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
ValidationExceptionwill 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
-
Timestream was unable to fully process this request because of an internal server error.
-
Too many requests were made by a user exceeding service quotas. The request was throttled.
-
Invalid or malformed request.
-
The operation tried to access a nonexistent resource. The resource might not be specified correctly, or its status might not be ACTIVE.
-
You are not authorized to perform this action.
-
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
ExistingVersionfield in theRejectedRecordsresponse 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 theExistingVersion. -
-
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.
-
-
The requested endpoint was invalid.
Shapes
AccessDeniedException
Description
You are not authorized to perform this action.
Members
ConflictException
Description
Timestream was unable to process this request because it contains resource that already exists.
Members
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
InternalServerException
Description
Timestream was unable to fully process this request because of an internal server error.
Members
InvalidEndpointException
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, useMeasureValueattribute 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
12345and the unit isms, then12345 mshave 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,
Versionwill still be updated . Default value is1.Versionmust be1or greater, or you will receive aValidationExceptionerror.
RecordsIngested
Description
Information on the records ingested by this request.
Members
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
ExistingVersionfield in theRejectedRecordsresponse 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 theExistingVersion. -
-
Records with timestamps that lie outside the retention duration of the memory store
When the retention window is updated, you will receive a
RejectedRecordsexception if you immediately try to ingest data within the new window. To avoid aRejectedRecordsexception, 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
ExistingVersionfield in theRejectedRecordsresponse 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 theExistingVersion. -
-
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
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
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
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
ThrottlingException
Description
Too many requests were made by a user exceeding service quotas. The request was throttled.