Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ Data Storage Insights/ Querying the Storage Usage of Tables in a Specified Schema

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

View PDF

Querying the Storage Usage of Tables in a Specified Schema

Function

This API is used to query the storage usage of tables in a specified schema. 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

POST /v3.1/{project_id}/instances/{instance_id}/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

Request Parameters

**Table 2** 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

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
database_name	Yes	String	Definition Database name. Constraints N/A Range N/A Default Value N/A
schema_names	Yes	Array of strings	Definition Schema names. Constraints N/A
table_name	No	String	Definition Table name. Constraints N/A Range N/A Default Value N/A
user_name	No	String	Definition Username of a table. Constraints N/A Range N/A Default Value N/A
sort_key	No	String	Definition Sorting field. Constraints N/A Range table_size: table size id: table ID table_name: table name table_owner: name of the user that the table belongs to database_name: database name schema_name: schema name is_part_type: whether the table or index has the property of a partitioned table is_hash_cluster_key: whether the table contains a hash-partitioned column tuples: number of rows in the table create_time: creation time update_time: update time average_size: average table size (total table size divided by the number of DNs), which is the ideal size of tables distributed on each DN max_ratio: ratio of the maximum table size on a single DN to the total table size min_ratio: ratio of the minimum table size on a single DN to the total table size skew_size: table skew (the maximum table size on a single DN minus the minimum table size on a single DN) skew_ratio: table skew ratio (skew size divided by total table size) skew_stddev: standard deviation of table distribution (For two tables of the same size, a larger deviation indicates a more severe skew.) Default Value N/A
sort_order	No	String	Definition Sorting method. Constraints N/A Range DESC: descending order desc: descending order ASC: ascending order asc: ascending order Default Value N/A
limit	No	Integer	Definition Number of records returned by a query. Constraints The value must be a non-negative integer. Range 1–100 Default Value 10
offset	No	Integer	Definition Index offset. The query starts from the next piece of data indexed by this parameter. Constraints The value must be a non-negative integer. Range 0–10000 Default Value 0

Response Parameters

**Table 4** Response body parameters
Parameter	Type	Description
table_volumes	Array of objects	Definition Storage usage of tables in a database. For details, see Table 5.
total_count	Integer	Definition Total number. Range N/A

**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 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 storage usage of tables in a specified schema

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/3d39c18788b54a919bab633874c159dfin14/instances/3d39c18788b54a919bab633874c159dfin01/table-volume
{
  "database_name": "db_tpcc",
  "schema_names": ["Schema_AA"],
  "table_name": "Table_AAA",
  "username": "admin",  
  "sort_key": "table_name",
  "sort_order": "asc",
  "limit": 10,
  "offset": 0
}

Example Response

{
    "table_volumes": [
        {
            "id": "17131",
            "table_name": "Table_AAA",
            "table_owner": "Adaptor",
            "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": ".336",
            "min_ratio": ".330",
            "skew_size": "57344",
            "skew_ratio": ".006",
            "table_size": "24 KB",
            "database_name": "db_tpcc",
            "skew_stddev": "29537"
        }
    ],
    "total_count": 1
}