# Preview table data

Preview table data without modifying table content.

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

## 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`: Table ID to preview.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/catalog/table/preview" \
  -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 positioning method of the table is consistent with [query table information](get-table.md): pass in `id`, or pass in `name` and `database_id`/`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 | Non-system database ID; mutually exclusive with `database_name`. |
| `database_name` | string | Conditionally required | System database name; mutually exclusive with `database_id`. |
| `page` | integer | No | Page number; if it is not transmitted or is less than or equal to `0`, it will be processed as page `1`. |
| `page_size` | integer | No | The number of items per page; use `100` when it is not transmitted or is less than or equal to `0`. |
| `preview_lines` | integer | No | Number of preview rows; passing a positive number overwrites `page_size` and starts at page `1`. |
| `include_total` | boolean | No | Whether to return the total number of rows; return if not transmitted. |

## Successful response

Returns `200` and preview results on success. The returned fields are consistent with [query table data](get-table-data.md).

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "data": [
      ["1", "100.00"]
    ],
    "columns": [
      {
        "name": "id",
        "type": "INT"
      },
      {
        "name": "amount",
        "type": "DECIMAL"
      }
    ],
    "page": 1,
    "page_size": 100
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.data` | array | Row data; each inner array is arranged in the order of `columns`. |
| `data.columns` | array | Column information, each item contains `name` and `type`. |
| `data.total_rows` | integer | Total number of table rows; only returned when `include_total` is requested. |
| `data.page` | integer | Current page number. |
| `data.page_size` | integer | The maximum number of lines per page. |

## 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`
  - Invalid table ID, name positioning, or paging parameters.
  - Use the table ID, or complete the table name and database location parameters.
* - `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 preview table data.
  - Record the request time and error message and try again; if it continues to fail, contact support.
```

## Follow-up operations

After completion, [Query Catalog details](get-catalog.md) confirms the result.