> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> API reference for ClickHouse: every `clickhouse.api.*` operation with input and output types.

Every `clickhouse.api.*` operation is listed below with parameter shapes and return types from the plugin Zod schemas.

<Info>
  **New to Corsair?** See [API access](/concepts/api), [authentication](/concepts/auth), and [error handling](/concepts/error-handling).
</Info>

## Play

### get

`play.get`

Fetch the ClickHouse Play web UI HTML (Monaco editor + query UI).

**Risk:** `read`

```ts theme={null}
await corsair.clickhouse.api.play.get({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | The Play UI URL |
| `html` | `string` | Yes | Play UI HTML page (Monaco editor + query UI) |
| `sizeBytes` | `number` | Yes | — |

***

## Query

### execute

`query.execute`

Execute a SQL query against the tenant ClickHouse instance and return the result rows. Arbitrary SQL is accepted — destructive statements require explicit permission.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.clickhouse.api.query.execute({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `sql` | `string` | Yes | SQL query to execute against ClickHouse |
| `database` | `string` | No | Default database context (sent as ?database=) |
| `limit` | `number` | No | Maximum rows to return; appended as LIMIT when not present in SQL |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `rows` | `object[]` | Yes | JSONEachRow objects; column names map to native JSON values |
| `rowCount` | `number` | Yes | — |

<AccordionGroup>
  <Accordion title="rows full type">
    ```ts theme={null}
    {
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### listDatabases

`query.listDatabases`

List all databases on the tenant ClickHouse instance.

**Risk:** `read`

```ts theme={null}
await corsair.clickhouse.api.query.listDatabases({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `databases` | `object[]` | Yes | — |

<AccordionGroup>
  <Accordion title="databases full type">
    ```ts theme={null}
    {
      name: string,
      engine: string
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### listTables

`query.listTables`

List tables in a ClickHouse database with their engine and approximate size.

**Risk:** `read`

```ts theme={null}
await corsair.clickhouse.api.query.listTables({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `database` | `string` | Yes | Database to list tables from |
| `limit` | `number` | No | Maximum tables to return |
| `offset` | `number` | No | Tables to skip before returning rows |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `database` | `string` | Yes | — |
| `tables` | `object[]` | Yes | — |
| `count` | `number` | Yes | Number of tables returned |

<AccordionGroup>
  <Accordion title="tables full type">
    ```ts theme={null}
    {
      name: string,
      engine?: string,
      totalRows?: number | string | null,
      totalBytes?: number | string | null
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

## Schema

### getDatabase

`schema.getDatabase`

Get schema overview for a ClickHouse database; optionally include column definitions for each table.

**Risk:** `read`

```ts theme={null}
await corsair.clickhouse.api.schema.getDatabase({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `database` | `string` | Yes | Database to introspect |
| `includeColumns` | `boolean` | No | When true, also fetch column definitions for each table |
| `limit` | `number` | No | — |
| `offset` | `number` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `database` | `string` | Yes | — |
| `tables` | `object[]` | Yes | — |
| `count` | `number` | Yes | — |

<AccordionGroup>
  <Accordion title="tables full type">
    ```ts theme={null}
    {
      name: string,
      engine?: string,
      totalRows?: number | string | null,
      totalBytes?: number | string | null,
      columns?: {
        name: string,
        type: string,
        position?: number | string | null,
        comment?: string,
        defaultExpression?: string
      }[]
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### getTable

`schema.getTable`

Get column-level schema for a ClickHouse table, optionally with sample rows.

**Risk:** `read`

```ts theme={null}
await corsair.clickhouse.api.schema.getTable({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `database` | `string` | Yes | Database the table belongs to |
| `table` | `string` | Yes | Table to introspect |
| `includeSample` | `boolean` | No | When true, include up to `sampleSize` rows from the table |
| `sampleSize` | `number` | No | Sample row count when includeSample is true; defaults to 5 |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `database` | `string` | Yes | — |
| `table` | `string` | Yes | — |
| `engine` | `string` | No | — |
| `totalRows` | `number \| string` | No | — |
| `columns` | `object[]` | Yes | — |
| `sampleRows` | `object[]` | No | Sample rows; only present when includeSample is true |

<AccordionGroup>
  <Accordion title="columns full type">
    ```ts theme={null}
    {
      name: string,
      type: string,
      position?: number | string | null,
      comment?: string,
      defaultExpression?: string
    }[]
    ```
  </Accordion>

  <Accordion title="sampleRows full type">
    ```ts theme={null}
    {
    }[]
    ```
  </Accordion>
</AccordionGroup>

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.