@sixb/ducklake 0.1.8 → 0.1.9

package/src/internal/ducklake-dataset-catalog.ts

@@ -1,9 +1,14 @@
 import { randomUUID } from "node:crypto"
 import type { DatasetDefinition, DatasetSchema } from "@sixb/core"
-import type { DatasetDefinitionUpdatePlan, DatasetSchemaUpdatePlan } from "@sixb/core/lake-storage"
+import type {
+  DatasetDefinitionUpdatePlan,
+  DatasetSchemaUpdatePlan,
+  DatasetVersionLineage,
+} from "@sixb/core/lake-storage"
 import {
   assertDatasetDefinition,
   LakeStorageError,
+  lineageAtCommit,
   planDatasetDefinitionUpdate,
 } from "@sixb/core/lake-storage"
 import type { DuckLakeStorageOptions } from "../types"
@@ -17,6 +22,15 @@ import {
 } from "./ducklake-catalog-schema"
 import type { DuckLakeConnectionManager } from "./ducklake-connection-manager"
 import { readCurrentDatasetDefinitions } from "./ducklake-current-dataset-definitions"
+import type { DatasetTableRef } from "./ducklake-dataset-table-ref"
+import type { DuckLakeVersionSummary } from "./ducklake-snapshot-reader"
+import {
+  beginTransactionOnLatestVersion,
+  commitVersionTransaction,
+  type LatestVersionAtSnapshot,
+  rerunWhenCatalogMoves,
+} from "./ducklake-version-transaction"
+import { encodeLineage } from "./lineage-encoding"
 import { encodeDatasetSequenceTableName, encodeDatasetTableName } from "./names"
 import { datasetColumnToDuckDbSql, datasetSchemaToDuckDbColumnsSql } from "./schema"
 import {
@@ -27,6 +41,28 @@ import {
   quoteSqlString,
 } from "./sql"
 
+/**
+ * Reads the latest version of a dataset, which a schema change keeps the rows of, as
+ * `BeginVersionTransactionInput.readLatestVersion`.
+ */
+export type LatestDatasetVersionReader = (
+  runtime: DuckDbQueryRuntime,
+  definition: DatasetDefinition
+) => Promise<LatestVersionAtSnapshot<DuckLakeVersionSummary>>
+
+export interface DatasetSchemaAtSnapshotRequest {
+  readonly table: DatasetTableRef
+  readonly snapshotId: string
+}
+
+/** A row of `ducklake_column`: one column of one table, alive over a snapshot range. */
+interface DuckLakeColumnVersion {
+  readonly tableId: bigint
+  readonly beginSnapshot: bigint
+  readonly endSnapshot?: bigint
+  readonly column: Omit<DuckLakeCatalogColumn, "tableName">
+}
+
 /**
  * Translates between Sixb dataset definitions and DuckLake table metadata.
  *
@@ -40,7 +76,10 @@ export class DuckLakeDatasetCatalog {
     private readonly connections: DuckLakeConnectionManager
   ) {}
 
-  async createDataset(definition: DatasetDefinition): Promise<DatasetDefinition> {
+  async createDataset(
+    definition: DatasetDefinition,
+    readLatestVersion: LatestDatasetVersionReader
+  ): Promise<DatasetDefinition> {
     this.assertSchema(definition)
 
     // Step 1: read the current DuckLake table back into Sixb shape. The
@@ -49,9 +88,25 @@ export class DuckLakeDatasetCatalog {
     const existing = await this.getDataset(definition.id)
 
     if (existing) {
-      const plan = planDatasetDefinitionUpdate(existing, definition)
+      // A schema change the catalog moved under, such as one another host applied concurrently,
+      // reruns from the stored definition: it may have nothing left to change.
+      const plan = await rerunWhenCatalogMoves(definition.id, async (attempt) => {
+        const current = attempt === 1 ? existing : await this.getDataset(definition.id)
+        if (!current) {
+          throw new LakeStorageError(
+            `[SixbDuckLake] Dataset '${definition.id}' was removed while its definition was updated.`
+          )
+        }
+
+        const plan = planDatasetDefinitionUpdate(current, definition)
+        if (plan.changed) {
+          await this.applyExistingDatasetUpdate(plan, readLatestVersion)
+        }
+
+        return plan
+      })
+
       if (plan.changed) {
-        await this.applyExistingDatasetUpdate(plan)
         this.connections.markLocalCatalogChanged()
         await this.connections.resetRuntime()
       }
@@ -201,23 +256,50 @@ export class DuckLakeDatasetCatalog {
     })
   }
 
-  async getDatasetSchemaAtSnapshot(
+  /**
+   * Dataset schemas at DuckLake snapshots, in request order, from one catalog read: a column row
+   * is visible from its begin_snapshot until its end_snapshot, so the rows alive anywhere between
+   * the oldest and the newest requested snapshot answer every request.
+   */
+  async getDatasetSchemasAtSnapshots(
     runtime: DuckDbQueryRuntime,
-    datasetId: string,
-    tableName: string,
-    tableId: bigint,
-    snapshotId: string
-  ): Promise<DatasetSchema> {
-    assertDuckLakeSnapshotId(snapshotId)
-
-    const columns = await this.readDatasetColumnsAtSnapshot(runtime, tableName, tableId, snapshotId)
-    if (columns.length === 0) {
-      throw new LakeStorageError(
-        `[SixbDuckLake] Could not reconstruct schema for dataset '${datasetId}' at DuckLake snapshot '${snapshotId}'.`
-      )
+    requests: readonly DatasetSchemaAtSnapshotRequest[]
+  ): Promise<readonly DatasetSchema[]> {
+    if (requests.length === 0) {
+      return []
     }
 
-    return duckLakeCatalogColumnsToDatasetSchema(tableName, columns)
+    for (const request of requests) {
+      assertDuckLakeSnapshotId(request.snapshotId)
+    }
+
+    const snapshots = requests.map((request) => BigInt(request.snapshotId))
+    const rows = await this.readDatasetColumnsBetweenSnapshots(
+      runtime,
+      requests.map((request) => request.table),
+      snapshots.reduce((oldest, snapshot) => (snapshot < oldest ? snapshot : oldest)),
+      snapshots.reduce((newest, snapshot) => (snapshot > newest ? snapshot : newest))
+    )
+
+    return requests.map(({ table, snapshotId }, index) => {
+      const snapshot = snapshots[index]
+      const columns = rows
+        .filter(
+          (row) =>
+            row.tableId === table.tableId &&
+            row.beginSnapshot <= snapshot &&
+            (row.endSnapshot === undefined || row.endSnapshot > snapshot)
+        )
+        .map((row) => ({ tableName: table.tableName, ...row.column }))
+
+      if (columns.length === 0) {
+        throw new LakeStorageError(
+          `[SixbDuckLake] Could not reconstruct schema for dataset '${table.datasetId}' at DuckLake snapshot '${snapshotId}'.`
+        )
+      }
+
+      return duckLakeCatalogColumnsToDatasetSchema(table.tableName, columns)
+    })
   }
 
   assertSchema(definition: DatasetDefinition): void {
@@ -227,27 +309,48 @@ export class DuckLakeDatasetCatalog {
     )
   }
 
-  private async applyExistingDatasetUpdate(plan: DatasetDefinitionUpdatePlan): Promise<void> {
+  private async applyExistingDatasetUpdate(
+    plan: DatasetDefinitionUpdatePlan,
+    readLatestVersion: LatestDatasetVersionReader
+  ): Promise<void> {
     const tableName = encodeDatasetTableName(plan.definition.id)
     const qualifiedName = qualifiedTableName(this.options, tableName)
+    const { schema } = plan
 
-    await this.connections.withExclusiveAttached(async (runtime) => {
-      if (plan.schema.kind === "none") {
-        await this.applyMetadataDelta(runtime, qualifiedName, plan)
-        return
-      }
+    if (schema.kind === "none") {
+      await this.connections.withExclusiveAttached((runtime) =>
+        this.applyMetadataDelta(runtime, qualifiedName, plan)
+      )
+      return
+    }
 
-      // Schema-only DuckLake snapshots still matter to Sixb. Apply schema and
-      // compatible metadata DDL atomically, then tag the commit so versions can
-      // treat it as this dataset's schema-change version.
-      await runtime.run("BEGIN TRANSACTION")
+    // Schema-only DuckLake snapshots still matter to Sixb. Apply schema and
+    // compatible metadata DDL atomically, then tag the commit so versions can
+    // treat it as this dataset's schema-change version. It keeps the rows of
+    // the latest version, and so its lineage. ALTER TABLE claims the table, and
+    // changes no rows: it commits on the snapshot it read, or fails and reruns.
+    await this.connections.withExclusiveAttached(async (runtime) => {
       let committed = false
       try {
-        await this.applySchemaEvolutionDdl(runtime, qualifiedName, plan.schema)
+        const parent = await beginTransactionOnLatestVersion({
+          options: this.options,
+          runtime,
+          datasetId: plan.definition.id,
+          readLatestVersion: () => readLatestVersion(runtime, plan.definition),
+        })
+
+        await this.applySchemaEvolutionDdl(runtime, qualifiedName, schema)
         await this.applyMetadataDelta(runtime, qualifiedName, plan)
-        await this.setSchemaEvolutionCommitMetadata(runtime, plan.definition.id, plan.schema)
+        await this.setSchemaEvolutionCommitMetadata(
+          runtime,
+          plan.definition.id,
+          schema,
+          lineageAtCommit({ mode: "schema", schema: plan.definition.schema, parent })
+        )
 
-        await runtime.run("COMMIT")
+        await commitVersionTransaction(runtime, plan.definition.id, {
+          poisonRuntime: () => this.connections.poisonRuntime(),
+        })
         committed = true
       } catch (error) {
         if (!committed) {
@@ -338,7 +441,8 @@ export class DuckLakeDatasetCatalog {
   private async setSchemaEvolutionCommitMetadata(
     runtime: DuckDbQueryRuntime,
     datasetId: string,
-    plan: Extract<DatasetSchemaUpdatePlan, { readonly kind: "addNullableColumns" }>
+    plan: Extract<DatasetSchemaUpdatePlan, { readonly kind: "addNullableColumns" }>,
+    lineage: DatasetVersionLineage | undefined
   ): Promise<void> {
     await runtime.run(
       `CALL ${quoteIdentifier(duckLakeAlias(this.options))}.set_commit_message(${quoteSqlString(
@@ -353,6 +457,7 @@ export class DuckLakeDatasetCatalog {
             schemaChange: {
               addColumns: plan.columns.map((column) => column.name),
             },
+            ...(lineage === undefined ? {} : { lineage: encodeLineage(lineage) }),
           },
         })
       )})`
@@ -368,36 +473,44 @@ export class DuckLakeDatasetCatalog {
     }
   }
 
-  private async readDatasetColumnsAtSnapshot(
+  private async readDatasetColumnsBetweenSnapshots(
     runtime: DuckDbQueryRuntime,
-    tableName: string,
-    tableId: bigint,
-    snapshotId: string
-  ): Promise<readonly DuckLakeCatalogColumn[]> {
+    tables: readonly DatasetTableRef[],
+    oldestSnapshot: bigint,
+    newestSnapshot: bigint
+  ): Promise<readonly DuckLakeColumnVersion[]> {
+    const tableIds = new Set(tables.map((table) => table.tableId))
     const ducklakeColumn = duckLakeMetadataTableName(this.options, "ducklake_column")
     const rows = await runtime.query(`
       SELECT
+        table_id,
         column_id,
         column_order,
         column_name,
         column_type,
         CAST(nulls_allowed AS BOOLEAN) AS nulls_allowed,
-        parent_column
+        parent_column,
+        begin_snapshot,
+        end_snapshot
       FROM ${ducklakeColumn}
-      WHERE table_id = ${tableId}
-        AND begin_snapshot <= ${snapshotId}
-        AND (end_snapshot IS NULL OR end_snapshot > ${snapshotId})
-      ORDER BY column_order
+      WHERE table_id IN (${[...tableIds].join(", ")})
+        AND begin_snapshot <= ${newestSnapshot}
+        AND (end_snapshot IS NULL OR end_snapshot > ${oldestSnapshot})
+      ORDER BY column_order, column_id
     `)
 
     return rows.map((row) => ({
-      tableName,
-      columnId: getBigIntLike(row, "column_id"),
-      columnOrder: getBigIntLike(row, "column_order"),
-      columnName: getString(row, "column_name"),
-      columnType: getString(row, "column_type"),
-      nullsAllowed: getBoolean(row, "nulls_allowed"),
-      parentColumnId: getOptionalBigIntLike(row, "parent_column"),
+      tableId: getBigIntLike(row, "table_id"),
+      beginSnapshot: getBigIntLike(row, "begin_snapshot"),
+      endSnapshot: getOptionalBigIntLike(row, "end_snapshot"),
+      column: {
+        columnId: getBigIntLike(row, "column_id"),
+        columnOrder: getBigIntLike(row, "column_order"),
+        columnName: getString(row, "column_name"),
+        columnType: getString(row, "column_type"),
+        nullsAllowed: getBoolean(row, "nulls_allowed"),
+        parentColumnId: getOptionalBigIntLike(row, "parent_column"),
+      },
     }))
   }
 }

package/src/internal/ducklake-dataset-table-ref.ts

@@ -1,13 +1,16 @@
+import { LakeStorageError } from "@sixb/core/lake-storage"
 import type { DuckLakeStorageOptions } from "../types"
 import { getBigIntLike } from "./duckdb-row"
 import type { DuckDbQueryRuntime } from "./duckdb-runtime"
-import { encodeDatasetTableName } from "./names"
-import { duckLakeMetadataTableName, quoteSqlString } from "./sql"
+import { encodeDatasetSequenceTableName, encodeDatasetTableName } from "./names"
+import { duckLakeAlias, duckLakeMetadataTableName, quoteIdentifier, quoteSqlString } from "./sql"
 
 export interface DatasetTableRef {
   readonly datasetId: string
   readonly tableName: string
   readonly tableId: bigint
+  /** The table a sequenced dataset keeps its source ordering in, which merges also change. */
+  readonly sequenceTableId?: bigint
 }
 
 export async function resolveDatasetTableRef(
@@ -15,21 +18,76 @@ export async function resolveDatasetTableRef(
   runtime: DuckDbQueryRuntime,
   datasetId: string
 ): Promise<DatasetTableRef | null> {
-  const tableName = encodeDatasetTableName(datasetId)
-  const ducklakeTable = duckLakeMetadataTableName(options, "ducklake_table")
-  const [row] = await runtime.query(`
-    SELECT table_id
-    FROM ${ducklakeTable}
-    WHERE table_name = ${quoteSqlString(tableName)}
-      AND end_snapshot IS NULL
-    LIMIT 1
+  return tableRefFromRows(datasetId, await runtime.query(datasetTablesSql(options, datasetId)))
+}
+
+/**
+ * The dataset's tables and the lake's current snapshot, in one catalog read. Inside a
+ * transaction, reading the current snapshot also fixes the transaction's DuckLake snapshot, which
+ * DuckLake otherwise fixes on its first read of the lake.
+ */
+export async function resolveDatasetTableRefAtCurrentSnapshot(
+  options: DuckLakeStorageOptions,
+  runtime: DuckDbQueryRuntime,
+  datasetId: string
+): Promise<{ readonly snapshotId: string; readonly table: DatasetTableRef | null }> {
+  // Joined on true, the current snapshot still reads when the dataset has no table.
+  const rows = await runtime.query(`
+    SELECT current.id AS current_snapshot, tables.table_id, tables.table_name
+    FROM ${quoteIdentifier(duckLakeAlias(options))}.current_snapshot() current
+    LEFT JOIN (${datasetTablesSql(options, datasetId)}) tables ON true
   `)
+  const [first] = rows
+  if (first === undefined) {
+    throw new LakeStorageError("[SixbDuckLake] DuckLake did not return a current snapshot.")
+  }
+
+  return {
+    snapshotId: String(getBigIntLike(first, "current_snapshot")),
+    table: tableRefFromRows(
+      datasetId,
+      rows.filter((row) => row.table_id !== null && row.table_id !== undefined)
+    ),
+  }
+}
+
+/** Every table a dataset's versions change. */
+export function datasetTableIds(table: Omit<DatasetTableRef, "tableName">): readonly bigint[] {
+  return table.sequenceTableId === undefined
+    ? [table.tableId]
+    : [table.tableId, table.sequenceTableId]
+}
+
+function datasetTablesSql(options: DuckLakeStorageOptions, datasetId: string): string {
+  const tableNames = [encodeDatasetTableName(datasetId), encodeDatasetSequenceTableName(datasetId)]
+  return `
+    SELECT table_id, table_name
+    FROM ${duckLakeMetadataTableName(options, "ducklake_table")}
+    WHERE table_name IN (${tableNames.map((name) => quoteSqlString(name)).join(", ")})
+      AND end_snapshot IS NULL
+  `
+}
+
+function tableRefFromRows(
+  datasetId: string,
+  rows: readonly Readonly<Record<string, unknown>>[]
+): DatasetTableRef | null {
+  const tableName = encodeDatasetTableName(datasetId)
+  const tableIdOf = (name: string) => {
+    const row = rows.find((candidate) => candidate.table_name === name)
+    return row === undefined ? undefined : getBigIntLike(row, "table_id")
+  }
+
+  const tableId = tableIdOf(tableName)
+  if (tableId === undefined) {
+    return null
+  }
 
-  return row === undefined
-    ? null
-    : {
-        datasetId,
-        tableName,
-        tableId: getBigIntLike(row, "table_id"),
-      }
+  const sequenceTableId = tableIdOf(encodeDatasetSequenceTableName(datasetId))
+  return {
+    datasetId,
+    tableName,
+    tableId,
+    ...(sequenceTableId === undefined ? {} : { sequenceTableId }),
+  }
 }

package/src/internal/ducklake-maintenance.ts

@@ -1,25 +1,40 @@
+import type { DatasetVersionRef } from "@sixb/core/lake-storage"
 import { LakeStorageError } from "@sixb/core/lake-storage"
 import type {
   DuckLakeMaintenanceOptions,
   DuckLakeMaintenanceReport,
   DuckLakeStorageOptions,
 } from "../types"
+import { getBigIntLike } from "./duckdb-row"
 import type { DuckDbQueryRuntime } from "./duckdb-runtime"
 import type { DuckLakeConnectionManager } from "./ducklake-connection-manager"
-import { duckLakeAlias, quoteSqlString } from "./sql"
+import type { DuckLakeSnapshotReader } from "./ducklake-snapshot-reader"
+import { duckLakeAlias, duckLakeMetadataTableName, quoteSqlString } from "./sql"
+import { parseVersionId } from "./versions"
 
 const DEFAULT_RETENTION = "7 days"
 
 interface MaintenanceCounts {
   readonly snapshots: number
+  readonly keptSnapshots: number
   readonly oldFiles: number
   readonly orphanedFiles: number
 }
 
+/**
+ * Expires old snapshots, except those holding a version that is still needed, then reclaims files.
+ *
+ * DuckLake's own `older_than` would expire the latest version of a dataset idle longer than the
+ * retention, leaving its rows without a version to read them through. Maintenance lists the
+ * snapshots older than the retention, keeps those holding each dataset's latest version or a
+ * protected version, and expires the rest by id. DuckLake then schedules the files only the
+ * expired snapshots referenced, as it does with `older_than`.
+ */
 export class DuckLakeMaintenance {
   constructor(
     private readonly options: DuckLakeStorageOptions,
-    private readonly connections: DuckLakeConnectionManager
+    private readonly connections: DuckLakeConnectionManager,
+    private readonly snapshots: DuckLakeSnapshotReader
   ) {}
 
   async runMaintenance(
@@ -30,6 +45,7 @@ export class DuckLakeMaintenance {
     const expireOlderThan = options.expireOlderThan ?? DEFAULT_RETENTION
     const deleteOlderThan = options.deleteOlderThan ?? expireOlderThan
     const dryRun = options.dryRun ?? false
+    const protect = (options.protect ?? []).map(protectedSnapshotId)
 
     if (this.options.readOnly && !dryRun) {
       throw new LakeStorageError(
@@ -38,13 +54,10 @@ export class DuckLakeMaintenance {
     }
 
     return this.connections.withMaintenanceRuntime(async (runtime) => {
-      const counts = await runMaintenanceProcedures(
+      const counts = await this.runMaintenanceProcedures(
         runtime,
-        this.options,
-        {
-          expireOlderThan,
-          deleteOlderThan,
-        },
+        { expireOlderThan, deleteOlderThan },
+        protect,
         dryRun
       )
 
@@ -60,57 +73,106 @@ export class DuckLakeMaintenance {
       }
     })
   }
-}
 
-async function runMaintenanceProcedures(
-  runtime: DuckDbQueryRuntime,
-  options: DuckLakeStorageOptions,
-  retention: Pick<DuckLakeMaintenanceReport, "expireOlderThan" | "deleteOlderThan">,
-  dryRun: boolean
-): Promise<MaintenanceCounts> {
-  const aliasSql = quoteSqlString(duckLakeAlias(options))
-  const snapshots = await runtime.query(
-    maintenanceProcedureSql(
-      "ducklake_expire_snapshots",
-      aliasSql,
-      retention.expireOlderThan,
-      dryRun
-    )
-  )
-  const oldFiles = await runtime.query(
-    maintenanceProcedureSql(
-      "ducklake_cleanup_old_files",
-      aliasSql,
-      retention.deleteOlderThan,
-      dryRun
+  private async runMaintenanceProcedures(
+    runtime: DuckDbQueryRuntime,
+    retention: Pick<DuckLakeMaintenanceReport, "expireOlderThan" | "deleteOlderThan">,
+    protect: readonly string[],
+    dryRun: boolean
+  ): Promise<MaintenanceCounts> {
+    const aliasSql = quoteSqlString(duckLakeAlias(this.options))
+
+    const oldSnapshotIds = await this.snapshotsOlderThan(runtime, retention.expireOlderThan)
+    const needed = new Set([
+      ...(await this.snapshots.latestVersionSnapshotIds(runtime)),
+      ...protect,
+    ])
+    const expirable = oldSnapshotIds.filter((snapshotId) => !needed.has(snapshotId))
+
+    const snapshots =
+      expirable.length === 0
+        ? []
+        : await runtime.query(
+            maintenanceProcedureSql(
+              "ducklake_expire_snapshots",
+              aliasSql,
+              `versions => [${expirable.join(", ")}]`,
+              dryRun
+            )
+          )
+
+    const oldFiles = await runtime.query(
+      maintenanceProcedureSql(
+        "ducklake_cleanup_old_files",
+        aliasSql,
+        `older_than => ${olderThanSql(retention.deleteOlderThan)}`,
+        dryRun
+      )
     )
-  )
-  const orphanedFiles = await runtime.query(
-    maintenanceProcedureSql(
-      "ducklake_delete_orphaned_files",
-      aliasSql,
-      retention.deleteOlderThan,
-      dryRun
+    const orphanedFiles = await runtime.query(
+      maintenanceProcedureSql(
+        "ducklake_delete_orphaned_files",
+        aliasSql,
+        `older_than => ${olderThanSql(retention.deleteOlderThan)}`,
+        dryRun
+      )
     )
-  )
 
-  return {
-    snapshots: snapshots.length,
-    oldFiles: oldFiles.length,
-    orphanedFiles: orphanedFiles.length,
+    return {
+      snapshots: snapshots.length,
+      keptSnapshots: oldSnapshotIds.length - expirable.length,
+      oldFiles: oldFiles.length,
+      orphanedFiles: orphanedFiles.length,
+    }
+  }
+
+  /**
+   * Snapshots older than the retention, except the current one, which DuckLake never expires.
+   *
+   * Not DuckLake's own `older_than` selection: a SQLite catalog stores snapshot times as text with
+   * their UTC offset, and with DuckLake 415a9ebd that selection then also returned snapshots
+   * written a moment ago outside UTC. Casting the stored text compares instants on every catalog.
+   */
+  private async snapshotsOlderThan(
+    runtime: DuckDbQueryRuntime,
+    olderThan: string
+  ): Promise<readonly string[]> {
+    const ducklakeSnapshot = duckLakeMetadataTableName(this.options, "ducklake_snapshot")
+    const rows = await runtime.query(`
+      SELECT snapshot_id
+      FROM ${ducklakeSnapshot}
+      WHERE CAST(snapshot_time AS TIMESTAMPTZ) < ${olderThanSql(olderThan)}
+        AND snapshot_id < (
+          SELECT snapshot_id FROM ${ducklakeSnapshot} ORDER BY snapshot_id DESC LIMIT 1
+        )
+      ORDER BY snapshot_id
+    `)
+
+    return rows.map((row) => String(getBigIntLike(row, "snapshot_id")))
+  }
+}
+
+function protectedSnapshotId(ref: DatasetVersionRef): string {
+  try {
+    return parseVersionId(ref.versionId)
+  } catch (error) {
+    throw new LakeStorageError(
+      `[SixbDuckLake] Cannot protect version '${ref.versionId}' of dataset '${ref.datasetId}' from maintenance: it is not a DuckLake version id.`,
+      { cause: error }
+    )
   }
 }
 
+function olderThanSql(olderThan: string): string {
+  return `now() - INTERVAL ${quoteSqlString(olderThan)}`
+}
+
 function maintenanceProcedureSql(
   procedure: string,
   aliasSql: string,
-  olderThan: string,
+  selection: string,
   dryRun: boolean
 ): string {
-  const olderThanSql = quoteSqlString(olderThan)
   const dryRunSql = dryRun ? "dry_run => true, " : ""
-  return (
-    `CALL ${procedure}(${aliasSql}, ${dryRunSql}` +
-    `older_than => now() - INTERVAL ${olderThanSql})`
-  )
+  return `CALL ${procedure}(${aliasSql}, ${dryRunSql}${selection})`
 }