onehouse_table_service

Manages a table service — an automated maintenance operation that runs on a specific table. Table services keep tables healthy by clustering data for faster reads, compacting small files, cleaning up old versions, and syncing metadata to external catalogs.

Canonical reference

This page documents Terraform-specific behavior (HCL syntax, types, mutability, drift, import). For full parameter semantics, valid values, and defaults, see CREATE TABLE_SERVICE, ALTER TABLE_SERVICE, and DELETE TABLE_SERVICE.

Example Usage

Clustering service

resource "onehouse_table_service" "cluster_events" {
  lake     = onehouse_lake.warehouse.name
  database = onehouse_database.events.name
  table    = "raw_events"
  service  = "CLUSTER"

  with_options = {
    "cluster.field.names"     = "event_date,tenant_id"
    "cluster.layout.strategy" = "linear"
    "cluster.frequency"       = "1"
  }
}

Compaction service

resource "onehouse_table_service" "compact_events" {
  lake     = onehouse_lake.warehouse.name
  database = onehouse_database.events.name
  table    = "raw_events"
  service  = "COMPACT"

  with_options = {
    "compaction.max.bytes"  = "536870912"
    "compaction.frequency"  = "1"
  }
}

Cleaning service

resource "onehouse_table_service" "clean_events" {
  lake     = onehouse_lake.warehouse.name
  database = onehouse_database.events.name
  table    = "raw_events"
  service  = "CLEAN"

  with_options = {
    "cleaner.retention.days" = "7"
    "cleaner.frequency"      = "1"
  }
}

Metasync service (on-demand)

resource "onehouse_table_service" "metasync_events" {
  lake         = onehouse_lake.warehouse.name
  database     = onehouse_database.events.name
  table        = "raw_events"
  service      = "METASYNC"
  trigger_mode = "ON_DEMAND"

  with_options = {
    "metasync.catalogs" = "prod-glue"
  }
}

Argument Reference

Argument	Type	Required	Mutability	Description
lake	string	✅	Immutable	Lake name.
database	string	✅	Immutable	Database name.
table	string	✅	Immutable	Table name.
service	string	✅	Immutable	Service type: CLUSTER, COMPACT, CLEAN, or METASYNC.
trigger_mode	string		Mutable	AUTOMATIC (default) or ON_DEMAND. ON_DEMAND is only valid for METASYNC. Changes issue ALTER TABLE_SERVICE.
with_options	map(string)		Mutable	Service-specific configuration parameters. Changes issue ALTER TABLE_SERVICE. → details below

service — when to pick each value

Value	Purpose
CLUSTER	Rewrite data files to co-locate records by specified fields, improving read performance for filtered queries.
COMPACT	Merge small files into larger ones to reduce file count and improve query performance.
CLEAN	Remove old file versions beyond the retention period.
METASYNC	Sync table metadata to external catalogs (Glue, Hive, Unity, etc.).

with_options

A map of string key-value pairs that configure the service. Keys vary by service type:

CLUSTER options

Key	Description
cluster.field.names	Comma-separated column names to cluster by.
cluster.layout.strategy	Layout strategy (e.g. linear).
cluster.frequency	How often to run (in number of commits).
cluster.bootstrap	Whether to cluster existing data on first run.

COMPACT options

Key	Description
compaction.max.bytes	Target file size in bytes.
compaction.frequency	How often to run (in number of commits).

CLEAN options

Key	Description
cleaner.retention.days	Number of days to retain old file versions.
cleaner.frequency	How often to run (in number of commits).

METASYNC options

Key	Description
metasync.catalogs	Comma-separated catalog names to sync to.

Additional catalog-specific Iceberg keys may be required depending on the target catalog.

Attribute Reference

Attribute	Type	Description
id	string	Composite identifier <lake>/<database>/<table>/<service>.

Import

Import IDs are composite: <lake>/<database>/<table>/<service>.

terraform import onehouse_table_service.cluster_events warehouse/events/raw_events/CLUSTER

Data Source

data "onehouse_table_service" "lookup" {
  lake     = "warehouse"
  database = "events"
  table    = "raw_events"
  service  = "CLUSTER"
}

output "trigger_mode" {
  value = data.onehouse_table_service.lookup.trigger_mode
}

The data source also exposes a status computed attribute reflecting the current service status.

Limitations

• with_options not echoed by DESCRIBE. After import or on Read, with_options values are preserved from prior Terraform state since the server does not return them in the DESCRIBE response. Supply all with_options in your .tf file before the first terraform apply after import.
• One service per type per table. Each table can have at most one service of each type.