# Query objects in the database

Query the volumes, tables and operators that can be read in the specified database. These objects match Volume, Table, and Operator in the console database create menu.

```text
POST https://moi.matrixorigin.cn/newmoi/catalog/database/children
```

## Preparation before calling

First [query the database list](list-databases.md) to obtain the target database ID. Prepare the personal access token, target workspace ID, and database ID that have 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.
- `$DATABASE_ID`: The database ID of the child object is to be queried.

## Request example

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

## Request body

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Database ID. |

## Successful response

On success, returns `200` and a list of sub-objects readable by the current identity.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "list": [
      {
        "id": 10,
        "name": "raw",
        "type": "volume",
        "children_count": 2,
        "size": 1024,
        "description": "原始文件",
        "reserved": false,
        "allowed_actions": ["volume.read"]
      }
    ]
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.list` | object[] | List of sub-objects; empty array when there is no readable object. |
| `data.list[].id` | integer or string | Object ID. |
| `data.list[].name` | string | Object name. |
| `data.list[].type` | string | Object type: `volume`, `table`, or `function` (operator). |
| `data.list[].children_count` | integer | Number of children; returned if applicable. |
| `data.list[].size` | integer | Storage size; returned if applicable. |
| `data.list[].created_at` | string | Creation time; returned if applicable. |
| `data.list[].created_by` | string | Creator ID; returned when applicable. |
| `data.list[].updated_at` | string | Update time; returned when applicable. |
| `data.list[].updated_by` | string | Updater ID; returned if applicable. |
| `data.list[].description` | string | Object description. |
| `data.list[].display_name` | string | Object display name; returned when applicable. |
| `data.list[].display_description` | string | Object display description; returned when applicable. |
| `data.list[].reserved` | boolean | Whether it is a reserved object. |
| `data.list[].is_pub` | boolean | Whether it is a publishing object; returned when applicable. |
| `data.list[].is_sub` | boolean | Whether it is a subscription object; returned when applicable. |
| `data.list[].allowed_actions` | string[] | Operations allowed by the current identity. |

In this document, `[]` after a type means an array; for example, `object[]` is an array of objects. In field paths, `[]` means each item in an array; for example, `data.list[].id` is the `id` field of each item in `data.list`.

## Error response

```json
{
  "code": "ErrObjectNotFound",
  "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`
  - The request body or database ID is invalid.
  - Use a positive integer ID from the database list.
* - `403`
  - `ErrForbidden`
  - The current identity does not have read permission.
  - Requesting permission to `database.read`.
* - `404`
  - `ErrObjectNotFound`
  - The database does not exist or is not readable.
  - Verify database ID and workspace.
* - `500`
  - `ErrServer`
  - The server failed to read the sub-object.
  - Try again later.
```

## Follow-up operations

Save `data.list[].id`. When the type is `volume`, [Query volume details](get-volume.md). When the type is `table`, [Query table information](get-table.md). When the type is `function`, [Query custom operator details](../../data-processing/custom-operators/get-custom-operator.md).