# Query table data

Read sampled data from a table. When the number of rows is not explicitly specified, the service returns 100 rows by default.

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

## 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 read data from.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/catalog/table/data" \
  -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): use `id`, or use `name` plus `database_id`/`database_name`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Conditionally required | Table ID. |
| `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, default `1`. |
| `page_size` | integer | No | Number of lines per page, default `100`. |
| `preview_lines` | integer | No | Number of preview lines. |
| `include_total` | boolean | No | Whether to return the total number of rows; return if not transmitted. |

## Successful response

On success, `200` and the sampling result are returned. Returns `403` when there is no read permission.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "data": [
      ["1", "100.00"]
    ],
    "columns": [
      {
        "name": "id",
        "type": "INT"
      },
      {
        "name": "amount",
        "type": "DECIMAL"
      }
    ],
    "total_rows": 120,
    "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 upper limit of the number of rows in the current 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 read table data.
  - 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).