@aws-sdk/client-timestream-query 3.675.0 → 3.677.0

package/README.md

@@ -13,7 +13,7 @@ AWS SDK for JavaScript TimestreamQuery Client for Node.js, Browser and React Nat
 
 ## Installing
 
-To install the this package, simply type add or install @aws-sdk/client-timestream-query
+To install this package, simply type add or install @aws-sdk/client-timestream-query
 using your favorite package manager:
 
 - `npm install @aws-sdk/client-timestream-query`

package/dist-cjs/index.js

@@ -44,6 +44,7 @@ __export(src_exports, {
   PrepareQueryResponseFilterSensitiveLog: () => PrepareQueryResponseFilterSensitiveLog,
   QueryCommand: () => QueryCommand,
   QueryExecutionException: () => QueryExecutionException,
+  QueryInsightsMode: () => QueryInsightsMode,
   QueryPricingModel: () => QueryPricingModel,
   QueryRequestFilterSensitiveLog: () => QueryRequestFilterSensitiveLog,
   ResourceNotFoundException: () => ResourceNotFoundException,
@@ -51,6 +52,7 @@ __export(src_exports, {
   ScalarMeasureValueType: () => ScalarMeasureValueType,
   ScalarType: () => ScalarType,
   ScheduledQueryDescriptionFilterSensitiveLog: () => ScheduledQueryDescriptionFilterSensitiveLog,
+  ScheduledQueryInsightsMode: () => ScheduledQueryInsightsMode,
   ScheduledQueryRunStatus: () => ScheduledQueryRunStatus,
   ScheduledQueryState: () => ScheduledQueryState,
   ServiceQuotaExceededException: () => ServiceQuotaExceededException,
@@ -322,6 +324,10 @@ var ScheduledQueryState = {
   DISABLED: "DISABLED",
   ENABLED: "ENABLED"
 };
+var ScheduledQueryInsightsMode = {
+  DISABLED: "DISABLED",
+  ENABLED_WITH_RATE_CONTROL: "ENABLED_WITH_RATE_CONTROL"
+};
 var _QueryExecutionException = class _QueryExecutionException extends TimestreamQueryServiceException {
   /**
    * @internal
@@ -340,6 +346,10 @@ var _QueryExecutionException = class _QueryExecutionException extends Timestream
 };
 __name(_QueryExecutionException, "QueryExecutionException");
 var QueryExecutionException = _QueryExecutionException;
+var QueryInsightsMode = {
+  DISABLED: "DISABLED",
+  ENABLED_WITH_RATE_CONTROL: "ENABLED_WITH_RATE_CONTROL"
+};
 var CreateScheduledQueryRequestFilterSensitiveLog = /* @__PURE__ */ __name((obj) => ({
   ...obj,
   ...obj.QueryString && { QueryString: import_smithy_client.SENSITIVE_STRING },
@@ -790,6 +800,7 @@ var se_ExecuteScheduledQueryRequest = /* @__PURE__ */ __name((input, context) =>
   return (0, import_smithy_client.take)(input, {
     ClientToken: [true, (_) => _ ?? (0, import_uuid.v4)()],
     InvocationTime: (_) => _.getTime() / 1e3,
+    QueryInsights: import_smithy_client._json,
     ScheduledQueryArn: []
   });
 }, "se_ExecuteScheduledQueryRequest");
@@ -798,6 +809,7 @@ var se_QueryRequest = /* @__PURE__ */ __name((input, context) => {
     ClientToken: [true, (_) => _ ?? (0, import_uuid.v4)()],
     MaxRows: [],
     NextToken: [],
+    QueryInsights: import_smithy_client._json,
     QueryString: []
   });
 }, "se_QueryRequest");
@@ -858,15 +870,40 @@ var de_PrepareQueryResponse = /* @__PURE__ */ __name((output, context) => {
     QueryString: import_smithy_client.expectString
   });
 }, "de_PrepareQueryResponse");
+var de_QueryInsightsResponse = /* @__PURE__ */ __name((output, context) => {
+  return (0, import_smithy_client.take)(output, {
+    OutputBytes: import_smithy_client.expectLong,
+    OutputRows: import_smithy_client.expectLong,
+    QuerySpatialCoverage: (_) => de_QuerySpatialCoverage(_, context),
+    QueryTableCount: import_smithy_client.expectLong,
+    QueryTemporalRange: import_smithy_client._json,
+    UnloadPartitionCount: import_smithy_client.expectLong,
+    UnloadWrittenBytes: import_smithy_client.expectLong,
+    UnloadWrittenRows: import_smithy_client.expectLong
+  });
+}, "de_QueryInsightsResponse");
 var de_QueryResponse = /* @__PURE__ */ __name((output, context) => {
   return (0, import_smithy_client.take)(output, {
     ColumnInfo: (_) => de_ColumnInfoList(_, context),
     NextToken: import_smithy_client.expectString,
     QueryId: import_smithy_client.expectString,
+    QueryInsightsResponse: (_) => de_QueryInsightsResponse(_, context),
     QueryStatus: (_) => de_QueryStatus(_, context),
     Rows: (_) => de_RowList(_, context)
   });
 }, "de_QueryResponse");
+var de_QuerySpatialCoverage = /* @__PURE__ */ __name((output, context) => {
+  return (0, import_smithy_client.take)(output, {
+    Max: (_) => de_QuerySpatialCoverageMax(_, context)
+  });
+}, "de_QuerySpatialCoverage");
+var de_QuerySpatialCoverageMax = /* @__PURE__ */ __name((output, context) => {
+  return (0, import_smithy_client.take)(output, {
+    PartitionKey: import_smithy_client._json,
+    TableArn: import_smithy_client.expectString,
+    Value: import_smithy_client.limitedParseDouble
+  });
+}, "de_QuerySpatialCoverageMax");
 var de_QueryStatus = /* @__PURE__ */ __name((output, context) => {
   return (0, import_smithy_client.take)(output, {
     CumulativeBytesMetered: import_smithy_client.expectLong,
@@ -917,6 +954,15 @@ var de_ScheduledQueryDescription = /* @__PURE__ */ __name((output, context) => {
     TargetConfiguration: import_smithy_client._json
   });
 }, "de_ScheduledQueryDescription");
+var de_ScheduledQueryInsightsResponse = /* @__PURE__ */ __name((output, context) => {
+  return (0, import_smithy_client.take)(output, {
+    OutputBytes: import_smithy_client.expectLong,
+    OutputRows: import_smithy_client.expectLong,
+    QuerySpatialCoverage: (_) => de_QuerySpatialCoverage(_, context),
+    QueryTableCount: import_smithy_client.expectLong,
+    QueryTemporalRange: import_smithy_client._json
+  });
+}, "de_ScheduledQueryInsightsResponse");
 var de_ScheduledQueryList = /* @__PURE__ */ __name((output, context) => {
   const retVal = (output || []).filter((e) => e != null).map((entry) => {
     return de_ScheduledQuery(entry, context);
@@ -929,6 +975,7 @@ var de_ScheduledQueryRunSummary = /* @__PURE__ */ __name((output, context) => {
     ExecutionStats: import_smithy_client._json,
     FailureReason: import_smithy_client.expectString,
     InvocationTime: (_) => (0, import_smithy_client.expectNonNull)((0, import_smithy_client.parseEpochTimestamp)((0, import_smithy_client.expectNumber)(_))),
+    QueryInsightsResponse: (_) => de_ScheduledQueryInsightsResponse(_, context),
     RunStatus: import_smithy_client.expectString,
     TriggerTime: (_) => (0, import_smithy_client.expectNonNull)((0, import_smithy_client.parseEpochTimestamp)((0, import_smithy_client.expectNumber)(_)))
   });
@@ -1489,7 +1536,9 @@ var paginateQuery = (0, import_core5.createPaginator)(TimestreamQueryClient, Que
   QueryPricingModel,
   ScheduledQueryRunStatus,
   ScheduledQueryState,
+  ScheduledQueryInsightsMode,
   QueryExecutionException,
+  QueryInsightsMode,
   CreateScheduledQueryRequestFilterSensitiveLog,
   ScheduledQueryDescriptionFilterSensitiveLog,
   DescribeScheduledQueryResponseFilterSensitiveLog,

package/dist-es/models/models_0.js

@@ -153,6 +153,10 @@ export const ScheduledQueryState = {
     DISABLED: "DISABLED",
     ENABLED: "ENABLED",
 };
+export const ScheduledQueryInsightsMode = {
+    DISABLED: "DISABLED",
+    ENABLED_WITH_RATE_CONTROL: "ENABLED_WITH_RATE_CONTROL",
+};
 export class QueryExecutionException extends __BaseException {
     constructor(opts) {
         super({
@@ -166,6 +170,10 @@ export class QueryExecutionException extends __BaseException {
         this.Message = opts.Message;
     }
 }
+export const QueryInsightsMode = {
+    DISABLED: "DISABLED",
+    ENABLED_WITH_RATE_CONTROL: "ENABLED_WITH_RATE_CONTROL",
+};
 export const CreateScheduledQueryRequestFilterSensitiveLog = (obj) => ({
     ...obj,
     ...(obj.QueryString && { QueryString: SENSITIVE_STRING }),

package/dist-es/protocols/Aws_json1_0.js

@@ -422,6 +422,7 @@ const se_ExecuteScheduledQueryRequest = (input, context) => {
     return take(input, {
         ClientToken: [true, (_) => _ ?? generateIdempotencyToken()],
         InvocationTime: (_) => _.getTime() / 1000,
+        QueryInsights: _json,
         ScheduledQueryArn: [],
     });
 };
@@ -430,6 +431,7 @@ const se_QueryRequest = (input, context) => {
         ClientToken: [true, (_) => _ ?? generateIdempotencyToken()],
         MaxRows: [],
         NextToken: [],
+        QueryInsights: _json,
         QueryString: [],
     });
 };
@@ -496,15 +498,40 @@ const de_PrepareQueryResponse = (output, context) => {
         QueryString: __expectString,
     });
 };
+const de_QueryInsightsResponse = (output, context) => {
+    return take(output, {
+        OutputBytes: __expectLong,
+        OutputRows: __expectLong,
+        QuerySpatialCoverage: (_) => de_QuerySpatialCoverage(_, context),
+        QueryTableCount: __expectLong,
+        QueryTemporalRange: _json,
+        UnloadPartitionCount: __expectLong,
+        UnloadWrittenBytes: __expectLong,
+        UnloadWrittenRows: __expectLong,
+    });
+};
 const de_QueryResponse = (output, context) => {
     return take(output, {
         ColumnInfo: (_) => de_ColumnInfoList(_, context),
         NextToken: __expectString,
         QueryId: __expectString,
+        QueryInsightsResponse: (_) => de_QueryInsightsResponse(_, context),
         QueryStatus: (_) => de_QueryStatus(_, context),
         Rows: (_) => de_RowList(_, context),
     });
 };
+const de_QuerySpatialCoverage = (output, context) => {
+    return take(output, {
+        Max: (_) => de_QuerySpatialCoverageMax(_, context),
+    });
+};
+const de_QuerySpatialCoverageMax = (output, context) => {
+    return take(output, {
+        PartitionKey: _json,
+        TableArn: __expectString,
+        Value: __limitedParseDouble,
+    });
+};
 const de_QueryStatus = (output, context) => {
     return take(output, {
         CumulativeBytesMetered: __expectLong,
@@ -557,6 +584,15 @@ const de_ScheduledQueryDescription = (output, context) => {
         TargetConfiguration: _json,
     });
 };
+const de_ScheduledQueryInsightsResponse = (output, context) => {
+    return take(output, {
+        OutputBytes: __expectLong,
+        OutputRows: __expectLong,
+        QuerySpatialCoverage: (_) => de_QuerySpatialCoverage(_, context),
+        QueryTableCount: __expectLong,
+        QueryTemporalRange: _json,
+    });
+};
 const de_ScheduledQueryList = (output, context) => {
     const retVal = (output || [])
         .filter((e) => e != null)
@@ -571,6 +607,7 @@ const de_ScheduledQueryRunSummary = (output, context) => {
         ExecutionStats: _json,
         FailureReason: __expectString,
         InvocationTime: (_) => __expectNonNull(__parseEpochTimestamp(__expectNumber(_))),
+        QueryInsightsResponse: (_) => de_ScheduledQueryInsightsResponse(_, context),
         RunStatus: __expectString,
         TriggerTime: (_) => __expectNonNull(__parseEpochTimestamp(__expectNumber(_))),
     });

package/dist-types/commands/DescribeScheduledQueryCommand.d.ts

@@ -116,6 +116,26 @@ declare const DescribeScheduledQueryCommand_base: {
  * //         RecordsIngested: Number("long"),
  * //         QueryResultRows: Number("long"),
  * //       },
+ * //       QueryInsightsResponse: { // ScheduledQueryInsightsResponse
+ * //         QuerySpatialCoverage: { // QuerySpatialCoverage
+ * //           Max: { // QuerySpatialCoverageMax
+ * //             Value: Number("double"),
+ * //             TableArn: "STRING_VALUE",
+ * //             PartitionKey: [ // PartitionKeyList
+ * //               "STRING_VALUE",
+ * //             ],
+ * //           },
+ * //         },
+ * //         QueryTemporalRange: { // QueryTemporalRange
+ * //           Max: { // QueryTemporalRangeMax
+ * //             Value: Number("long"),
+ * //             TableArn: "STRING_VALUE",
+ * //           },
+ * //         },
+ * //         QueryTableCount: Number("long"),
+ * //         OutputRows: Number("long"),
+ * //         OutputBytes: Number("long"),
+ * //       },
  * //       ErrorReportLocation: { // ErrorReportLocation
  * //         S3ReportLocation: { // S3ReportLocation
  * //           BucketName: "STRING_VALUE",
@@ -137,6 +157,26 @@ declare const DescribeScheduledQueryCommand_base: {
  * //           RecordsIngested: Number("long"),
  * //           QueryResultRows: Number("long"),
  * //         },
+ * //         QueryInsightsResponse: {
+ * //           QuerySpatialCoverage: {
+ * //             Max: {
+ * //               Value: Number("double"),
+ * //               TableArn: "STRING_VALUE",
+ * //               PartitionKey: [
+ * //                 "STRING_VALUE",
+ * //               ],
+ * //             },
+ * //           },
+ * //           QueryTemporalRange: {
+ * //             Max: {
+ * //               Value: Number("long"),
+ * //               TableArn: "STRING_VALUE",
+ * //             },
+ * //           },
+ * //           QueryTableCount: Number("long"),
+ * //           OutputRows: Number("long"),
+ * //           OutputBytes: Number("long"),
+ * //         },
  * //         ErrorReportLocation: {
  * //           S3ReportLocation: {
  * //             BucketName: "STRING_VALUE",

package/dist-types/commands/ExecuteScheduledQueryCommand.d.ts

@@ -28,6 +28,7 @@ declare const ExecuteScheduledQueryCommand_base: {
 };
 /**
  * <p> You can use this API to run a scheduled query manually. </p>
+ *          <p>If you enabled <code>QueryInsights</code>, this API also returns insights and metrics related to the query that you executed as part of an Amazon SNS notification. <code>QueryInsights</code> helps with performance tuning of your query.</p>
  * @example
  * Use a bare-bones client and the command you need to make an API call.
  * ```javascript
@@ -38,6 +39,9 @@ declare const ExecuteScheduledQueryCommand_base: {
  *   ScheduledQueryArn: "STRING_VALUE", // required
  *   InvocationTime: new Date("TIMESTAMP"), // required
  *   ClientToken: "STRING_VALUE",
+ *   QueryInsights: { // ScheduledQueryInsights
+ *     Mode: "ENABLED_WITH_RATE_CONTROL" || "DISABLED", // required
+ *   },
  * };
  * const command = new ExecuteScheduledQueryCommand(input);
  * const response = await client.send(command);

package/dist-types/commands/QueryCommand.d.ts

@@ -29,7 +29,13 @@ declare const QueryCommand_base: {
 /**
  * <p>
  *             <code>Query</code> is a synchronous operation that enables you to run a query against
- *             your Amazon Timestream data. <code>Query</code> will time out after 60 seconds.
+ *             your Amazon Timestream data.</p>
+ *          <p>If you enabled <code>QueryInsights</code>, this API also returns insights and metrics related to the query that you executed. <code>QueryInsights</code> helps with performance tuning of your query.</p>
+ *          <note>
+ *             <p>The maximum number of <code>Query</code> API requests you're allowed to make with <code>QueryInsights</code> enabled is 1 query per second (QPS). If you exceed this query rate, it might result in throttling.</p>
+ *          </note>
+ *          <p>
+ *             <code>Query</code> will time out after 60 seconds.
  *             You must update the default timeout in the SDK to support a timeout of 60 seconds. See
  *             the <a href="https://docs.aws.amazon.com/timestream/latest/developerguide/code-samples.run-query.html">code
  *                 sample</a> for details. </p>
@@ -69,6 +75,9 @@ declare const QueryCommand_base: {
  *   ClientToken: "STRING_VALUE",
  *   NextToken: "STRING_VALUE",
  *   MaxRows: Number("int"),
+ *   QueryInsights: { // QueryInsights
+ *     Mode: "ENABLED_WITH_RATE_CONTROL" || "DISABLED", // required
+ *   },
  * };
  * const command = new QueryCommand(input);
  * const response = await client.send(command);
@@ -134,6 +143,29 @@ declare const QueryCommand_base: {
  * //     CumulativeBytesScanned: Number("long"),
  * //     CumulativeBytesMetered: Number("long"),
  * //   },
+ * //   QueryInsightsResponse: { // QueryInsightsResponse
+ * //     QuerySpatialCoverage: { // QuerySpatialCoverage
+ * //       Max: { // QuerySpatialCoverageMax
+ * //         Value: Number("double"),
+ * //         TableArn: "STRING_VALUE",
+ * //         PartitionKey: [ // PartitionKeyList
+ * //           "STRING_VALUE",
+ * //         ],
+ * //       },
+ * //     },
+ * //     QueryTemporalRange: { // QueryTemporalRange
+ * //       Max: { // QueryTemporalRangeMax
+ * //         Value: Number("long"),
+ * //         TableArn: "STRING_VALUE",
+ * //       },
+ * //     },
+ * //     QueryTableCount: Number("long"),
+ * //     OutputRows: Number("long"),
+ * //     OutputBytes: Number("long"),
+ * //     UnloadPartitionCount: Number("long"),
+ * //     UnloadWrittenRows: Number("long"),
+ * //     UnloadWrittenBytes: Number("long"),
+ * //   },
  * // };
  *
  * ```

package/dist-types/models/models_0.d.ts

@@ -696,6 +696,140 @@ export interface ExecutionStats {
      */
     QueryResultRows?: number;
 }
+/**
+ * <p>Provides insights into the table with the most sub-optimal spatial range scanned by your query.</p>
+ * @public
+ */
+export interface QuerySpatialCoverageMax {
+    /**
+     * <p>The maximum ratio of spatial coverage.</p>
+     * @public
+     */
+    Value?: number;
+    /**
+     * <p>The Amazon Resource Name (ARN) of the table with the most sub-optimal spatial pruning.</p>
+     * @public
+     */
+    TableArn?: string;
+    /**
+     * <p>The partition key used for partitioning, which can be a default <code>measure_name</code> or a <a href="https://docs.aws.amazon.com/timestream/latest/developerguide/customer-defined-partition-keys.html">customer defined partition key</a>.</p>
+     * @public
+     */
+    PartitionKey?: string[];
+}
+/**
+ * <p>Provides insights into the spatial coverage of the query, including the table with sub-optimal (max) spatial pruning. This information can help you identify areas for improvement in your partitioning strategy to enhance spatial pruning</p>
+ *          <p>For example, you can do the following with the <code>QuerySpatialCoverage</code> information:</p>
+ *          <ul>
+ *             <li>
+ *                <p>Add measure_name or use <a href="https://docs.aws.amazon.com/timestream/latest/developerguide/customer-defined-partition-keys.html">customer-defined partition key</a> (CDPK) predicates.</p>
+ *             </li>
+ *             <li>
+ *                <p>If you've already done the preceding action, remove functions around them or clauses, such as <code>LIKE</code>.</p>
+ *             </li>
+ *          </ul>
+ * @public
+ */
+export interface QuerySpatialCoverage {
+    /**
+     * <p>Provides insights into the spatial coverage of the executed query and the table with the most inefficient spatial pruning.</p>
+     *          <ul>
+     *             <li>
+     *                <p>
+     *                   <code>Value</code> – The maximum ratio of spatial coverage.</p>
+     *             </li>
+     *             <li>
+     *                <p>
+     *                   <code>TableArn</code> – The Amazon Resource Name (ARN) of the table with sub-optimal spatial pruning.</p>
+     *             </li>
+     *             <li>
+     *                <p>
+     *                   <code>PartitionKey</code> – The partition key used for partitioning, which can be a default <code>measure_name</code> or a CDPK.</p>
+     *             </li>
+     *          </ul>
+     * @public
+     */
+    Max?: QuerySpatialCoverageMax;
+}
+/**
+ * <p>Provides insights into the table with the most sub-optimal temporal pruning scanned by your query.</p>
+ * @public
+ */
+export interface QueryTemporalRangeMax {
+    /**
+     * <p>The maximum duration in nanoseconds between the start and end of the query.</p>
+     * @public
+     */
+    Value?: number;
+    /**
+     * <p>The Amazon Resource Name (ARN) of the table which is queried with the largest time range.</p>
+     * @public
+     */
+    TableArn?: string;
+}
+/**
+ * <p>Provides insights into the temporal range of the query, including the table with the largest (max) time range.</p>
+ * @public
+ */
+export interface QueryTemporalRange {
+    /**
+     * <p>Encapsulates the following properties that provide insights into the most sub-optimal performing table on the temporal axis:</p>
+     *          <ul>
+     *             <li>
+     *                <p>
+     *                   <code>Value</code> – The maximum duration in nanoseconds between the start and end of the query.</p>
+     *             </li>
+     *             <li>
+     *                <p>
+     *                   <code>TableArn</code> – The Amazon Resource Name (ARN) of the table which is queried with the largest time range.</p>
+     *             </li>
+     *          </ul>
+     * @public
+     */
+    Max?: QueryTemporalRangeMax;
+}
+/**
+ * <p>Provides various insights and metrics related to the <code>ExecuteScheduledQueryRequest</code> that was executed.</p>
+ * @public
+ */
+export interface ScheduledQueryInsightsResponse {
+    /**
+     * <p>Provides insights into the spatial coverage of the query, including the table with sub-optimal (max) spatial pruning. This information can help you identify areas for improvement in your partitioning strategy to enhance spatial pruning.</p>
+     * @public
+     */
+    QuerySpatialCoverage?: QuerySpatialCoverage;
+    /**
+     * <p>Provides insights into the temporal range of the query, including the table with the largest (max) time range. Following are some of the potential options for optimizing time-based pruning:</p>
+     *          <ul>
+     *             <li>
+     *                <p>Add missing time-predicates.</p>
+     *             </li>
+     *             <li>
+     *                <p>Remove functions around the time predicates.</p>
+     *             </li>
+     *             <li>
+     *                <p>Add time predicates to all the sub-queries.</p>
+     *             </li>
+     *          </ul>
+     * @public
+     */
+    QueryTemporalRange?: QueryTemporalRange;
+    /**
+     * <p>Indicates the number of tables in the query.</p>
+     * @public
+     */
+    QueryTableCount?: number;
+    /**
+     * <p>Indicates the total number of rows returned as part of the query result set. You can use this data to validate if the number of rows in the result set have changed as part of the query tuning exercise.</p>
+     * @public
+     */
+    OutputRows?: number;
+    /**
+     * <p>Indicates the size of query result set in bytes. You can use this data to validate if the result set has changed as part of the query tuning exercise.</p>
+     * @public
+     */
+    OutputBytes?: number;
+}
 /**
  * @public
  * @enum
@@ -737,6 +871,11 @@ export interface ScheduledQueryRunSummary {
      * @public
      */
     ExecutionStats?: ExecutionStats;
+    /**
+     * <p>Provides various insights and metrics related to the run summary of the scheduled query.</p>
+     * @public
+     */
+    QueryInsightsResponse?: ScheduledQueryInsightsResponse;
     /**
      * <p>S3 location for error report.</p>
      * @public
@@ -852,6 +991,39 @@ export interface DescribeScheduledQueryResponse {
      */
     ScheduledQuery: ScheduledQueryDescription | undefined;
 }
+/**
+ * @public
+ * @enum
+ */
+export declare const ScheduledQueryInsightsMode: {
+    readonly DISABLED: "DISABLED";
+    readonly ENABLED_WITH_RATE_CONTROL: "ENABLED_WITH_RATE_CONTROL";
+};
+/**
+ * @public
+ */
+export type ScheduledQueryInsightsMode = (typeof ScheduledQueryInsightsMode)[keyof typeof ScheduledQueryInsightsMode];
+/**
+ * <p>Encapsulates settings for enabling <code>QueryInsights</code> on an <code>ExecuteScheduledQueryRequest</code>.</p>
+ * @public
+ */
+export interface ScheduledQueryInsights {
+    /**
+     * <p>Provides the following modes to enable <code>ScheduledQueryInsights</code>:</p>
+     *          <ul>
+     *             <li>
+     *                <p>
+     *                   <code>ENABLED_WITH_RATE_CONTROL</code> – Enables <code>ScheduledQueryInsights</code> for the queries being processed. This mode also includes a rate control mechanism, which limits the <code>QueryInsights</code> feature to 1 query per second (QPS).</p>
+     *             </li>
+     *             <li>
+     *                <p>
+     *                   <code>DISABLED</code> – Disables <code>ScheduledQueryInsights</code>.</p>
+     *             </li>
+     *          </ul>
+     * @public
+     */
+    Mode: ScheduledQueryInsightsMode | undefined;
+}
 /**
  * @public
  */
@@ -872,6 +1044,12 @@ export interface ExecuteScheduledQueryRequest {
      * @public
      */
     ClientToken?: string;
+    /**
+     * <p>Encapsulates settings for enabling <code>QueryInsights</code>.</p>
+     *          <p>Enabling <code>QueryInsights</code> returns insights and metrics as a part of the Amazon SNS notification for the query that you executed. You can use <code>QueryInsights</code> to tune your query performance and cost.</p>
+     * @public
+     */
+    QueryInsights?: ScheduledQueryInsights;
 }
 /**
  * @public
@@ -1056,6 +1234,62 @@ export declare class QueryExecutionException extends __BaseException {
      */
     constructor(opts: __ExceptionOptionType<QueryExecutionException, __BaseException>);
 }
+/**
+ * @public
+ * @enum
+ */
+export declare const QueryInsightsMode: {
+    readonly DISABLED: "DISABLED";
+    readonly ENABLED_WITH_RATE_CONTROL: "ENABLED_WITH_RATE_CONTROL";
+};
+/**
+ * @public
+ */
+export type QueryInsightsMode = (typeof QueryInsightsMode)[keyof typeof QueryInsightsMode];
+/**
+ * <p>
+ *             <code>QueryInsights</code> is a performance tuning feature that helps you optimize your queries, reducing costs and improving performance. With <code>QueryInsights</code>, you can assess the pruning efficiency of your queries and identify areas for improvement to enhance query performance. With <code>QueryInsights</code>, you can also analyze the effectiveness of your queries in terms of temporal and spatial pruning, and identify opportunities to improve performance. Specifically, you can evaluate how well your queries use time-based and partition key-based indexing strategies to optimize data retrieval. To optimize query performance, it's essential that you fine-tune both the temporal and spatial parameters that govern query execution.</p>
+ *          <p>The key metrics provided by <code>QueryInsights</code> are <code>QuerySpatialCoverage</code> and <code>QueryTemporalRange</code>. <code>QuerySpatialCoverage</code> indicates how much of the spatial axis the query scans, with lower values being more efficient. <code>QueryTemporalRange</code> shows the time range scanned, with narrower ranges being more performant.</p>
+ *          <p>
+ *             <b>Benefits of QueryInsights</b>
+ *          </p>
+ *          <p>The following are the key benefits of using <code>QueryInsights</code>:</p>
+ *          <ul>
+ *             <li>
+ *                <p>
+ *                   <b>Identifying inefficient queries</b> – <code>QueryInsights</code> provides information on the time-based and attribute-based pruning of the tables accessed by the query. This information helps you identify the tables that are sub-optimally accessed.</p>
+ *             </li>
+ *             <li>
+ *                <p>
+ *                   <b>Optimizing your data model and partitioning</b> – You can use the <code>QueryInsights</code> information to access and fine-tune your data model and partitioning strategy.</p>
+ *             </li>
+ *             <li>
+ *                <p>
+ *                   <b>Tuning queries</b> – <code>QueryInsights</code> highlights opportunities to use indexes more effectively.</p>
+ *             </li>
+ *          </ul>
+ *          <note>
+ *             <p>The maximum number of <code>Query</code> API requests you're allowed to make with <code>QueryInsights</code> enabled is 1 query per second (QPS). If you exceed this query rate, it might result in throttling.</p>
+ *          </note>
+ * @public
+ */
+export interface QueryInsights {
+    /**
+     * <p>Provides the following modes to enable <code>QueryInsights</code>:</p>
+     *          <ul>
+     *             <li>
+     *                <p>
+     *                   <code>ENABLED_WITH_RATE_CONTROL</code> – Enables <code>QueryInsights</code> for the queries being processed. This mode also includes a rate control mechanism, which limits the <code>QueryInsights</code> feature to 1 query per second (QPS).</p>
+     *             </li>
+     *             <li>
+     *                <p>
+     *                   <code>DISABLED</code> – Disables <code>QueryInsights</code>.</p>
+     *             </li>
+     *          </ul>
+     * @public
+     */
+    Mode: QueryInsightsMode | undefined;
+}
 /**
  * @public
  */
@@ -1163,6 +1397,69 @@ export interface QueryRequest {
      * @public
      */
     MaxRows?: number;
+    /**
+     * <p>Encapsulates settings for enabling <code>QueryInsights</code>.</p>
+     *          <p>Enabling <code>QueryInsights</code> returns insights and metrics in addition to query results for the query that you executed. You can use <code>QueryInsights</code> to tune your query performance.</p>
+     * @public
+     */
+    QueryInsights?: QueryInsights;
+}
+/**
+ * <p>Provides various insights and metrics related to the query that you executed.</p>
+ * @public
+ */
+export interface QueryInsightsResponse {
+    /**
+     * <p>Provides insights into the spatial coverage of the query, including the table with sub-optimal (max) spatial pruning. This information can help you identify areas for improvement in your partitioning strategy to enhance spatial pruning. </p>
+     * @public
+     */
+    QuerySpatialCoverage?: QuerySpatialCoverage;
+    /**
+     * <p>Provides insights into the temporal range of the query, including the table with the largest (max) time range. Following are some of the potential options for optimizing time-based pruning:</p>
+     *          <ul>
+     *             <li>
+     *                <p>Add missing time-predicates.</p>
+     *             </li>
+     *             <li>
+     *                <p>Remove functions around the time predicates.</p>
+     *             </li>
+     *             <li>
+     *                <p>Add time predicates to all the sub-queries.</p>
+     *             </li>
+     *          </ul>
+     * @public
+     */
+    QueryTemporalRange?: QueryTemporalRange;
+    /**
+     * <p>Indicates the number of tables in the query.</p>
+     * @public
+     */
+    QueryTableCount?: number;
+    /**
+     * <p>Indicates the total number of rows returned as part of the query result set. You can use this data to validate if the number of rows in the result set have changed as part of the query tuning exercise.</p>
+     * @public
+     */
+    OutputRows?: number;
+    /**
+     * <p>Indicates the size of query result set in bytes. You can use this data to validate if the result set has changed as part of the query tuning exercise.</p>
+     * @public
+     */
+    OutputBytes?: number;
+    /**
+     * <p>Indicates the partitions created by the <code>Unload</code> operation.</p>
+     * @public
+     */
+    UnloadPartitionCount?: number;
+    /**
+     * <p>Indicates the rows written by the <code>Unload</code> query.</p>
+     * @public
+     */
+    UnloadWrittenRows?: number;
+    /**
+     * <p>Indicates the size, in bytes, written by the <code>Unload</code> operation.</p>
+     * @public
+     */
+    UnloadWrittenBytes?: number;
 }
 /**
  * <p>Information about the status of the query, including progress and bytes
@@ -1479,6 +1776,11 @@ export interface QueryResponse {
      * @public
      */
     QueryStatus?: QueryStatus;
+    /**
+     * <p>Encapsulates <code>QueryInsights</code> containing insights and metrics related to the query that you executed.</p>
+     * @public
+     */
+    QueryInsightsResponse?: QueryInsightsResponse;
 }
 /**
  * @public

package/dist-types/ts3.4/models/models_0.d.ts

@@ -220,6 +220,28 @@ export interface ExecutionStats {
   RecordsIngested?: number;
   QueryResultRows?: number;
 }
+export interface QuerySpatialCoverageMax {
+  Value?: number;
+  TableArn?: string;
+  PartitionKey?: string[];
+}
+export interface QuerySpatialCoverage {
+  Max?: QuerySpatialCoverageMax;
+}
+export interface QueryTemporalRangeMax {
+  Value?: number;
+  TableArn?: string;
+}
+export interface QueryTemporalRange {
+  Max?: QueryTemporalRangeMax;
+}
+export interface ScheduledQueryInsightsResponse {
+  QuerySpatialCoverage?: QuerySpatialCoverage;
+  QueryTemporalRange?: QueryTemporalRange;
+  QueryTableCount?: number;
+  OutputRows?: number;
+  OutputBytes?: number;
+}
 export declare const ScheduledQueryRunStatus: {
   readonly AUTO_TRIGGER_FAILURE: "AUTO_TRIGGER_FAILURE";
   readonly AUTO_TRIGGER_SUCCESS: "AUTO_TRIGGER_SUCCESS";
@@ -233,6 +255,7 @@ export interface ScheduledQueryRunSummary {
   TriggerTime?: Date;
   RunStatus?: ScheduledQueryRunStatus;
   ExecutionStats?: ExecutionStats;
+  QueryInsightsResponse?: ScheduledQueryInsightsResponse;
   ErrorReportLocation?: ErrorReportLocation;
   FailureReason?: string;
 }
@@ -262,10 +285,20 @@ export interface ScheduledQueryDescription {
 export interface DescribeScheduledQueryResponse {
   ScheduledQuery: ScheduledQueryDescription | undefined;
 }
+export declare const ScheduledQueryInsightsMode: {
+  readonly DISABLED: "DISABLED";
+  readonly ENABLED_WITH_RATE_CONTROL: "ENABLED_WITH_RATE_CONTROL";
+};
+export type ScheduledQueryInsightsMode =
+  (typeof ScheduledQueryInsightsMode)[keyof typeof ScheduledQueryInsightsMode];
+export interface ScheduledQueryInsights {
+  Mode: ScheduledQueryInsightsMode | undefined;
+}
 export interface ExecuteScheduledQueryRequest {
   ScheduledQueryArn: string | undefined;
   InvocationTime: Date | undefined;
   ClientToken?: string;
+  QueryInsights?: ScheduledQueryInsights;
 }
 export interface ListScheduledQueriesRequest {
   MaxResults?: number;
@@ -314,11 +347,31 @@ export declare class QueryExecutionException extends __BaseException {
     opts: __ExceptionOptionType<QueryExecutionException, __BaseException>
   );
 }
+export declare const QueryInsightsMode: {
+  readonly DISABLED: "DISABLED";
+  readonly ENABLED_WITH_RATE_CONTROL: "ENABLED_WITH_RATE_CONTROL";
+};
+export type QueryInsightsMode =
+  (typeof QueryInsightsMode)[keyof typeof QueryInsightsMode];
+export interface QueryInsights {
+  Mode: QueryInsightsMode | undefined;
+}
 export interface QueryRequest {
   QueryString: string | undefined;
   ClientToken?: string;
   NextToken?: string;
   MaxRows?: number;
+  QueryInsights?: QueryInsights;
+}
+export interface QueryInsightsResponse {
+  QuerySpatialCoverage?: QuerySpatialCoverage;
+  QueryTemporalRange?: QueryTemporalRange;
+  QueryTableCount?: number;
+  OutputRows?: number;
+  OutputBytes?: number;
+  UnloadPartitionCount?: number;
+  UnloadWrittenRows?: number;
+  UnloadWrittenBytes?: number;
 }
 export interface QueryStatus {
   ProgressPercentage?: number;
@@ -388,6 +441,7 @@ export interface QueryResponse {
   Rows: Row[] | undefined;
   ColumnInfo: ColumnInfo[] | undefined;
   QueryStatus?: QueryStatus;
+  QueryInsightsResponse?: QueryInsightsResponse;
 }
 export interface PrepareQueryResponse {
   QueryString: string | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aws-sdk/client-timestream-query",
   "description": "AWS SDK for JavaScript Timestream Query Client for Node.js, Browser and React Native",
-  "version": "3.675.0",
+  "version": "3.677.0",
   "scripts": {
     "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types'",
     "build:cjs": "node ../../scripts/compilation/inline client-timestream-query",
@@ -20,20 +20,20 @@
   "dependencies": {
     "@aws-crypto/sha256-browser": "5.2.0",
     "@aws-crypto/sha256-js": "5.2.0",
-    "@aws-sdk/client-sso-oidc": "3.675.0",
-    "@aws-sdk/client-sts": "3.675.0",
-    "@aws-sdk/core": "3.667.0",
-    "@aws-sdk/credential-provider-node": "3.675.0",
+    "@aws-sdk/client-sso-oidc": "3.677.0",
+    "@aws-sdk/client-sts": "3.677.0",
+    "@aws-sdk/core": "3.677.0",
+    "@aws-sdk/credential-provider-node": "3.677.0",
     "@aws-sdk/middleware-endpoint-discovery": "3.667.0",
     "@aws-sdk/middleware-host-header": "3.667.0",
     "@aws-sdk/middleware-logger": "3.667.0",
     "@aws-sdk/middleware-recursion-detection": "3.667.0",
-    "@aws-sdk/middleware-user-agent": "3.669.0",
+    "@aws-sdk/middleware-user-agent": "3.677.0",
     "@aws-sdk/region-config-resolver": "3.667.0",
     "@aws-sdk/types": "3.667.0",
     "@aws-sdk/util-endpoints": "3.667.0",
     "@aws-sdk/util-user-agent-browser": "3.675.0",
-    "@aws-sdk/util-user-agent-node": "3.669.0",
+    "@aws-sdk/util-user-agent-node": "3.677.0",
     "@smithy/config-resolver": "^3.0.9",
     "@smithy/core": "^2.4.8",
     "@smithy/fetch-http-handler": "^3.2.9",