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 AWS managed KMS keys for more info. Service quotas apply. For more information, see Access Management in the Timestream Developer Guide.
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 AWS 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.
CreateTable
$result = $client->createTable
([/* ... */]); $promise = $client->createTableAsync
([/* ... */]);
The CreateTable operation adds a new table to an existing database in your account. In an AWS 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 seperate databases. While creating the table, you must specify the table name, database name, and the retention properties. Service quotas apply. For more information, see Access Management in the Timestream Developer Guide.
Parameter Syntax
$result = $client->createTable([ 'DatabaseName' => '<string>', // REQUIRED '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.
- 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>, '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.
-
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.
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.
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. For more information, see Access Management in the Timestream Developer Guide.
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 Timestream’s 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:
-
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 to use DescribeEndpoints, see The Endpoint Discovery Pattern and REST APIs.
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 aDescribeEndpoints
request 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. For more information, see Access Management in the Timestream Developer Guide.
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>, '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. For more information, see Access Management in the Timestream Developer Guide.
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.
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>, '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.
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 theKmsKeyId
currently registered with the database is the same as theKmsKeyId
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
-
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.
Service quotas apply. For more information, see Access Management in the Timestream Developer Guide.
Parameter Syntax
$result = $client->updateTable([ 'DatabaseName' => '<string>', // REQUIRED 'RetentionProperties' => [ // REQUIRED 'MagneticStoreRetentionPeriodInDays' => <integer>, // REQUIRED 'MemoryStoreRetentionPeriodInHours' => <integer>, // REQUIRED ], 'TableName' => '<string>', // REQUIRED ]);
Parameter Details
Members
- DatabaseName
-
- Required: Yes
- Type: string
The name of the Timestream database.
- RetentionProperties
-
- Required: Yes
- Type: RetentionProperties structure
The retention duration of the memory store and the magnetic store.
- TableName
-
- Required: Yes
- Type: string
The name of the Timesream table.
Result Syntax
[ 'Table' => [ 'Arn' => '<string>', 'CreationTime' => <DateTime>, 'DatabaseName' => '<string>', 'LastUpdatedTime' => <DateTime>, '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. For more information, see Access Management in the Timestream Developer Guide.
Parameter Syntax
$result = $client->writeRecords([ 'CommonAttributes' => [ 'Dimensions' => [ [ 'DimensionValueType' => 'VARCHAR', 'Name' => '<string>', // REQUIRED 'Value' => '<string>', // REQUIRED ], // ... ], 'MeasureName' => '<string>', 'MeasureValue' => '<string>', 'MeasureValueType' => 'DOUBLE|BIGINT|VARCHAR|BOOLEAN', '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', '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 and dimension attributes shared across all the records in the request. The measure and dimension attributes specified in here will be merged with the measure and dimension attributes in the records object when the data is written into Timestream.
- 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 dimension and measure attributes for each time series data point.
- TableName
-
- Required: Yes
- Type: string
The name of the Timesream table.
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.
-
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 different measure values.
-
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 Access Management 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
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.
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.
- 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 isms
, then12345 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.
- 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 to 1.
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 different measure values.
-
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 aRejectedRecords
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 different measure values.
-
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 Access Management 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
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.
- 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.