Help Center/ GeminiDB/ API Reference/ APIs v3 (Recommended)/ Instances/ Querying the Memory Mapping List and Details
Updated on 2025-09-04 GMT+08:00

Querying the Memory Mapping List and Details

Function

This API is used to query the memory mapping list and details based on specified conditions.

Constraints

This API can be used only on primary/standby GeminiDB Redis instances.

URI

GET https://{Endpoint}/v3/{project_id}/dbcache/mappings

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Explanation:

Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID.

Constraints:

N/A

Values:

N/A

Default value:

N/A

Table 2 Query parameters

Parameter

Mandatory

Type

Description

id

No

String

Explanation:

Mapping ID, which can be obtained by calling the API for querying the memory mapping list and details.

Constraints:

N/A

Values:

N/A

Default value:

N/A

name

No

String

Explanation:

Mapping name. If you enter a name starting with an asterisk (*), fuzzy search results are returned. If you enter a valid name, an exact result is returned.

Constraints:

N/A

Values:

N/A

Default value:

N/A

source_instance_id

No

String

Explanation:

Source instance ID

Constraints:

N/A

Values:

N/A

Default value:

N/A

source_instance_name

No

String

Explanation:

Source instance name. If you enter a name starting with an asterisk (*), fuzzy search results are returned. If you enter a valid name, an exact result is returned.

Constraints:

N/A

Values:

N/A

Default value:

N/A

target_instance_id

No

String

Explanation:

Target instance ID

Constraints:

N/A

Values:

N/A

Default value:

N/A

target_instance_name

No

String

Explanation:

Target instance name. If you enter a name starting with an asterisk (*), fuzzy search results are returned. If you enter a valid name, an exact result is returned.

Constraints:

N/A

Values:

N/A

Default value:

N/A

offset

No

Integer

Explanation:

Index offset. The query starts from the next piece of data indexed by this parameter.

Constraints:

The value must be a non-negative integer.

Values:

≥ 0

Default value:

0: The query starts from the first data record.

limit

No

Integer

Explanation:

Maximum records to be queried

Constraints:

N/A

Values:

1100

Default value:

100

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Explanation:

User token

You can obtain the token by calling the IAM API by following Obtaining a User Token Through Password Authentication.

Constraints:

N/A

Values:

N/A

Default value:

N/A

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

total_count

Integer

Explanation:

Total number of records

Values:

N/A

dbcache_mappings

Array of objects in Table 5

Explanation:

Memory mapping information

Values:

N/A

Table 5 QueryDBCacheMappingResponse

Parameter

Type

Description

id

String

Explanation:

Memory acceleration mapping ID

Values:

N/A

name

String

Explanation:

Memory mapping name

Values:

N/A

source_instance_id

String

Explanation:

Source instance ID

Values:

N/A

source_instance_name

String

Explanation:

Source instance name

Values:

N/A

target_instance_id

String

Explanation:

Target instance ID

Values:

N/A

target_instance_name

String

Explanation:

Target instance name

Values:

N/A

status

String

Explanation:

Memory mapping relationship

Values:

  • normal: A memory mapping is normal.
  • creating: A memory mapping is being created.
  • createfail: A memory mapping failed to be created.
  • deleting: A memory mapping is being deleted.
  • stopped: A memory mapping is stopped.
  • deleted: A memory mapping is deleted.

created

String

Explanation:

Time when a memory mapping was created

Values:

N/A

updated

String

Explanation:

Last time when a memory mapping was changed

Values:

N/A

rule_count

Integer

Explanation:

Number of rules in a memory mapping

Values:

N/A

Example Request

Querying the first 10 memory mappings

GET https://{endpoint}/v3/054e292c9880d4992f02c0196d3ea468/dbcache/mappings?offset=0&limit=10

Example Response

Status code: 200

Successful request

{ 
  "total_count" : 1, 
  "dbcache_mappings" : [ { 
    "id" : "0231e002-d278-4df8-815c-8284164168e5", 
    "name" : "dbcache_rule_01", 
    "source_instance_id" : "d8e6ca5a624745bcb546a227aa3ae1cfin01", 
    "target_instance_id" : "9136fd2a9fcd405ea4674276ce36dae8in12", 
    "source_instance_name" : "source_name", 
    "target_instance_name" : "target_name", 
    "status" : "normal", 
    "rule_count" : 10, 
    "created" : "2024-01-17T07:05:52", 
    "updated" : "2024-01-20T08:07:02" 
  } ] 
}

Status Codes

See Status Codes.

Error Codes

See Error Codes.