Cloudflare.Basin reference

Table

Source: src/Cloudflare/Basin/Table.ts

An Apache Iceberg table in a Cloudflare Basin (R2 Data) catalog.

Declare the table’s schema with Effect Schema; Alchemy derives the Iceberg schema (String→string, Boolean→boolean, Int→long (int when bounded to 32 bits), Number→double, Date→timestamptz, Uint8Array→binary, arrays→list, Struct/Class→struct, Record→map, optional/nullable→not required). Additive schema changes evolve the table in place, keeping its UUID and field ids; destructive changes fail the plan. By default the table is retained when removed from the stack.

Writing to a table from a Pipelines sink and querying it with Basin SQL are not part of this resource yet.

Table: Creating a table

Table from an Effect Schema

const Order = Schema.Struct({
  id: Schema.String,
  amount: Schema.Number,
  at: Schema.Date,
  note: Schema.optional(Schema.String),
});

const bucket = yield* Cloudflare.R2.Bucket("Analytics");
const catalog = yield* Cloudflare.R2.DataCatalog("Catalog", {
  bucket,
});
const orders = yield* Cloudflare.Basin.Table("Orders", {
  catalog,
  namespace: "sales",
  schema: Order,
  partitionBy: ["day(at)"],
});
// orders.identifier → "sales.<generated name>"

Plain Iceberg column descriptors

const prices = yield* Cloudflare.Basin.Table("Prices", {
  catalog,
  namespace: "sales",
  name: "prices",
  schema: {
    fields: [
      { name: "sku", type: "string", required: true },
      { name: "price", type: "decimal(10, 2)" },
      { name: "day", type: "date" },
    ],
  },
});

Table: Evolving the schema

const Order = Schema.Struct({
  id: Schema.String,
  amount: Schema.Number,
  at: Schema.Date,
  note: Schema.optional(Schema.String),
  coupon: Schema.optional(Schema.String), // new: evolves the table
});

Table: Properties and maintenance

// Table maintenance needs the jobs enabled on the catalog first.
const catalog = yield* Cloudflare.R2.DataCatalog("Catalog", {
  bucket,
  compaction: { state: "enabled" },
  snapshotExpiration: { state: "enabled" },
  token: maintenanceToken,
});
const orders = yield* Cloudflare.Basin.Table("Orders", {
  catalog,
  namespace: "sales",
  schema: Order,
  properties: { "write.parquet.compression-codec": "zstd" },
  maintenance: {
    compaction: { targetSizeMb: "256" },
    snapshotExpiration: { olderThan: "7 days", retainLast: 10 },
  },
});

Table: Deleting

const scratch = yield* Cloudflare.Basin.Table("Scratch", {
  catalog,
  namespace: "tmp",
  schema: Order,
  delete: "purge",
});