Skip to content
WarpStream Documentation

Tables

APIs for interacting with Tableflow tables.

Table creation is managed automatically by the WarpStream Control Plane. Create a pipeline with desired table configurations to initiate table creations.

POST /api/v1/tableflow/list_tables

Returns all active Tableflow tables for a given virtual cluster.

Field Type Required Description
virtual_cluster_id string Yes The ID of the Tableflow virtual cluster.
curl [https://api.warpstream.com/api/v1/tableflow/list_tables](https://api.warpstream.com/api/v1/tableflow/list_tables) \
-H 'warpstream-api-key: XXXXXXXXXX' \
-H 'Content-Type: application/json' \
-d '{"virtual_cluster_id": "vci_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX"}'
{
"tables": [
{
"table_name": "my_cluster.my_topic.a1b2c3d4",
"table_uuid": "550e8400-e29b-41d4-a716-446655440000",
"source_stream_name": "my_topic",
"source_cluster_name": "my_cluster",
"stats_estimated_byte_count": 1048576,
"stats_estimated_row_count": 10000,
"created_at_unix_nanos": 1700000000000000000
}
]
}

POST /api/v1/tableflow/get_table

Returns details for a single Tableflow table, looked up by UUID or by name.

Field Type Required Description
virtual_cluster_id string Yes The ID of the Tableflow virtual cluster.
table_uuid string Optional* The UUID of the table to retrieve.
table_name string Optional* The name of the table to retrieve.
include_status boolean No If true, includes Tableflow health, sync status, and lag information.
curl https://api.warpstream.com/api/v1/tableflow/get_table \
-H 'warpstream-api-key: XXXXXXXXXX' \
-H 'Content-Type: application/json' \
-d '{
"virtual_cluster_id": "vci_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
"table_uuid": "550e8400-e29b-41d4-a716-446655440000"
}'
curl https://api.warpstream.com/api/v1/tableflow/get_table \
-H 'warpstream-api-key: XXXXXXXXXX' \
-H 'Content-Type: application/json' \
-d '{
"virtual_cluster_id": "vci_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
"table_uuid": "550e8400-e29b-41d4-a716-446655440000",
"include_status": true
}'
{
"table": {
"table_name": "my_cluster.my_topic.a1b2c3d4",
"table_uuid": "550e8400-e29b-41d4-a716-446655440000",
"table_location": "s3://my_bucket/warpstream/_tableflow/my_cluster.my_topic.a1b2c3d4-550e8400-e29b-41d4-a716-446655440000",
"source_stream_name": "my_topic",
"source_cluster_name": "my_cluster",
"stats_estimated_byte_count": 1048576,
"stats_estimated_row_count": 10000,
"created_at_unix_nanos": 1700000000000000000
}
}
Field Type Description
table.table_name string The full name of the table.
table.table_uuid string The unique identifier of the table.
table.table_location string The location (blob storage URL) where the Iceberg table’s data and metadata is stored.
table.source_stream_name string The source Kafka topic name.
table.source_cluster_name string The name of the source cluster.
table.stats_estimated_byte_count integer Estimated total size of the table in bytes.
table.stats_estimated_row_count integer Estimated total number of rows in the table.
table.created_at_unix_nanos integer Table creation timestamp in nanoseconds since Unix epoch.

When include_status is true, the response includes a status object.

{
"table": {
"table_name": "my_cluster.my_topic.a1b2c3d4",
"table_uuid": "550e8400-e29b-41d4-a716-446655440000",
"table_location": "s3://my_bucket/warpstream/_tableflow/my_cluster.my_topic.a1b2c3d4-550e8400-e29b-41d4-a716-446655440000",
"source_stream_name": "my_topic",
"source_cluster_name": "my_cluster",
"stats_estimated_byte_count": 1048576,
"stats_estimated_row_count": 10000,
"created_at_unix_nanos": 1700000000000000000
},
"status": {
"health": {
"status": "healthy",
"message": "Table is active, synced, and lag signals are current.",
"reasons": [
"table_active",
"pipeline_config_synced"
]
},
"iceberg_metadata_matches_deployed_config": true,
"iceberg_metadata_pipeline_version": 12,
"deployed_pipeline_version": 12,
"table_status": "active",
"ingestion_lag_known": true,
"ingestion_lag_milliseconds": 60000,
"query_lag_known": true,
"query_lag_milliseconds": 90000,
"total_offset_lag_count": 42,
"partitions": [
{
"partition_id": 0,
"offset_lag_count": 42,
"time_lag_known": true,
"time_lag_milliseconds": 60000
}
]
}
}

POST /api/v1/tableflow/delete_table

Permanently deletes a Tableflow table and all of its associated metadata from the WarpStream control plane.

Removing a table from the YAML configuration does not delete it. It only stops ingestion, the table and its metadata remain in the WarpStream control plane. Adding the table back to the configuration will resume ingestion on the same existing table. This endpoint removes all metadata from the WarpStream control plane but does not delete data files already synced to your object storage bucket. To fully clean up, delete the table’s directory from within the warpstream/_tableflow path in your bucket using your cloud provider’s UI or CLI.

Field Type Required Description
virtual_cluster_id string Yes The ID of the Tableflow virtual cluster.
table_uuid string Yes The UUID of the table to delete.
curl [https://api.warpstream.com/api/v1/tableflow/delete_table](https://api.warpstream.com/api/v1/tableflow/delete_table) \
-H 'warpstream-api-key: XXXXXXXXXX' \
-H 'Content-Type: application/json' \
-d '{
"virtual_cluster_id": "vci_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
"table_uuid": "550e8400-e29b-41d4-a716-446655440000"
}'
{}

To recreate a table from scratch (for example, to reset ingestion after a schema change or data issue):

  1. Delete the table using the API or UI.
  2. Keep the table configuration in your pipleine YAML configuration.
  3. On the next discovery cycle, Tableflow will automatically create a new table with a fresh UUID and begin ingesting from scratch.

The new table will have no historical data, it is a brand-new table from the control plane’s perspective.