Preview table data¶

Preview table data without modifying table content.

POST https://api.moi.matrixorigin.cn/v5/catalog/table/preview

Preparation before calling¶

First query the object 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¶

curl -X POST "https://api.moi.matrixorigin.cn/v5/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: 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.

{
  "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¶

The following is a generic HTTP 500 error response. Some deployments can also return it when the table is missing. ErrServer does not distinguish a missing table from a service failure. Invalid table location parameters are a separate case from a well-formed ID that does not identify an existing table.

If preview fails, use the same table location parameters to query table information. If that request returns 404, verify the table ID or name and database before previewing again. If the table information is readable but preview still fails, record the HTTP status, response code, and request time and contact support.

{
  "code": "ErrServer",
  "msg": "Internal server error",
  "data": null
}

Common HTTP errors¶

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.	Check the table information with the same location parameters. If the table is readable but preview still fails, record the request time and response code and contact support.

Follow-up operations¶

After completion, Query Catalog details confirms the result.

Last updated on Oct 19, 2026