# Query table information

Query table definition, table creation SQL, statistics and other information.

```text
POST https://moi.matrixorigin.cn/newmoi/catalog/table/info
```

## Preparation before calling

First [query the object](list-database-objects.md) in the database to obtain the target table ID, or prepare the table name and database positioning parameters. Prepare the personal access token, target workspace ID, and table location information that has access to the target workspace.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: Target workspace ID, passed through `X-Workspace-ID` Header.
- `$TABLE_ID`: The table ID to be queried.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/catalog/table/info" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "id": '"$TABLE_ID"'
  }'
```

## Request body

The request can be queried by table ID, or by table name plus database ID/system database name.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Conditionally required | Table ID. You do not need to pass the name after providing it. |
| `name` | string | Conditionally required | Table name; required if `id` is not provided. |
| `database_id` | integer | Conditionally required | Database ID of non-system database; mutually exclusive with `database_name`. |
| `database_name` | string | Conditionally required | System database name; mutually exclusive with `database_id`. |
| `include_stats` | boolean | No | Whether to return column statistics. |

## Successful response

Returns `200` and table information on success. Returns `403` when there is no read permission.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "name": "orders",
    "lines": 120,
    "size": 4096,
    "created_at": 1735689600,
    "updated_at": 1735689600,
    "created_by": "user@example.com",
    "description": "订单表",
    "comment": "订单明细",
    "columns": [
      {
        "name": "id",
        "type": "INT",
        "is_pk": true
      }
    ],
    "create_sql": "CREATE TABLE orders (id INT PRIMARY KEY)",
    "stats": [
      {
        "name": "id",
        "type": "INT",
        "max_value": "100",
        "min_value": "1"
      }
    ]
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.name` | string | Table name. |
| `data.lines` | integer | Number of table rows. |
| `data.size` | integer | Table size in bytes. |
| `data.created_at` | integer | Unix timestamp of creation time in seconds. |
| `data.updated_at` | integer | Unix timestamp of the update time in seconds. |
| `data.created_by` | string | Creator ID. |
| `data.description` | string | Table description. |
| `data.comment` | string | Table comment. |
| `data.columns` | array | Column definition. Each item contains `name`, `type`, and may contain `is_pk`, `comment`, `precision`, `default`. |
| `data.create_sql` | string | Create table SQL. |
| `data.stats` | array | Column statistics; each item includes column name, type, primary key identifier, default value, comment, and maximum and minimum values. |

## Error response

```json
{
  "code": "ErrParamInvalid",
  "msg": "表定位参数无效",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `ErrParamInvalid`
  - No valid table positioning method is provided, or `database_id` and `database_name` are passed in at the same time.
  - Use a table ID, or just a name targeting method.
* - `403`
  - `ErrForbidden`
  - The current identity does not have table read permission.
  - Check workspace and table authorizations.
* - `409`
  - `ErrReadonlySystemDatabase`
  - The system database does not support the current read path.
  - Use supported table positioning methods instead.
* - `500`
  - `ErrServer`
  - The service cannot read table information.
  - Record the request time and error message and try again; if it continues to fail, contact support.
```

## Follow-up operations

When modifications are needed [Update database](update-database.md). When returning the list [Query file products](list-file-artifacts.md).