Struct aws_sdk_timestreamquery::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 that can be set on the Config that is absent from SdkConfig, or slightly different settings for a specific client may be desired. The Config 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>):

    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>):

    Name of the scheduled query.

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

    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>):

    The schedule configuration for the query.

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

    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>):

    Configuration used for writing the result of a query.

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

    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>):

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

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

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

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

    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>):

    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(Option<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>):

    The ARN of the scheduled query.

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

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(Option<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>):

    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>):

    ARN of the scheduled query.

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

    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>):

    Not used.

• 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>):

    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>):

    A pagination token to resume pagination.

• On success, responds with ListScheduledQueriesOutput with field(s):
  • scheduled_queries(Option<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>):

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

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

    The maximum number of tags to return.

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

    A pagination token to resume pagination.

• On success, responds with ListTagsForResourceOutput with field(s):
  • tags(Option<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>):

    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>):

    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(Option<String>):

    The query string that you want prepare.

  • columns(Option<Vec<SelectColumn>>):

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

  • parameters(Option<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>):

    The query to be run by Timestream.

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

    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>):

    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>):

    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.

• On success, responds with QueryOutput with field(s):
  • query_id(Option<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(Option<Vec<Row>>):

    The result set rows returned by the query.

  • column_info(Option<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.

• 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>):

    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>>):

    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>):

    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>>):

    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_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>):

    ARN of the scheuled query.

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

    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), ResolveEndpointError>

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 if the conf has retry or timeouts enabled without a sleep_impl. If you experience this panic, it can be fixed by setting the sleep_impl, or by disabling retries and timeouts.

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.

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.