AWS.Timestream reference

CancelQuery

Source: src/AWS/Timestream/CancelQuery.ts

Runtime binding for timestream-query:CancelQuery — cancel a running query by the QueryId a previous Query call reported.

timestream:CancelQuery does not support resource-level permissions, so this is an account-level binding invoked with no resource argument.

Provide Timestream.CancelQueryHttp on the Function to implement the binding.

CancelQuery: Querying Data

// init — account-level binding, no resource argument
const cancelQuery = yield* Timestream.CancelQuery();

// runtime — cancel by the QueryId from a prior Query response
const result = yield* cancelQuery({ QueryId: queryId });
// result.CancellationMessage reports whether the query was still running

CreateBatchLoadTask

Source: src/AWS/Timestream/CreateBatchLoadTask.ts

Runtime binding for timestream-write:CreateBatchLoadTask — start a bulk CSV import from S3 into a Timestream Table.

Bind the operation to the target table to get a callable with TargetDatabaseName and TargetTableName injected automatically; you supply the S3 data source, the report location, and the data model. The binding grants timestream:CreateBatchLoadTask on the table and its database; grant the host S3 read on the source bucket and write on the report bucket separately (e.g. via the S3 capability bindings).

Provide Timestream.CreateBatchLoadTaskHttp on the Function to implement the binding.

CreateBatchLoadTask: Batch Loading

// init — bind the operation to the target table
const createBatchLoadTask = yield* Timestream.CreateBatchLoadTask(table);

// runtime — import CSV rows from S3
const task = yield* createBatchLoadTask({
  DataSourceConfiguration: {
    DataSourceS3Configuration: { BucketName: "my-ingest-bucket", ObjectKeyPrefix: "metrics/" },
    DataFormat: "CSV",
  },
  ReportConfiguration: {
    ReportS3Configuration: { BucketName: "my-report-bucket" },
  },
  DataModelConfiguration: { DataModel: { TimeColumn: "time", TimeUnit: "MILLISECONDS", DimensionMappings: [{ SourceColumn: "host" }], MeasureNameColumn: "measure" } },
});
// task.TaskId identifies the import for Describe/Resume

Database

Source: src/AWS/Timestream/Database.ts

An Amazon Timestream for LiveAnalytics database — the top-level container for time-series Tables.

Database owns the database’s lifecycle and its mutable configuration: the KMS key used for encryption at rest and its tags. A database name is auto-generated from the app, stage, and logical ID unless you provide one.

Note

Timestream for LiveAnalytics is closed to new AWS customers. Accounts that were not already onboarded receive TimestreamNotOnboarded (a specialized AccessDenied) on every operation.

Database: Creating Databases

Basic Database

import * as Timestream from "alchemy/AWS/Timestream";

const database = yield* Timestream.Database("Metrics");

Database with a Customer-Managed KMS Key

const database = yield* Timestream.Database("SecureMetrics", {
  kmsKeyId: "alias/my-timestream-key",
  tags: { Environment: "production" },
});

DbInstance

Source: src/AWS/Timestream/DbInstance.ts

An Amazon Timestream for InfluxDB DB instance — a managed, single-tenant InfluxDB engine for time-series workloads.

DbInstance owns the instance’s lifecycle and its mutable configuration (instance type, storage, port, parameter group, log delivery, deployment type, and tags). Networking (subnets, security groups), the initial credentials, organization, and bucket are fixed at creation.

Caution

Provisioning a DB instance takes ~15–20 minutes and incurs EC2-backed cost.

DbInstance: Creating DB Instances

import * as Timestream from "alchemy/AWS/Timestream";

const influx = yield* Timestream.DbInstance("Influx", {
  name: "my-influx",
  dbInstanceType: "db.influx.medium",
  allocatedStorage: 20,
  vpcSubnetIds: [subnetA.subnetId, subnetB.subnetId],
  vpcSecurityGroupIds: [securityGroup.groupId],
  password: Redacted.make("super-secret-password"),
});

DescribeBatchLoadTask

Source: src/AWS/Timestream/DescribeBatchLoadTask.ts

Runtime binding for timestream-write:DescribeBatchLoadTask — poll a bulk import started by CreateBatchLoadTask for its status and progress report.

Batch-load task reads are keyed by TaskId and authorized account-wide, so this is an account-level binding invoked with no resource argument.

Provide Timestream.DescribeBatchLoadTaskHttp on the Function to implement the binding.

DescribeBatchLoadTask: Batch Loading

// init — account-level binding, no resource argument
const describeBatchLoadTask = yield* Timestream.DescribeBatchLoadTask();

// runtime
const described = yield* describeBatchLoadTask({ TaskId: task.TaskId });
// described.BatchLoadTaskDescription?.TaskStatus === "SUCCEEDED"

ExecuteScheduledQuery

Source: src/AWS/Timestream/ExecuteScheduledQuery.ts

Runtime binding for timestream-query:ExecuteScheduledQuery — manually run a ScheduledQuery for a given invocation time (e.g. to backfill a window the schedule missed).

Bind the operation to the scheduled query to get a callable with ScheduledQueryArn injected automatically.

Provide Timestream.ExecuteScheduledQueryHttp on the Function to implement the binding.

ExecuteScheduledQuery: Creating Scheduled Queries

// init — bind the operation to the scheduled query
const executeScheduledQuery = yield* Timestream.ExecuteScheduledQuery(rollup);

// runtime — re-run the rollup as-of one hour ago
yield* executeScheduledQuery({
  InvocationTime: new Date(Date.now() - 60 * 60 * 1000),
});

ListBatchLoadTasks

Source: src/AWS/Timestream/ListBatchLoadTasks.ts

Runtime binding for timestream-write:ListBatchLoadTasks — enumerate the account’s bulk imports, optionally filtered by status.

Account-level binding invoked with no resource argument.

Provide Timestream.ListBatchLoadTasksHttp on the Function to implement the binding.

ListBatchLoadTasks: Batch Loading

// init — account-level binding, no resource argument
const listBatchLoadTasks = yield* Timestream.ListBatchLoadTasks();

// runtime
const tasks = yield* listBatchLoadTasks({ TaskStatus: "IN_PROGRESS" });
// tasks.BatchLoadTasks lists each task's TaskId and status

PrepareQuery

Source: src/AWS/Timestream/PrepareQuery.ts

Runtime binding for timestream-query:PrepareQuery — validate a SQL query against a Timestream Table and inspect its result schema and parameter mappings without running it.

Bind the operation to the table the SQL reads so the host is granted timestream:PrepareQuery and timestream:Select on it (plus the unscoped timestream:DescribeEndpoints the endpoint-discovery flow needs). The query string itself still references the database and table by name.

Provide Timestream.PrepareQueryHttp on the Function to implement the binding.

PrepareQuery: Querying Data

// init — bind the operation to the table the SQL reads
const prepareQuery = yield* Timestream.PrepareQuery(table);

// runtime — validate only; Columns/Parameters describe the result shape
const prepared = yield* prepareQuery({
  QueryString: `SELECT COUNT(*) AS c FROM "${databaseName}"."${tableName}"`,
  ValidateOnly: true,
});
// prepared.Columns[0].Name === "c"

Query

Source: src/AWS/Timestream/Query.ts

Runtime binding for timestream-query:Query — run SQL queries against a Timestream Table.

Bind the operation to a table inside a function runtime to get a callable that grants timestream:Select on the table (plus the unscoped timestream:DescribeEndpoints the endpoint-discovery flow needs). The query string itself still references the database and table by name.

Provide Timestream.QueryHttp on the Function to implement the binding.

Query: Querying Data

// init — bind the operation to the table
const query = yield* Timestream.Query(table);

// runtime — run a SQL query
const result = yield* query({
  QueryString: `SELECT COUNT(*) AS c FROM "${databaseName}"."${tableName}"`,
});
// result.Rows / result.ColumnInfo hold the result set

RecordsSink

Source: src/AWS/Timestream/RecordsSink.ts

A batching sink over Timestream WriteRecords (100 records per call).

Timestream ingests the valid subset of each batch and reports invalid records positionally via RejectedRecordsException (schema conflicts, timestamps outside the retention window, version conflicts). Rejections are permanent — the sink drops them (surfacing a warning with the rejected count) and keeps draining; there is no transient per-record failure mode to retry.

Provide Timestream.RecordsSinkHttp on the Function to implement the binding.

RecordsSink: Streaming Records

// init — bind the sink to the table; shared attributes are sent once per
// batch as CommonAttributes and merged into every record server-side
const sink = yield* Timestream.RecordsSink(table, {
  commonAttributes: {
    MeasureName: "cpu",
    MeasureValueType: "DOUBLE",
    TimeUnit: "MILLISECONDS",
  },
});

// runtime — drain a stream through the sink (batched 100 records/call)
yield* Stream.fromIterable(
  samples.map((s) => ({
    Dimensions: [{ Name: "host", Value: s.host }],
    MeasureValue: `${s.value}`,
    Time: `${s.time}`,
  })),
).pipe(Stream.run(sink));

ResumeBatchLoadTask

Source: src/AWS/Timestream/ResumeBatchLoadTask.ts

Runtime binding for timestream-write:ResumeBatchLoadTask — resume a bulk import that Timestream paused (e.g. after transient S3 or throttling failures).

Account-level binding invoked with no resource argument; keyed by TaskId.

Provide Timestream.ResumeBatchLoadTaskHttp on the Function to implement the binding.

ResumeBatchLoadTask: Batch Loading

// init — account-level binding, no resource argument
const resumeBatchLoadTask = yield* Timestream.ResumeBatchLoadTask();

// runtime
yield* resumeBatchLoadTask({ TaskId: task.TaskId });

ScheduledQuery

Source: src/AWS/Timestream/ScheduledQuery.ts

An Amazon Timestream for LiveAnalytics scheduled query — a SQL query Timestream runs on a cron/rate schedule, materializing results into a target table and notifying an SNS topic after each run.

Only the state (ENABLED/DISABLED) is mutable in place; changing the query, schedule, notification topic, role, target, error report location, or KMS key replaces the scheduled query. Tags sync in place.

Note

Timestream for LiveAnalytics is closed to new AWS customers. Accounts that were not already onboarded receive TimestreamNotOnboarded (a specialized AccessDenied) on every operation.

ScheduledQuery: Creating Scheduled Queries

Hourly Rollup

import * as Timestream from "alchemy/AWS/Timestream";

const rollup = yield* Timestream.ScheduledQuery("HourlyRollup", {
  queryString: `SELECT host, AVG(measure_value::double) AS avg_cpu
                FROM "metrics"."cpu"
                WHERE time > ago(1h) GROUP BY host`,
  scheduleExpression: "rate(1 hour)",
  notificationTopicArn: topic.topicArn,
  executionRoleArn: role.roleArn,
  errorReportS3: { bucketName: bucket.bucketName },
  targetConfiguration: {
    TimestreamConfiguration: {
      DatabaseName: database.databaseName,
      TableName: rollupTable.tableName,
      TimeColumn: "time",
      DimensionMappings: [{ Name: "host", DimensionValueType: "VARCHAR" }],
      MultiMeasureMappings: {
        TargetMultiMeasureName: "cpu_rollup",
        MultiMeasureAttributeMappings: [
          { SourceColumn: "avg_cpu", MeasureValueType: "DOUBLE" },
        ],
      },
    },
  },
});

Pausing a Schedule

const rollup = yield* Timestream.ScheduledQuery("HourlyRollup", {
  // ... unchanged configuration ...
  state: "DISABLED",
});

Table

Source: src/AWS/Timestream/Table.ts

An Amazon Timestream for LiveAnalytics table — a time-series store inside a Database.

Table owns the table’s lifecycle and its mutable configuration: memory and magnetic store retention, magnetic store write behavior, and tags. A table name is auto-generated from the app, stage, and logical ID unless you provide one.

Note

Timestream for LiveAnalytics is closed to new AWS customers. Accounts that were not already onboarded receive TimestreamNotOnboarded on every operation.

Table: Creating Tables

Basic Table

import * as Timestream from "alchemy/AWS/Timestream";

const database = yield* Timestream.Database("Metrics");
const table = yield* Timestream.Table("Cpu", {
  databaseName: database.databaseName,
});

Table with Retention Tuning

const table = yield* Timestream.Table("Cpu", {
  databaseName: database.databaseName,
  retentionProperties: {
    memoryStoreRetention: "24 hours",
    magneticStoreRetention: "365 days",
  },
});

Table: Writing Points

// init
const writeRecords = yield* Timestream.WriteRecords(table);

return {
  fetch: Effect.gen(function* () {
    // runtime
    yield* writeRecords({
      Records: [
        {
          Dimensions: [{ Name: "host", Value: "web-1" }],
          MeasureName: "cpu",
          MeasureValue: "42.0",
          MeasureValueType: "DOUBLE",
          Time: `${Date.now()}`,
          TimeUnit: "MILLISECONDS",
        },
      ],
    });
    return HttpServerResponse.text("ok");
  }),
};

WriteRecords

Source: src/AWS/Timestream/WriteRecords.ts

Runtime binding for timestream-write:WriteRecords — ingest time-series records into a Timestream Table.

Bind the operation to a table inside a function runtime to get a callable with DatabaseName and TableName injected automatically; you only supply the Records (and optional CommonAttributes). For high-volume streaming ingestion prefer the batching RecordsSink.

Provide Timestream.WriteRecordsHttp on the Function to implement the binding.

WriteRecords: Writing Records

// init — bind the operation to the table
const writeRecords = yield* Timestream.WriteRecords(table);

// runtime — ingest a record
const result = yield* writeRecords({
  Records: [
    {
      Dimensions: [{ Name: "host", Value: "web-1" }],
      MeasureName: "cpu",
      MeasureValue: "42.5",
      MeasureValueType: "DOUBLE",
      Time: `${Date.now()}`,
      TimeUnit: "MILLISECONDS",
    },
  ],
});
// result.RecordsIngested reports how many records landed