Help Center/ Distributed Database Middleware/ API Reference/ APIs (Recommended)/ Schemas/ Querying Details About a Schema (a V3 API)
Updated on 2026-05-30 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Querying Details About a Schema (a V3 API)

Function

Querying details about a schema

URI

GET /v3/{project_id}/instances/{instance_id}/databases/{database_name}

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID.

instance_id

Yes

String

Instance ID

database_name

Yes

String

Schema name

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token

The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

shards

Array of Shards objects

Shards of a schema.

status

String

Schema status.

CREATING: The logical table is being created.

RUNNING: The logical table is running.

UNKNOWN: The local table is in other states.

created

String

Creation time. The format is yyyy-MM-ddTHH:mm:ssZ.

T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, in the Beijing time zone, the offset is +0800.

updated

String

Update time. The format is yyyy-MM-ddTHH:mm:ssZ.

T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, in the Beijing time zone, the offset is +0800.

name

String

Schema name, which:

  • Can include 2 to 48 characters.

  • Must start with a letter.

  • Contains only lowercase letters, digits, and underscores (_).

  • Cannot be the following names:

information_schema, mysql, performance_schema, or sys

shard_mode

String

Sharding mode of the schema. The value can be:

  • cluster: indicates that the schema is in sharded mode.

  • single: indicates that the schema is in unsharded mode.

shard_number

Integer

Number of shards in the schema.

data_nodes

Array of DataNodes objects

Information about associated backend data nodes.
Table 4 Shards

Parameter

Type

Description

data_node_id

String

ID of the RDS instance where a physical shard is located.

physical_db_name

String

Physical shard name.

status

String

Physical shard status.

shard_index

Integer

Sequence number of a physical shard.
Table 5 DataNodes

Parameter

Type

Description

id

String

ID of a data node.

status

String

Status of a data node.

name

String

Name of a data node.

engine_name

String

Engine name of a data node.

engine_version

String

Engine version of a data node

mem

Integer

Memory size of a data node.

cpu

Integer

CPU size of a data node.

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Status code: 500

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Example Request

Querying details about a schema

GET https://{endpoint}/v3/{project_id}/instances/{instance_id}/databases/{database_name}

Example Response

Status code: 200

OK

{
  "shards" : [ {
    "data_node_id" : "253883d46****d3fb38161b57in01",
    "physical_db_name" : "ddm_db_test_0000",
    "status" : "RUNNING",
    "shard_index" : 0
  }, {
    "data_node_id" : "253883d4*****9960d3fb38161b57in01",
    "physical_db_name" : "ddm_db_test_0001",
    "status" : "RUNNING",
    "shard_index" : 1
  } ],
  "status" : "RUNNING",
  "created" : "2025-02-10T07:18:26+0000",
  "updated" : "2025-02-10T07:18:26+0000",
  "name" : "ddm_db_test",
  "shard_mode" : "cluster",
  "shard_number" : 2,
  "data_nodes" : [ {
    "id" : "253883****089960d3fb38161b57in01",
    "status" : "normal",
    "name" : "mysql*****YwVuVoio6g8AnF5oUH5i",
    "engine_name" : "mysql",
    "engine_version" : "5.7",
    "mem" : 4,
    "cpu" : 2
  } ]
}

Status code: 400

Bad request

{
  "error_code" : "DBS.280001",
  "error_msg" : "Parameter error."
}

Status code: 500

Server error

{
  "error_code" : "DBS.290015",
  "error_msg" : "Failed to process the request."
}

Status Codes

Status Codes

Description

202

OK

400

Bad request

500

Server error

Error Codes

For details, see Error Codes.

Parent topic: Schemas