# Information Schema

Source: https://www.hotdata.dev/docs/api-reference/information-schema
Site index: https://www.hotdata.dev/llms.txt

Inspect table and column metadata across all connections. Returns schema information including column names, data types, and sync status for every discovered table.

## List tables

`GET /v1/information_schema`

List discovered tables with optional filtering and pagination. Supports wildcard patterns (SQL %) for schema and table name filters. Set include_columns=true to include column definitions (omitted by default). Every table carries its declared storage layout — `partition_by` and `sorted_by` — which is fixed when the table is created and cannot be changed afterwards. Both are always present; an empty array means none was declared. Only tables in a Hotdata instant database declare a layout here, so a table discovered from an external connection always reports empty arrays.

**Query parameters**

- `connection_id` `string` — Filter by connection ID
- `schema` `string` — Filter by schema name (supports % wildcards)
- `table` `string` — Filter by table name (supports % wildcards)
- `include_columns` `boolean` — Include column definitions (default: false)
- `limit` `integer` — Maximum number of tables per page
- `cursor` `string` — Pagination cursor from a previous response

**Response** `200` — Table metadata

- `count` `integer` — **required**. Min: `0`
- `has_more` `boolean` — **required**
- `limit` `integer` — **required**. Min: `0`
- `next_cursor` `string,null`
- `tables` `TableInfo`[] — **required**
  - `columns` `ColumnInfo`[] | `null`
    - `data_type` `string` — **required**
    - `name` `string` — **required**
    - `nullable` `boolean` — **required**
  - `connection` `string` — **required**
  - `last_sync` `string,null`
  - `partition_by` `TablePartitionKey`[] — **required**. The table's partition keys, in the order they were declared when the table was created. Empty when the table is not partitioned. A table's storage layout is fixed when the table is created and cannot be changed afterwards, so this is how to confirm a table really was created with the layout that was asked for. The field is always present: an empty array means "no partitioning declared", which is not the same as a response that omits the field entirely. Reported for tables in a Hotdata instant database, which are the only ones whose layout is declared here. A table discovered from an external connection always reports an empty array — its layout belongs to the upstream system, so an empty array there means "not known from here", not "confirmed unpartitioned".
    - `column` `string` — **required**. Column the key reads.
    - `transform` `string` — **required**. How the value is derived from the column. One of `identity` (the column value itself), `year`, `month`, `day`, or `hour`.
  - `schema` `string` — **required**
  - `sorted_by` `TableSortKey`[] — **required**. The table's sort keys, in the order they were declared when the table was created. Empty when no sort order was declared. Always present, and limited to tables in a Hotdata instant database, for the same reasons as `partition_by`.
    - `column` `string` — **required**
    - `direction` `string,null` — `asc` (the default) or `desc`. Null when the table was declared without an explicit direction for this key.
    - `nulls` `string,null` — Where nulls are placed: `first` or `last`. Defaults to the SQL default for the chosen direction. Null when the table was declared without an explicit placement for this key.
  - `synced` `boolean` — **required**
  - `table` `string` — **required**

```json
{
  "count": 0,
  "has_more": true,
  "limit": 0,
  "next_cursor": "string",
  "tables": [
    {
      "columns": [
        {}
      ],
      "connection": "string",
      "last_sync": "string",
      "partition_by": [
        {}
      ],
      "schema": "string",
      "sorted_by": [
        {}
      ],
      "synced": true,
      "table": "string"
    }
  ]
}
```

**Errors**

| Status | Description |
| ------ | ----------- |
| `404` | Connection not found |