Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ Data Storage Insights/ Querying the Top 20 Tables by Storage Usage in an Instance

Updated on 2025-12-26 GMT+08:00

View PDF

Querying the Top 20 Tables by Storage Usage in an Instance

Function

This API is used to query the top 20 tables by storage usage in an instance. Before calling this API:

Learn how to authenticate this API.
Obtain the required region and endpoint.

Debugging

You can debug this API in API Explorer.

URI

GET /v3.1/{project_id}/instances/{instance_id}/top-table-volume

**Table 1** Parameter description
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID of a tenant in a region. To obtain the value, see Obtaining a Project ID. Constraints N/A Range The value can contain 32 characters. Only letters and digits are allowed. Default Value N/A
instance_id	Yes	String	Definition Instance ID, which uniquely identifies an instance. Constraints N/A Range The value can contain 36 characters. Only letters and digits are allowed. Default Value N/A

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
job_id	No	String	Definition Job ID, which is obtained by calling this API for the first time without passing any task parameter. Constraints N/A Range N/A Default Value N/A
node_id	No	String	Definition ID of the node that executes the job, which is obtained by calling this API for the first time without passing any task parameter. Constraints N/A Range N/A Default Value N/A

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. You can obtain the token by calling the IAM API used to obtain a user token. After a response is returned, the value of X-Subject-Token in the response header is the token. Constraints N/A Range N/A Default Value N/A
X-Language	No	String	Definition Language. Constraints N/A Range zh-cn en-us Default Value en-us

Response Parameters

**Table 4** Response body parameters
Parameter	Type	Description
table_volumes	Array of objects	Definition Storage usage of tables in a database, which is returned when job_id in the request is not empty. For details, see Table 5.
total_count	Integer	Definition Total number of tables, which is returned when job_id in the request is not empty. Range N/A
job_id	String	Definition Job ID, which is returned when no request parameter is provided. Range N/A
node_id	String	Definition ID of the node that executes the job, which is returned when no request parameter is provided. Range N/A
state	String	Definition Job status, which is returned when job_id in the request is not empty. Range FINISHED: The job is complete. RUNNING: The job is running. ERROR: The job failed.

**Table 5** TableVolume
Parameter	Type	Description
table_size	String	Definition Table size. Range N/A
id	String	Definition Table ID. Range N/A
table_name	String	Definition Table name. Range N/A
table_owner	String	Definition Username of a table. Range N/A
schema_name	String	Definition Schema name. Range N/A
database_name	String	Definition Database name. Range N/A
is_part_type	Boolean	Definition Whether the table or index has the property of a partitioned table. Range true: The table or index has the property of a partitioned table. false: The table or index does not have the property of a partitioned table.
is_hash_cluster_key	Boolean	Definition Whether the table contains a hash-partitioned column. Range Range true: The table contains a hash-partitioned column. false: The table does not contain a hash-partitioned column.
tuples	String	Definition Number of rows in the table. Range N/A
create_time	String	Definition Creation time. Range N/A
update_time	String	Definition Update time. Range N/A
average_size	String	Definition Average table size (total table size divided by the number of DNs), which is the ideal size of tables distributed on each DN. Range N/A
max_ratio	String	Definition Ratio of the maximum table size on a single DN to the total table size. Range N/A
min_ratio	String	Definition Ratio of the minimum table size on a single DN to the total table size. Range N/A
skew_size	String	Definition Table skew (the maximum table size on a single DN minus the minimum table size on a single DN). Range N/A
skew_ratio	String	Definition Table skew ratio (skew size divided by total table size). Range N/A
skew_stddev	String	Definition Standard deviation of table distribution. (For two tables of the same size, a larger deviation indicates a more severe skew.) Range N/A

Example Request

Querying the top 20 tables by storage usage in an instance

GET https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/3d39c18788b54a919bab633874c159dfin14/instances/3d39c18788b54a919bab633874c159dfin01/top-table-volume?job_id=SPACE_ANALYTICS_-121b4edd-940b-4b4f-a246-334f1a6658d6-47ec&node_id=a8dfad34a4b246f49a12012914b727ddno14

Obtaining the ID of the job for querying the top 20 tables by storage usage

GET https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/3d39c18788b54a919bab633874c159dfin14/instances/3d39c18788b54a919bab633874c159dfin01/top-table-volume

Example Response

Top 20 tables by storage usage in an instance queried.

{
    "table_volumes": [
        {
            "id": "17131",
            "table_name": "Table_AAA",
            "table_owner": "Adaptor",
            "database_name": "DB_ttsA",
            "schema_name": "Schema_AA",
            "is_part_type": false,
            "is_hash_cluster_key": false,
            "tuples": "0",
            "create_time": "2025-04-17 11:00:24.667761+08",
            "update_time": "2025-04-17 11:00:24.667761+08",
            "average_size": "3,176 KB",
            "max_ratio": "0.336",
            "min_ratio": "0.330",
            "skew_size": "57344",
            "skew_ratio": "0.006",
            "table_size": "24 KB",
            "skew_stddev": "29537"
        },
        {
            "id": "17137",
            "table_name": "Table_BAA",
            "table_owner": "Adaptor",
            "database_name": "DB_ttsB",
            "schema_name": "Schema_BA",
            "is_part_type": false,
            "is_hash_cluster_key": false,
            "tuples": "0",
            "create_time": "2025-04-17 11:00:44.878895+08",
            "update_time": "2025-04-17 11:00:44.878895+08",
            "average_size": "3171 kB",
            "max_ratio": "0.336",
            "min_ratio": "0.330",
            "table_size": "24 KB",
            "skew_size": "65536",
            "skew_ratio": "0.007",
            "skew_stddev": "33108"
        }
    ],
    "total_count": 2,
    "state": "FINISHED"
}

ID of the job for querying the top 20 tables by storage usage obtained.

{
    "job_id": "SPACE_ANALYTICS_-121b4edd-940b-4b4f-a246-334f1a6658d6-47ec",
    "node_id": "a8dfad34a4b246f49a12012914b727ddno14"
}

Status Codes

Normal
200
Abnormal
For details, see Status Codes.

Error Codes

For details, see Error Codes.

Parent topic: Data Storage Insights

Previous topic: Querying the Storage Usage of Tables in a Specified Schema

Next topic: Session Management

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot