All Products
Search

This Product

    AnalyticDB:DescribeSQLPatterns

    Document Center

    AnalyticDB:DescribeSQLPatterns

    Last Updated:May 08, 2026

    Call the DescribeSQLPatterns API to retrieve SQL patterns for an AnalyticDB for MySQL cluster within a specified date range.

    Operation description

    • Global public endpoint: adb.aliyuncs.com.

    • Regional public endpoint: adb.<region-id>.aliyuncs.com. For example: adb.cn-hangzhou.aliyuncs.com.

    • Regional VPC endpoint: adb-vpc.<region-id>.aliyuncs.com. For example: adb-vpc.cn-hangzhou.aliyuncs.com.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    adb:DescribeSQLPatterns

    list

    DBCluster

    acs:adb:{#regionId}:{#accountId}:dbcluster/{#DBClusterId}

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    DBClusterId

    string

    Yes

    The cluster ID.

    Note

    You can call the DescribeDBClusters operation to query details, including cluster IDs, for all AnalyticDB for MySQL clusters in a specific region.

    am-bp1r053byu48p****
    StartTime

    string

    Yes

    The start of the time range to query. Specify the time in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

    Note

    • You can query data for the last 14 days only. For example, if the current time is 2021-11-22T12:00:00Z, the earliest time that you can query is 2021-11-09T12:00:00Z.

    • The interval between the start time and the end time cannot exceed 24 hours.

    2021-09-30T00:10:00Z
    EndTime

    string

    Yes

    The end of the time range to query. Specify the time in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

    Note

    The end time must be later than the start time.

    2021-09-30T00:15:00Z
    RegionId

    string

    Yes

    The region ID.

    Note

    You can call the DescribeRegions operation to query the available regions and availability zones for AnalyticDB for MySQL, including the region IDs.

    cn-hangzhou
    Keyword

    string

    No

    The keyword for filtering SQL patterns.

    SELECT
    Order

    string

    Yes

    Specifies how to sort the query results. Set this parameter to a JSON string. Example: [{"Field":"AverageQueryTime","Type":"Asc"}]. The JSON string contains the following fields:

    • Field: The sort field. Valid values:

      • PatternCreationTime: the earliest submission time of the SQL pattern within the specified time range.

      • AverageQueryTime: the average total query time of the SQL pattern within the specified time range.

      • MaxQueryTime: the maximum total query time of the SQL pattern within the specified time range.

      • AverageExecutionTime: the average execution time of the SQL pattern within the specified time range.

      • MaxExecutionTime: the maximum execution time of the SQL pattern within the specified time range.

      • AveragePeakMemory: the average peak memory usage of the SQL pattern within the specified time range.

      • MaxPeakMemory: the maximum peak memory usage of the SQL pattern within the specified time range.

      • AverageScanSize: the average amount of data scanned by the SQL pattern within the specified time range.

      • MaxScanSize: the maximum amount of data scanned by the SQL pattern within the specified time range.

      • QueryCount: the number of times the SQL pattern is executed within the specified time range.

      • FailedCount: the number of failed executions for the SQL pattern within the specified time range.

    • Type: the sort order. Valid values (case-insensitive):

      • Asc: ascending order.

      • Desc: descending order.

    [{"Field":"AverageQueryTime","Type":"Asc"}]
    PageNumber

    integer

    No

    The page number. The value must be an integer greater than 0.

    Note

    The default value is 1.

    1
    PageSize

    integer

    No

    The number of entries per page. Valid values:

    • 30

    • 50

    • 100

    Note

    The default value is 30.

    30
    Lang

    string

    No

    The language of the response. This parameter is used to localize messages such as error details. Valid values:

    • zh: Simplified Chinese (default)

    • en: English

    • ja: Japanese

    • zh-tw: Traditional Chinese

    zh
    UserName

    string

    No

    The username that is used to filter the SQL patterns. If you specify this parameter, only the SQL patterns of the specified user are returned.

    test_user

    Response elements

    Element

    Type

    Description

    Example

    object

    The data returned for the request.

    PageNumber

    integer

    The page number.

    1
    PageSize

    integer

    The number of entries returned per page.

    30
    TotalCount

    integer

    The total number of entries returned.

    1
    PatternDetails

    array<object>

    The details of the SQL patterns.

    object

    The details of an SQL pattern.

    SQLPattern

    string

    The SQL pattern statement.

    SELECT * FROM KEPLER_META_NODE_STATIC_INFO WHERE elastic_node = ? OR (elastic_node = ? AND enable = ?)
    PatternId

    string

    The ID of the SQL pattern.

    5575924945138******
    User

    string

    The database username that submitted the SQL statements matching this pattern.

    reporter
    AccessIp

    string

    The client IP address from which the SQL statements matching this pattern were submitted.

    192.168.xx.xx
    Tables

    string

    The database table scanned by the queries in this pattern.

    tpch.orders
    PatternCreationTime

    string

    The earliest time a query matching this pattern was submitted within the specified time range. The time is in the YYYY-MM-DD HH:MM:SS format.

    2021-11-12 03:06:00
    AverageQueryTime

    number

    The average query time for statements matching this SQL pattern within the specified time range, in milliseconds.

    4
    MaxQueryTime

    integer

    The maximum query time for statements matching this SQL pattern within the specified time range, in milliseconds.

    2341
    AverageExecutionTime

    number

    The average execution time for statements matching this SQL pattern within the specified time range, in milliseconds.

    234.78
    MaxExecutionTime

    integer

    The maximum execution time for statements matching this SQL pattern within the specified time range, in milliseconds.

    2142
    AveragePeakMemory

    number

    The average peak memory usage for statements matching this SQL pattern within the specified time range, in bytes.

    234.22
    MaxPeakMemory

    integer

    The maximum peak memory usage for statements matching this SQL pattern within the specified time range, in bytes.

    234149
    AverageScanSize

    number

    The average data scan size for statements matching this SQL pattern within the specified time range, in bytes.

    234149.23
    MaxScanSize

    integer

    The maximum data scan size for statements matching this SQL pattern within the specified time range, in bytes.

    234149
    QueryCount

    integer

    The number of executions for statements matching this pattern within the specified time range.

    345
    FailedCount

    integer

    The number of failed executions for statements matching this pattern within the specified time range.

    234
    Blockable

    boolean

    Specifies whether queries matching this pattern can be blocked. Valid values:

    • true: The SQL pattern can be blocked.

    • false: The SQL pattern cannot be blocked.

    Note

    AnalyticDB for MySQL supports blocking for only SELECT and INSERT statements.

    true
    QueryTimeSum

    number

    The total query time for statements matching this pattern, in milliseconds.

    5
    QueryTimePercentage

    number

    The percentage of total query time from all patterns that the queries for this pattern consume.

    10
    PeakMemorySum

    number

    The total peak memory used by statements matching this pattern, in bytes.

    5
    PeakMemoryPercentage

    number

    The percentage of total peak memory usage from all patterns that the queries for this pattern consume.

    10
    ScanSizeSum

    number

    The total data scan size for statements matching this pattern, in bytes.

    5
    ScanSizePercentage

    number

    The percentage of the total data scan size from all patterns that the queries for this pattern consume.

    80
    AverageOperatorCost

    number

    The average CPU cost for statements matching this pattern, in milliseconds.

    5
    MaxOperatorCost

    number

    The maximum CPU cost for statements matching this pattern, in milliseconds.

    5
    OperatorCostSum

    number

    The total CPU cost for statements matching this pattern, in milliseconds.

    5
    OperatorCostPercentage

    number

    The percentage of the total CPU cost from all patterns that the queries for this pattern consume.

    20
    AverageScanCost

    number

    The average CPU cost of table scans for statements matching this pattern, in milliseconds.

    5
    MaxScanCost

    number

    The maximum CPU cost of table scans for statements matching this pattern, in milliseconds.

    5
    ScanCostSum

    number

    The total CPU cost of table scans for statements matching this pattern, in milliseconds.

    5
    ScanCostPercentage

    number

    The percentage of the total CPU cost from all table scans that the queries for this pattern consume.

    5
    RequestId

    string

    The ID of the request.

    6BE0EDD1-0DE6-3EB6-81BF-BFE4F2******

    Examples

    Success response

    JSON format

    {
  "PageNumber": 1,
  "PageSize": 30,
  "TotalCount": 1,
  "PatternDetails": [
    {
      "SQLPattern": "SELECT * FROM KEPLER_META_NODE_STATIC_INFO WHERE elastic_node = ? OR (elastic_node = ? AND enable = ?)",
      "PatternId": "5575924945138******",
      "User": "reporter",
      "AccessIp": "192.168.xx.xx",
      "Tables": "tpch.orders",
      "PatternCreationTime": "2021-11-12 03:06:00",
      "AverageQueryTime": 4,
      "MaxQueryTime": 2341,
      "AverageExecutionTime": 234.78,
      "MaxExecutionTime": 2142,
      "AveragePeakMemory": 234.22,
      "MaxPeakMemory": 234149,
      "AverageScanSize": 234149.23,
      "MaxScanSize": 234149,
      "QueryCount": 345,
      "FailedCount": 234,
      "Blockable": true,
      "QueryTimeSum": 5,
      "QueryTimePercentage": 10,
      "PeakMemorySum": 5,
      "PeakMemoryPercentage": 10,
      "ScanSizeSum": 5,
      "ScanSizePercentage": 80,
      "AverageOperatorCost": 5,
      "MaxOperatorCost": 5,
      "OperatorCostSum": 5,
      "OperatorCostPercentage": 20,
      "AverageScanCost": 5,
      "MaxScanCost": 5,
      "ScanCostSum": 5,
      "ScanCostPercentage": 5
    }
  ],
  "RequestId": "6BE0EDD1-0DE6-3EB6-81BF-BFE4F2******"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.