Struct Client

pub struct Client { /* private fields */ }

Client for Amazon Timestream Query

Client for invoking operations on Amazon Timestream Query. Each operation on Amazon Timestream Query is a method on this this struct. .send() MUST be invoked on the generated operations to dispatch the request to the service.

Constructing a Client

A Config is required to construct a client. For most use cases, the aws-config crate should be used to automatically resolve this config using aws_config::load_from_env(), since this will resolve an SdkConfig which can be shared across multiple different AWS SDK clients. This config resolution process can be customized by calling aws_config::from_env() instead, which returns a ConfigLoader that uses the builder pattern to customize the default config.

In the simplest case, creating a client looks as follows:

let config = aws_config::load_from_env().await;
// You MUST call `with_endpoint_discovery_enabled` to produce a working client for this service.
let client = aws_sdk_timestreamquery::Client::new(&config).with_endpoint_discovery_enabled().await;

Occasionally, SDKs may have additional service-specific values that can be set on the Config that is absent from SdkConfig, or slightly different settings for a specific client may be desired. The Builder struct implements From<&SdkConfig>, so setting these specific settings can be done as follows:

let sdk_config = ::aws_config::load_from_env().await;
let config = aws_sdk_timestreamquery::config::Builder::from(&sdk_config)
    .some_service_specific_setting("value")
    .build();

See the aws-config docs and Config for more information on customizing configuration.

Note: Client construction is expensive due to connection thread pool initialization, and should be done once at application start-up.

Using the Client

A client has a function for every operation that can be performed by the service. For example, the CancelQuery operation has a Client::cancel_query, function which returns a builder for that operation. The fluent builder ultimately has a send() function that returns an async future that returns a result, as illustrated below:

let result = client.cancel_query()
    .query_id("example")
    .send()
    .await;

The underlying HTTP requests that get made by this can be modified with the customize_operation function on the fluent builder. See the customize module for more information.

Implementations

impl Client

pub fn cancel_query(&self) -> CancelQueryFluentBuilder

Constructs a fluent builder for the CancelQuery operation.

• The fluent builder is configurable:
  • query_id(impl Into<String>) / set_query_id(Option<String>):
    required: true
    

    The ID of the query that needs to be cancelled. QueryID is returned as part of the query result.

    
    
• On success, responds with CancelQueryOutput with field(s):
  • cancellation_message(Option<String>):

    A CancellationMessage is returned when a CancelQuery request for the query specified by QueryId has already been issued.

• On failure, responds with SdkError<CancelQueryError>

impl Client

pub fn create_scheduled_query(&self) -> CreateScheduledQueryFluentBuilder

Constructs a fluent builder for the CreateScheduledQuery operation.

• The fluent builder is configurable:
  • name(impl Into<String>) / set_name(Option<String>):
    required: true
    

    Name of the scheduled query.

    
    
  • query_string(impl Into<String>) / set_query_string(Option<String>):
    required: true
    

    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.

    
    
  • schedule_configuration(ScheduleConfiguration) / set_schedule_configuration(Option<ScheduleConfiguration>):
    required: true
    

    The schedule configuration for the query.

    
    
  • notification_configuration(NotificationConfiguration) / set_notification_configuration(Option<NotificationConfiguration>):
    required: true
    

    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.

    
    
  • target_configuration(TargetConfiguration) / set_target_configuration(Option<TargetConfiguration>):
    required: false
    

    Configuration used for writing the result of a query.

    
    
  • client_token(impl Into<String>) / set_client_token(Option<String>):
    required: false
    

    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.

    
    
  • scheduled_query_execution_role_arn(impl Into<String>) / set_scheduled_query_execution_role_arn(Option<String>):
    required: true
    

    The ARN for the IAM role that Timestream will assume when running the scheduled query.

    
    
  • tags(Tag) / set_tags(Option<Vec::<Tag>>):
    required: false
    

    A list of key-value pairs to label the scheduled query.

    
    
  • kms_key_id(impl Into<String>) / set_kms_key_id(Option<String>):
    required: false
    

    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.

    
    
  • error_report_configuration(ErrorReportConfiguration) / set_error_report_configuration(Option<ErrorReportConfiguration>):
    required: true
    

    Configuration for error reporting. Error reports will be generated when a problem is encountered when writing the query results.

    
    
• On success, responds with CreateScheduledQueryOutput with field(s):
  • arn(String):

    ARN for the created scheduled query.

• On failure, responds with SdkError<CreateScheduledQueryError>

impl Client

pub fn delete_scheduled_query(&self) -> DeleteScheduledQueryFluentBuilder

Constructs a fluent builder for the DeleteScheduledQuery operation.

• The fluent builder is configurable:
  • scheduled_query_arn(impl Into<String>) / set_scheduled_query_arn(Option<String>):
    required: true
    

    The ARN of the scheduled query.

    
    
• On success, responds with DeleteScheduledQueryOutput
• On failure, responds with SdkError<DeleteScheduledQueryError>

impl Client

pub fn describe_account_settings(&self) -> DescribeAccountSettingsFluentBuilder

Constructs a fluent builder for the DescribeAccountSettings operation.

• The fluent builder takes no input, just send it.
• On success, responds with DescribeAccountSettingsOutput with field(s):
  • max_query_tcu(Option<i32>):

    The maximum number of Timestream compute units (TCUs) the service will use at any point in time to serve your queries. To run queries, you must set a minimum capacity of 4 TCU. You can set the maximum number of TCU in multiples of 4, for example, 4, 8, 16, 32, and so on. This configuration is applicable only for on-demand usage of (TCUs).

  • query_pricing_model(Option<QueryPricingModel>):

    The pricing model for queries in your account.

    The QueryPricingModel parameter is used by several Timestream operations; however, the UpdateAccountSettings API operation doesn’t recognize any values other than COMPUTE_UNITS.

  • query_compute(Option<QueryComputeResponse>):

    An object that contains the usage settings for Timestream Compute Units (TCUs) in your account for the query workload.

• On failure, responds with SdkError<DescribeAccountSettingsError>

impl Client

pub fn describe_endpoints(&self) -> DescribeEndpointsFluentBuilder

Constructs a fluent builder for the DescribeEndpoints operation.

• The fluent builder takes no input, just send it.
• On success, responds with DescribeEndpointsOutput with field(s):
  • endpoints(Vec::<Endpoint>):

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

• On failure, responds with SdkError<DescribeEndpointsError>

impl Client

pub fn describe_scheduled_query(&self) -> DescribeScheduledQueryFluentBuilder

Constructs a fluent builder for the DescribeScheduledQuery operation.

• The fluent builder is configurable:
  • scheduled_query_arn(impl Into<String>) / set_scheduled_query_arn(Option<String>):
    required: true
    

    The ARN of the scheduled query.

    
    
• On success, responds with DescribeScheduledQueryOutput with field(s):
  • scheduled_query(Option<ScheduledQueryDescription>):

    The scheduled query.

• On failure, responds with SdkError<DescribeScheduledQueryError>

impl Client

pub fn execute_scheduled_query(&self) -> ExecuteScheduledQueryFluentBuilder

Constructs a fluent builder for the ExecuteScheduledQuery operation.

• The fluent builder is configurable:
  • scheduled_query_arn(impl Into<String>) / set_scheduled_query_arn(Option<String>):
    required: true
    

    ARN of the scheduled query.

    
    
  • invocation_time(DateTime) / set_invocation_time(Option<DateTime>):
    required: true
    

    The timestamp in UTC. Query will be run as if it was invoked at this timestamp.

    
    
  • client_token(impl Into<String>) / set_client_token(Option<String>):
    required: false
    

    Not used.

    
    
  • query_insights(ScheduledQueryInsights) / set_query_insights(Option<ScheduledQueryInsights>):
    required: false
    

    Encapsulates settings for enabling QueryInsights.

    Enabling QueryInsights returns insights and metrics as a part of the Amazon SNS notification for the query that you executed. You can use QueryInsights to tune your query performance and cost.

    
    
• On success, responds with ExecuteScheduledQueryOutput
• On failure, responds with SdkError<ExecuteScheduledQueryError>

impl Client

pub fn list_scheduled_queries(&self) -> ListScheduledQueriesFluentBuilder

Constructs a fluent builder for the ListScheduledQueries operation. This operation supports pagination; See into_paginator().

• The fluent builder is configurable:
  • max_results(i32) / set_max_results(Option<i32>):
    required: false
    

    The maximum 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 the argument to the subsequent call to ListScheduledQueriesRequest.

    
    
  • next_token(impl Into<String>) / set_next_token(Option<String>):
    required: false
    

    A pagination token to resume pagination.

    
    
• On success, responds with ListScheduledQueriesOutput with field(s):
  • scheduled_queries(Vec::<ScheduledQuery>):

    A list of scheduled queries.

  • next_token(Option<String>):

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

• On failure, responds with SdkError<ListScheduledQueriesError>

impl Client

pub fn list_tags_for_resource(&self) -> ListTagsForResourceFluentBuilder

Constructs a fluent builder for the ListTagsForResource operation. This operation supports pagination; See into_paginator().

• The fluent builder is configurable:
  • resource_arn(impl Into<String>) / set_resource_arn(Option<String>):
    required: true
    

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

    
    
  • max_results(i32) / set_max_results(Option<i32>):
    required: false
    

    The maximum number of tags to return.

    
    
  • next_token(impl Into<String>) / set_next_token(Option<String>):
    required: false
    

    A pagination token to resume pagination.

    
    
• On success, responds with ListTagsForResourceOutput with field(s):
  • tags(Vec::<Tag>):

    The tags currently associated with the Timestream resource.

  • next_token(Option<String>):

    A pagination token to resume pagination with a subsequent call to ListTagsForResourceResponse.

• On failure, responds with SdkError<ListTagsForResourceError>

impl Client

pub fn prepare_query(&self) -> PrepareQueryFluentBuilder

Constructs a fluent builder for the PrepareQuery operation.

• The fluent builder is configurable:
  • query_string(impl Into<String>) / set_query_string(Option<String>):
    required: true
    

    The Timestream query string that you want to use as a prepared statement. Parameter names can be specified in the query string @ character followed by an identifier.

    
    
  • validate_only(bool) / set_validate_only(Option<bool>):
    required: false
    

    By setting this value to true, Timestream will only validate that the query string is a valid Timestream query, and not store the prepared query for later use.

    
    
• On success, responds with PrepareQueryOutput with field(s):
  • query_string(String):

    The query string that you want prepare.

  • columns(Vec::<SelectColumn>):

    A list of SELECT clause columns of the submitted query string.

  • parameters(Vec::<ParameterMapping>):

    A list of parameters used in the submitted query string.

• On failure, responds with SdkError<PrepareQueryError>

impl Client

pub fn query(&self) -> QueryFluentBuilder

Constructs a fluent builder for the Query operation.

• The fluent builder is configurable:
  • query_string(impl Into<String>) / set_query_string(Option<String>):
    required: true
    

    The query to be run by Timestream.

    
    
  • client_token(impl Into<String>) / set_client_token(Option<String>):
    required: false
    

    Unique, case-sensitive string of up to 64 ASCII characters specified when a Query request is made. Providing a ClientToken makes the call to Query idempotent. This means that running the same query repeatedly will produce the same result. In other words, making multiple identical Query requests has the same effect as making a single request. When using ClientToken in a query, note the following:

    • If the Query API is instantiated without a ClientToken, the Query SDK generates a ClientToken on your behalf.

    • If the Query invocation only contains the ClientToken but does not include a NextToken, that invocation of Query is assumed to be a new query run.

    • If the invocation contains NextToken, that particular invocation is assumed to be a subsequent invocation of a prior call to the Query API, and a result set is returned.

    • After 4 hours, any request with the same ClientToken is treated as a new request.

    
    
  • next_token(impl Into<String>) / set_next_token(Option<String>):
    required: false
    

    A pagination token used to return a set of results. When the Query API is invoked using NextToken, that particular invocation is assumed to be a subsequent invocation of a prior call to Query, and a result set is returned. However, if the Query invocation only contains the ClientToken, that invocation of Query is assumed to be a new query run.

    Note the following when using NextToken in a query:

    • A pagination token can be used for up to five Query invocations, OR for a duration of up to 1 hour – whichever comes first.

    • Using the same NextToken will return the same set of records. To keep paginating through the result set, you must to use the most recent nextToken.

    • Suppose a Query invocation returns two NextToken values, TokenA and TokenB. If TokenB is used in a subsequent Query invocation, then TokenA is invalidated and cannot be reused.

    • To request a previous result set from a query after pagination has begun, you must re-invoke the Query API.

    • The latest NextToken should be used to paginate until null is returned, at which point a new NextToken should be used.

    • If the IAM principal of the query initiator and the result reader are not the same and/or the query initiator and the result reader do not have the same query string in the query requests, the query will fail with an Invalid pagination token error.

    
    
  • max_rows(i32) / set_max_rows(Option<i32>):
    required: false
    

    The total number of rows to be returned in the Query output. The initial run of Query with a MaxRows value specified will return the result set of the query in two cases:

    • The size of the result is less than 1MB.

    • The number of rows in the result set is less than the value of maxRows.

    Otherwise, the initial invocation of Query only returns a NextToken, which can then be used in subsequent calls to fetch the result set. To resume pagination, provide the NextToken value in the subsequent command.

    If the row size is large (e.g. a row has many columns), Timestream may return fewer rows to keep the response size from exceeding the 1 MB limit. If MaxRows is not provided, Timestream will send the necessary number of rows to meet the 1 MB limit.

    
    
  • query_insights(QueryInsights) / set_query_insights(Option<QueryInsights>):
    required: false
    

    Encapsulates settings for enabling QueryInsights.

    Enabling QueryInsights returns insights and metrics in addition to query results for the query that you executed. You can use QueryInsights to tune your query performance.

    
    
• On success, responds with QueryOutput with field(s):
  • query_id(String):

    A unique ID for the given query.

  • next_token(Option<String>):

    A pagination token that can be used again on a Query call to get the next set of results.

  • rows(Vec::<Row>):

    The result set rows returned by the query.

  • column_info(Vec::<ColumnInfo>):

    The column data types of the returned result set.

  • query_status(Option<QueryStatus>):

    Information about the status of the query, including progress and bytes scanned.

  • query_insights_response(Option<QueryInsightsResponse>):

    Encapsulates QueryInsights containing insights and metrics related to the query that you executed.

• On failure, responds with SdkError<QueryError>

impl Client

pub fn tag_resource(&self) -> TagResourceFluentBuilder

Constructs a fluent builder for the TagResource operation.

• The fluent builder is configurable:
  • resource_arn(impl Into<String>) / set_resource_arn(Option<String>):
    required: true
    

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

    
    
  • tags(Tag) / set_tags(Option<Vec::<Tag>>):
    required: true
    

    The tags to be assigned to the Timestream resource.

    
    
• On success, responds with TagResourceOutput
• On failure, responds with SdkError<TagResourceError>

impl Client

pub fn untag_resource(&self) -> UntagResourceFluentBuilder

Constructs a fluent builder for the UntagResource operation.

• The fluent builder is configurable:
  • resource_arn(impl Into<String>) / set_resource_arn(Option<String>):
    required: true
    

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

    
    
  • tag_keys(impl Into<String>) / set_tag_keys(Option<Vec::<String>>):
    required: true
    

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

    
    
• On success, responds with UntagResourceOutput
• On failure, responds with SdkError<UntagResourceError>

impl Client

pub fn update_account_settings(&self) -> UpdateAccountSettingsFluentBuilder

Constructs a fluent builder for the UpdateAccountSettings operation.

• The fluent builder is configurable:
  • max_query_tcu(i32) / set_max_query_tcu(Option<i32>):
    required: false
    

    The maximum number of compute units the service will use at any point in time to serve your queries. To run queries, you must set a minimum capacity of 4 TCU. You can set the maximum number of TCU in multiples of 4, for example, 4, 8, 16, 32, and so on. The maximum value supported for MaxQueryTCU is 1000. To request an increase to this soft limit, contact Amazon Web Services Support. For information about the default quota for maxQueryTCU, see Default quotas. This configuration is applicable only for on-demand usage of Timestream Compute Units (TCUs).

    The maximum value supported for MaxQueryTCU is 1000. To request an increase to this soft limit, contact Amazon Web Services Support. For information about the default quota for maxQueryTCU, see Default quotas.

    
    
  • query_pricing_model(QueryPricingModel) / set_query_pricing_model(Option<QueryPricingModel>):
    required: false
    

    The pricing model for queries in an account.

    The QueryPricingModel parameter is used by several Timestream operations; however, the UpdateAccountSettings API operation doesn’t recognize any values other than COMPUTE_UNITS.

    
    
  • query_compute(QueryComputeRequest) / set_query_compute(Option<QueryComputeRequest>):
    required: false
    

    Modifies the query compute settings configured in your account, including the query pricing model and provisioned Timestream Compute Units (TCUs) in your account.

    This API is idempotent, meaning that making the same request multiple times will have the same effect as making the request once.

    
    
• On success, responds with UpdateAccountSettingsOutput with field(s):
  • max_query_tcu(Option<i32>):

    The configured maximum number of compute units the service will use at any point in time to serve your queries.

  • query_pricing_model(Option<QueryPricingModel>):

    The pricing model for an account.

  • query_compute(Option<QueryComputeResponse>):

    Confirms the updated account settings for querying data in your account.

• On failure, responds with SdkError<UpdateAccountSettingsError>

impl Client

pub fn update_scheduled_query(&self) -> UpdateScheduledQueryFluentBuilder

Constructs a fluent builder for the UpdateScheduledQuery operation.

• The fluent builder is configurable:
  • scheduled_query_arn(impl Into<String>) / set_scheduled_query_arn(Option<String>):
    required: true
    

    ARN of the scheuled query.

    
    
  • state(ScheduledQueryState) / set_state(Option<ScheduledQueryState>):
    required: true
    

    State of the scheduled query.

    
    
• On success, responds with UpdateScheduledQueryOutput
• On failure, responds with SdkError<UpdateScheduledQueryError>

impl Client

pub async fn with_endpoint_discovery_enabled( self, ) -> Result<(Self, ReloadEndpoint), BoxError>

Enable endpoint discovery for this client

This method MUST be called to construct a working client.

impl Client

pub fn from_conf(conf: Config) -> Self

Creates a new client from the service Config.

Panics

This method will panic in the following cases:

• Retries or timeouts are enabled without a sleep_impl configured.
• Identity caching is enabled without a sleep_impl and time_source configured.
• No behavior_version is provided.

The panic message for each of these will have instructions on how to resolve them.

pub fn config(&self) -> &Config

Returns the client’s configuration.

impl Client

pub fn new(sdk_config: &SdkConfig) -> Self

Creates a new client from an SDK Config.

Panics

• This method will panic if the sdk_config is missing an async sleep implementation. If you experience this panic, set the sleep_impl on the Config passed into this function to fix it.
• This method will panic if the sdk_config is missing an HTTP connector. If you experience this panic, set the http_connector on the Config passed into this function to fix it.
• This method will panic if no BehaviorVersion is provided. If you experience this panic, set behavior_version on the Config or enable the behavior-version-latest Cargo feature.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.