scheduled_queries

Creates, updates, deletes, gets or lists a scheduled_queries resource.

Overview

Name	scheduled_queries
Type	Resource
Id	aws.timestream_query.scheduled_queries

Fields

The following fields are returned by SELECT queries:

describe_scheduled_query

Name	Datatype	Description
arn	string	Scheduled query ARN.
creation_time	string (date-time)	Creation time of the scheduled query.
error_report_configuration	object	Error-reporting configuration for the scheduled query.
kms_key_id	string	A customer provided KMS key used to encrypt the scheduled query resource.
last_run_summary	object	Runtime summary for the last scheduled query run.
name	string	Name of the scheduled query. (pattern: <code>[a-zA-Z0-9|!-*'()]([a-zA-Z0-9]|[!-*'()/.])+</code>)
next_invocation_time	string (date-time)	The next time the scheduled query is scheduled to run.
notification_configuration	object	Notification configuration.
previous_invocation_time	string (date-time)	Last time the query was run.
query_string	string	The query to be run.
recently_failed_runs	array	Runtime summary for the last five failed scheduled query runs.
schedule_configuration	object	Schedule configuration.
scheduled_query_execution_role_arn	string	IAM role that Timestream uses to run the schedule query.
state	string	State of the scheduled query. (ENABLED, DISABLED)
target_configuration	object	Scheduled query target store configuration.

list_scheduled_queries

Name	Datatype	Description
arn	string	The Amazon Resource Name.
creation_time	string (date-time)	The creation time of the scheduled query.
error_report_configuration	object	Configuration for scheduled query error reporting.
last_run_status	string	Status of the last scheduled query run. (AUTO_TRIGGER_SUCCESS, AUTO_TRIGGER_FAILURE, MANUAL_TRIGGER_SUCCESS, MANUAL_TRIGGER_FAILURE)
name	string	The name of the scheduled query. (pattern: <code>[a-zA-Z0-9|!-*'()]([a-zA-Z0-9]|[!-*'()/.])+</code>)
next_invocation_time	string (date-time)	The next time the scheduled query is to be run.
previous_invocation_time	string (date-time)	The last time the scheduled query was run.
state	string	State of scheduled query. (ENABLED, DISABLED)
target_destination	object	Target data source where final scheduled query result will be written.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_scheduled_query	select	region		Provides detailed information about a scheduled query.
list_scheduled_queries	select	region		Gets a list of all scheduled queries in the caller's Amazon account and Region. ListScheduledQueries is eventually consistent.
create_scheduled_query	insert	region, QueryString, ScheduleConfiguration, NotificationConfiguration, ScheduledQueryExecutionRoleArn, ErrorReportConfiguration		Create a scheduled query that will be run on your behalf at the configured schedule. Timestream assumes the execution role provided as part of the ScheduledQueryExecutionRoleArn parameter to run the query. You can use the NotificationConfiguration parameter to configure notification for your scheduled query operations.
update_scheduled_query	update	region, ScheduledQueryArn		Update a scheduled query.
delete_scheduled_query	delete	region		Deletes a given scheduled query. This is an irreversible operation.
execute_scheduled_query	exec	region, ScheduledQueryArn, InvocationTime		You can use this API to run a scheduled query manually. If you enabled QueryInsights, this API also returns insights and metrics related to the query that you executed as part of an Amazon SNS notification. QueryInsights helps with performance tuning of your query. For more information about QueryInsights, see Using query insights to optimize queries in Amazon Timestream.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_scheduled_query

Provides detailed information about a scheduled query.

SELECT
arn,
creation_time,
error_report_configuration,
kms_key_id,
last_run_summary,
name,
next_invocation_time,
notification_configuration,
previous_invocation_time,
query_string,
recently_failed_runs,
schedule_configuration,
scheduled_query_execution_role_arn,
state,
target_configuration
FROM aws.timestream_query.scheduled_queries
WHERE region = '{{ region }}' -- required
;

list_scheduled_queries

Gets a list of all scheduled queries in the caller's Amazon account and Region. ListScheduledQueries is eventually consistent.

SELECT
arn,
creation_time,
error_report_configuration,
last_run_status,
name,
next_invocation_time,
previous_invocation_time,
state,
target_destination
FROM aws.timestream_query.scheduled_queries
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_scheduled_query

Create a scheduled query that will be run on your behalf at the configured schedule. Timestream assumes the execution role provided as part of the ScheduledQueryExecutionRoleArn parameter to run the query. You can use the NotificationConfiguration parameter to configure notification for your scheduled query operations.

INSERT INTO aws.timestream_query.scheduled_queries (
Name,
QueryString,
ScheduleConfiguration,
NotificationConfiguration,
TargetConfiguration,
ClientToken,
ScheduledQueryExecutionRoleArn,
Tags,
KmsKeyId,
ErrorReportConfiguration,
region
)
SELECT 
'{{ Name }}',
'{{ QueryString }}' /* required */,
'{{ ScheduleConfiguration }}' /* required */,
'{{ NotificationConfiguration }}' /* required */,
'{{ TargetConfiguration }}',
'{{ ClientToken }}',
'{{ ScheduledQueryExecutionRoleArn }}' /* required */,
'{{ Tags }}',
'{{ KmsKeyId }}',
'{{ ErrorReportConfiguration }}' /* required */,
'{{ region }}'
RETURNING
arn
;

Manifest

# Description fields are for documentation purposes
- name: scheduled_queries
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the scheduled_queries resource.
  - name: Name
    value: "{{ Name }}"
    description: |
      Name of the scheduled query.
  - name: QueryString
    value: "{{ QueryString }}"
    description: |
      The query string to run. Parameter names can be specified in the query string @ character followed by an identifier. The named Parameter @scheduled_runtime is reserved and can be used in the query to get the time at which the query is scheduled to run. The timestamp calculated according to the ScheduleConfiguration parameter, will be the value of @scheduled_runtime paramater for each query run. For example, consider an instance of a scheduled query executing on 2021-12-01 00:00:00. For this instance, the @scheduled_runtime parameter is initialized to the timestamp 2021-12-01 00:00:00 when invoking the query.
  - name: ScheduleConfiguration
    description: |
      The schedule configuration for the query.
    value:
      ScheduleExpression: "{{ ScheduleExpression }}"
  - name: NotificationConfiguration
    description: |
      Notification configuration for the scheduled query. A notification is sent by Timestream when a query run finishes, when the state is updated or when you delete it.
    value:
      SnsConfiguration:
        TopicArn: "{{ TopicArn }}"
  - name: TargetConfiguration
    description: |
      Configuration used for writing the result of a query.
    value:
      TimestreamConfiguration:
        DatabaseName: "{{ DatabaseName }}"
        TableName: "{{ TableName }}"
        TimeColumn: "{{ TimeColumn }}"
        DimensionMappings:
          - Name: "{{ Name }}"
            DimensionValueType: "{{ DimensionValueType }}"
        MultiMeasureMappings:
          TargetMultiMeasureName: "{{ TargetMultiMeasureName }}"
          MultiMeasureAttributeMappings:
            - SourceColumn: "{{ SourceColumn }}"
              TargetMultiMeasureAttributeName: "{{ TargetMultiMeasureAttributeName }}"
              MeasureValueType: "{{ MeasureValueType }}"
        MixedMeasureMappings:
          - MeasureName: "{{ MeasureName }}"
            SourceColumn: "{{ SourceColumn }}"
            TargetMeasureName: "{{ TargetMeasureName }}"
            MeasureValueType: "{{ MeasureValueType }}"
            MultiMeasureAttributeMappings: "{{ MultiMeasureAttributeMappings }}"
        MeasureNameColumn: "{{ MeasureNameColumn }}"
  - name: ClientToken
    value: "{{ ClientToken }}"
    description: |
      Using a ClientToken makes the call to CreateScheduledQuery idempotent, in other words, making the same request repeatedly will produce the same result. Making multiple identical CreateScheduledQuery requests has the same effect as making a single request. If CreateScheduledQuery is called without a ClientToken, the Query SDK generates a ClientToken on your behalf. After 8 hours, any request with the same ClientToken is treated as a new request.
  - name: ScheduledQueryExecutionRoleArn
    value: "{{ ScheduledQueryExecutionRoleArn }}"
    description: |
      The ARN for the IAM role that Timestream will assume when running the scheduled query.
  - name: Tags
    description: |
      A list of key-value pairs to label the scheduled query.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: KmsKeyId
    value: "{{ KmsKeyId }}"
    description: |
      The Amazon KMS key used to encrypt the scheduled query resource, at-rest. If the Amazon KMS key is not specified, the scheduled query resource will be encrypted with a Timestream owned Amazon KMS key. To specify a KMS key, use the key ID, key ARN, alias name, or alias ARN. When using an alias name, prefix the name with alias/ If ErrorReportConfiguration uses SSE_KMS as encryption type, the same KmsKeyId is used to encrypt the error report at rest.
  - name: ErrorReportConfiguration
    description: |
      Configuration for error reporting. Error reports will be generated when a problem is encountered when writing the query results.
    value:
      S3Configuration:
        BucketName: "{{ BucketName }}"
        ObjectKeyPrefix: "{{ ObjectKeyPrefix }}"
        EncryptionOption: "{{ EncryptionOption }}"

UPDATE examples

update_scheduled_query

Update a scheduled query.

UPDATE aws.timestream_query.scheduled_queries
SET 
ScheduledQueryArn = '{{ ScheduledQueryArn }}',
State = '{{ State }}'
WHERE 
region = '{{ region }}' --required
AND ScheduledQueryArn = '{{ ScheduledQueryArn }}' --required;

DELETE examples

delete_scheduled_query

Deletes a given scheduled query. This is an irreversible operation.

DELETE FROM aws.timestream_query.scheduled_queries
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

execute_scheduled_query

You can use this API to run a scheduled query manually. If you enabled QueryInsights, this API also returns insights and metrics related to the query that you executed as part of an Amazon SNS notification. QueryInsights helps with performance tuning of your query. For more information about QueryInsights, see Using query insights to optimize queries in Amazon Timestream.

EXEC aws.timestream_query.scheduled_queries.execute_scheduled_query 
@region='{{ region }}' --required 
@@json=
'{
"ScheduledQueryArn": "{{ ScheduledQueryArn }}", 
"InvocationTime": "{{ InvocationTime }}", 
"ClientToken": "{{ ClientToken }}", 
"QueryInsights": "{{ QueryInsights }}"
}'
;