# Tables

APIs for interacting with Tableflow tables.

## Create Table

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

## List Tables

`POST /api/v1/tableflow/list_tables`

Returns all active Tableflow tables for a given virtual cluster.

### Request

| Field                | Type   | Required | Description                              |
| -------------------- | ------ | -------- | ---------------------------------------- |
| `virtual_cluster_id` | string | Yes      | The ID of the Tableflow virtual cluster. |

#### CURL Example

```bash
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"}'
```

### Response

```json
{
  "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
    }
  ]
}
```

## Get Table

`POST /api/v1/tableflow/get_table`

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

### Request

| 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. |

:::caution
**Exactly one** of `table_uuid` or `table_name` must be specified. Providing both or neither will return an error.
:::

#### CURL Example (by UUID)

```bash
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 Example With Status

```bash
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
  }'
```

### Response

```json
{
  "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.                              |

### Response With Status

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

```json
{
  "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
      }
    ]
  }
}
```

## Delete Table

`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.

:::danger
**This operation is irreversible.** The table's metadata in the WarpStream control plane will be permanently removed. Data files already synced to your object storage bucket under `warpstream/_tableflow` are **not** deleted, you must clean those up manually using your cloud provider's UI or CLI.
:::

:::note
This endpoint requires admin-level permissions. Read-only API keys cannot delete tables.
:::

### Request

| 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 Example

```bash
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"
  }'
```

### Response

```json
{}
```

## Recreating Table

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.