The page introduces all APIs provided by the Meta Service.

API version

For the purpose of compatibility and extension, all future APIs will include a version number in implementation. It is recommended to include the version number when using the APIs. Currently, all existing APIs have been added v1/ as the version identifier.

For example, this is create_instance with its API version identifier:

  1. PUT /MetaService/http/v1/create_instance?token=<token> HTTP/1.1

To ensure compatibility, existing APIs can still be accessed without v1/.

Field values

For certain fields, special attention should be paid to their allowed value ranges and formats.

FieldDescriptionNotes
instanceidID of the data warehouse instance instance in the compute-storage decoupled mode, normally a UUID string. It should follow the format of [0-9a-zA-Z-]+.Example: 6ADDF03D-4C71-4F43-9D84-5FC89B3514F8
cloudunique_idA configuration in be.conf and fe.conf in the compute-storage decoupled mode; should be provided in a createcluster request; the format of it is 1:<instance_id>:<string>, in which the string should conform to the format of [0-9a-zA-Z</em>-]+. The value for each node should be different.Example: 1:regression_instance0:regression-cloud-unique-id-1
cluster_nameIn the compute-storage decoupled mode, this field is required when describing a compute cluster. It must be a unique identifier and its format should match the pattern [a-zA-Z][0-9a-zA-Z]+Example: write_cluster, read_cluster0

create_instance (multiple storage vaults)

Description

This API is used to create an instance, which supports one or more storage vaults (including HDFS and S3). This instance does not contain any node information. The same instance_id cannot be created multiple times.

Request

Use HDFS as the storage vault

  • Syntax for a create_instance request using HDFS as the storage vault
  1. PUT /MetaService/http/create_instance?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string,
  6. "name": string,
  7. "user_id": string,
  8. "vault": {
  9. "hdfs_info" : {
  10. "build_conf": {
  11. "fs_name": string,
  12. "user": string,
  13. "hdfs_kerberos_keytab": string,
  14. "hdfs_kerberos_principal": string,
  15. "hdfs_confs" : [
  16. {
  17. "key": string,
  18. "value": string
  19. }
  20. ]
  21. },
  22. "prefix": string
  23. }
  24. }
  25. }
  • Parameters for a create_instance request using HDFS as the storage vault
ParameterDescriptionRequired/OptionalNotes
instanceidID of the data warehouse instance in the compute-storage decoupled mode, normally a UUID string. It should conform to the format of [0-9a-zA-Z-]+.RequiredExample: 6ADDF03D-4C71-4F43-9D84-5FC89B3514F8
nameInstance name. It should conform to the format of [a-zA-Z][0-9a-zA-Z]+Optional
user_idID of the user who creates the instance. It should conform to the format of [a-zA-Z][0-9a-zA-Z]+Required
vaultStorage vaultRequired
vault.hdfs_infoInformation of the HDFS storage vaultRequired
vault.build_confBuild configuration of the HDFS storage vaultRequired
vault.build_conf.fs_nameHDFS name, normally the connection addressRequired
vault.build_conf.userUser to connect to HDFSRequired
vault.build_conf.hdfs_kerberos_keytabKerberos Keytab pathOptionalRequired when using Kerberos authentication
vault.build_conf.hdfs_kerberos_principalKerberos PrincipalOptionalRequired when using Kerberos authentication
vault.build_conf.hdfs_confsOther configurations of HDFSOptionalCan be filled in as needed
vault.prefixPrefix for data storage; used for data isolationRequiredNormally named after the specific business, such as big_data
  • Example of a create_instance request using HDFS as the storage vault
  1. PUT /MetaService/http/create_instance?token=greedisgood9999 HTTP/1.1
  2. Content-Length: 550
  3. Content-Type: text/plain
  4. {
  5. "instance_id": "sample_instance_id",
  6. "name": "sample_instance_name",
  7. "user_id": "sample_user_id",
  8. "vault": {
  9. "hdfs_info" : {
  10. "build_conf": {
  11. "fs_name": "hdfs://172.21.0.44:4007",
  12. "user": "hadoop",
  13. "hdfs_kerberos_keytab": "/etc/emr.keytab",
  14. "hdfs_kerberos_principal": "hadoop/172.30.0.178@EMR-XXXYYY",
  15. "hdfs_confs" : [
  16. {
  17. "key": "hadoop.security.authentication",
  18. "value": "kerberos"
  19. }
  20. ]
  21. },
  22. "prefix": "sample_prefix"
  23. }
  24. }
  25. }

Use object storage as the storage vault

  • Syntax for a create_instance request using object storage as the storage vault
  1. PUT /MetaService/http/create_instance?token=<token HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string,
  6. "name": string,
  7. "user_id": string,
  8. "vault": {
  9. "obj_info": {
  10. "ak": string,
  11. "sk": string,
  12. "bucket": string,
  13. "prefix": string,
  14. "endpoint": string,
  15. "external_endpoint": string,
  16. "region": string,
  17. "provider": string
  18. }
  19. }
  20. }
  • Parameters for a create_instance request using object storage as the storage vault
ParameterDescriptionRequired/OptionalNotes
instanceidID of the data warehouse instance in the compute-storage decoupled mode, normally a UUID string. It should conform to the format of [0-9a-zA-Z-]+.RequiredExample: 6ADDF03D-4C71-4F43-9D84-5FC89B3514F8
nameInstance name. It should conform to the format of [a-zA-Z][0-9a-zA-Z]+Optional
user_idID of the user who creates the instance. It should conform to the format of [a-zA-Z][0-9a-zA-Z]+Required
vault.obj_infoS3 link configurationRequired
vault.obj_info.akS3 Access KeyRequired
vault.obj_info.skS3 Secret KeyRequired
vault.obj_info.bucketS3 bucket nameRequired
vault.obj_info.prefixPrefix for data storage on S3OptionalIf this parameter is empty, the default storage location will be in the root directory of the bucket, such as big_data
obj_info.endpointS3 endpointRequiredThe domain or IP:port, not including the scheme prefix such as http://.
obj_info.regionS3 regionRequiredIf using MinIO, this parameter can be filled in with any value.
obj_info.external_endpointS3 external endpointRequiredNormally consistent with the endpoint. Compatible with OSS. Note the difference between external and internal OSS.
vault.obj_info.providerS3 provider; options include OSS, S3, COS, OBS, BOS, GCP, and AZURERequiredIf using MinIO, simply fill in S3.
  • Example of a create_instance request using object storage as the storage vault
  1. PUT /MetaService/http/create_instance?token=greedisgood9999 HTTP/1.1
  2. Content-Length: 441
  3. Content-Type: text/plain
  4. {
  5. "instance_id": "sample_instance_id",
  6. "name": "sample_instance_name",
  7. "user_id": "sample_user_id",
  8. "vault": {
  9. "obj_info": {
  10. "ak": "ak_xxxxxxxxxxx",
  11. "sk": "sk_xxxxxxxxxxx",
  12. "bucket": "sample_bucket_name",
  13. "prefix": "sample_prefix",
  14. "endpoint": "cos.ap-beijing.myqcloud.com",
  15. "external_endpoint": "cos.ap-beijing.myqcloud.com",
  16. "region": "ap-beijing",
  17. "provider": "COS"
  18. }
  19. }
  20. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "ALREADY_EXISTED",
  3. "msg": "instance already existed, instance_id=instance_id_deadbeef"
  4. }

create_instance (one storage vault)

Meta Service API - 图1caution

This is a legacy interface and is deprecated in newer versions. It should not be used in private deployment.

Description

This API is used to create an instance, which only supports one storage vault (must be S3). This instance does not contain any node information. The same instance_id cannot be created multiple times.

Request

  • Syntax
  1. PUT /MetaService/http/create_instance?token=<token HTTP/1.1
  2. Content-Length: <ContentLength
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string,
  6. "name": string,
  7. "user_id": string,
  8. "obj_info": {
  9. "ak": string,
  10. "sk": string,
  11. "bucket": string,
  12. "prefix": string,
  13. "endpoint": string,
  14. "region": string,
  15. "external_endpoint": string,
  16. "provider": string
  17. "user_id": string
  18. },
  19. "ram_user": {
  20. "user_id": string,
  21. "ak": string,
  22. "sk": string
  23. }
  24. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instanceidID of the data warehouse instance in the compute-storage decoupled mode, normally a UUID string. It should conform to the format of [0-9a-zA-Z-]+.RequiredExample: 6ADDF03D-4C71-4F43-9D84-5FC89B3514F8
nameInstance name. It should conform to the format of [a-zA-Z][0-9a-zA-Z]+Optional
user_idID of the user who creates the instance. It should conform to the format of [a-zA-Z][0-9a-zA-Z]+Required
obj_infoS3 link configurationRequired
obj_info.akS3 Access KeyRequired
obj_info.skS3 Secret KeyRequired
obj_info.bucketS3 bucket nameRequired
obj_info.prefixPrefix for data storage on S3OptionalIf this parameter is empty, the default storage location will be in the root directory of the bucket.
obj_info.endpointS3 endpointRequiredThe domain or IP:port, not including the scheme prefix such as http://.
obj_info.regionS3 regionRequired
obj_info.external_endpointS3 external endpointOptionalCompatible with OSS. Note the difference between external and internal OSS.
obj_info.providerS3 providerRequired
obj_info.user_iduser_id for bucketOptionalUsed to identify the object that needs to have its AK/SK changed during AK/SK rotation.
ram_userram_user, used for external bucket authorizationOptional
ram_user.user_idRequired
ram_user.akRequired
ram_user.skRequired
  • Example
  1. PUT /MetaService/http/create_instance?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": "123456",
  6. "name": "name",
  7. "user_id": "abcdef",
  8. "obj_info": {
  9. "ak": "test-ak1",
  10. "sk": "test-sk1",
  11. "bucket": "test-bucket",
  12. "prefix": "test-prefix",
  13. "endpoint": "test-endpoint",
  14. "region": "test-region",
  15. "provider": "OBS",
  16. "user_id": "xxx"
  17. }
  18. "ram_user": {
  19. "user_id": string,
  20. "ak": string,
  21. "sk": string
  22. }
  23. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "ALREADY_EXISTED",
  3. "msg": "instance already existed, instance_id=instance_id_deadbeef"
  4. }

drop_instance

Description

This API is used to delete an existing instance. After marking it for deletion, the Recycler will asynchronously reclaim the resources.

Request

  • Syntax
  1. PUT /MetaService/http/drop_instance?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string
  6. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idinstance_idRequiredGlobally unique
  • Example
  1. PUT /MetaService/http/drop_instance?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": "123456"
  6. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INVALID_ARGUMENT",
  3. "msg": "failed to drop instance, instance has clusters"
  4. }

get_instance

Description

This API is used to query the details of an instance, including information of S3, compute clusters, and stages. It can be used for debugging purposes.

Request

  • Syntax
  1. GET /MetaService/http/get_instance?token=greedisgood9999&instance_id={instance_id} HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idinstance_idRequiredGlobally unique
  • Example
  1. GET /MetaService/http/get_instance?token=greedisgood9999&instance_id=test-instance HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
resultDetails of the instanceRequired
result.user_idUser ID used to create the instanceRequired
result.instance_idinstance_id passed in when creating the instanceRequired
result.nameUser name used to create the instanceRequired
result.clustersList of compute clusters within the instanceRequired
result.mtimeModification time of the instanceRequired
result.obj_infoS3 information list associated with the instanceRequired
result.stagesList of stages associated with the instanceRequired
result.statusInstance statusOptionalIf an instance is dropped, its status will turn into DELETED.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": "",
  4. "result": {
  5. "user_id": "gavin-user-id",
  6. "instance_id": "regression_instance0",
  7. "name": "test-instance",
  8. "clusters": [
  9. {
  10. "cluster_id": "RESERVED_CLUSTER_ID_FOR_SQL_SERVER",
  11. "cluster_name": "RESERVED_CLUSTER_NAME_FOR_SQL_SERVER",
  12. "type": "SQL",
  13. "nodes": [
  14. {
  15. "cloud_unique_id": "1:regression_instance0:regression-cloud-unique-id-fe-1",
  16. "ip": "127.0.0.1",
  17. "ctime": "1669260437",
  18. "mtime": "1669260437",
  19. "edit_log_port": 12103,
  20. "node_type": "FE_MASTER"
  21. }
  22. ]
  23. },
  24. {
  25. "cluster_id": "regression_test_cluster_id0",
  26. "cluster_name": "regression_test_cluster_name0",
  27. "type": "COMPUTE",
  28. "nodes": [
  29. {
  30. "cloud_unique_id": "1:regression_instance0:regression-cloud-unique-id0",
  31. "ip": "127.0.0.1",
  32. "ctime": "1669260437",
  33. "mtime": "1669260437",
  34. "heartbeat_port": 11102
  35. }
  36. ],
  37. "mysql_user_name": [
  38. "root"
  39. ]
  40. },
  41. {
  42. "cluster_id": "regression_test_cluster_id1",
  43. "cluster_name": "regression_test_cluster_name1",
  44. "type": "COMPUTE",
  45. "nodes": [
  46. {
  47. "cloud_unique_id": "1:regression_instance0:regression-cloud-unique-id0",
  48. "ip": "127.0.0.1",
  49. "ctime": "1669260437",
  50. "mtime": "1669260437",
  51. "heartbeat_port": 14102
  52. }
  53. ],
  54. "mysql_user_name": [
  55. "jack",
  56. "lx"
  57. ]
  58. },
  59. {
  60. "cluster_id": "regression_test_cluster_id2",
  61. "cluster_name": "regression_test_cluster_name2",
  62. "type": "COMPUTE",
  63. "nodes": [
  64. {
  65. "cloud_unique_id": "1:regression_instance0:regression-cloud-unique-id0",
  66. "ip": "127.0.0.1",
  67. "ctime": "1669260437",
  68. "mtime": "1669260437",
  69. "heartbeat_port": 16102
  70. }
  71. ]
  72. }
  73. ],
  74. "obj_info": [
  75. {
  76. "ctime": "1669260437",
  77. "mtime": "1669260437",
  78. "id": "1",
  79. "ak": "akak",
  80. "sk": "sksk",
  81. "bucket": "justtmp-bj-1308700295",
  82. "prefix": "dx-test",
  83. "endpoint": "cos.ap-beijing.myqcloud.com",
  84. "region": "ap-beijing",
  85. "provider": "COS",
  86. "external_endpoint": ""
  87. }
  88. ],
  89. "stages": [
  90. {
  91. "mysql_user_name": [
  92. "admin"
  93. ],
  94. "obj_info": {
  95. "id": "1",
  96. "prefix": "dx-test/stage/admin/admin"
  97. },
  98. "stage_id": "c56f5d01-0ae2-4719-8be2-8b52b3144f60",
  99. "mysql_user_id": [
  100. "admin"
  101. ]
  102. },
  103. {
  104. "type": "EXTERNAL",
  105. "name": "smoke_test_tpch",
  106. "obj_info": {
  107. "ak": "akak",
  108. "sk": "sksk",
  109. "bucket": "gavin-test-bj",
  110. "prefix": "smoke-test",
  111. "endpoint": "oss-cn-beijing.aliyuncs.com",
  112. "region": "cn-beijing",
  113. "provider": "OSS"
  114. },
  115. "stage_id": "261c3565-7ac3-4cb5-9c82-a9bc38cff8e8",
  116. "properties": {
  117. "default.file.column_separator": "|"
  118. }
  119. }
  120. ]
  121. }
  122. }

set_instance_status

Description

This API is used to set the status of an instance to either NORMAL or OVERDUE.

Request

  • Syntax
  1. PUT /MetaService/http/set_instance_status?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string
  6. "op": string
  7. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idRequired
opIt should be either “SET_NORMAL” or “SET_OVERDUE”.Required
  • Request example
  1. curl '127.0.0.1:5000/MetaService/http/set_instance_status?token=greedisgood9999' -d '{
  2. "instance_id":"test_instance",
  3. "op": "SET_OVERDUE"
  4. }'
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequired
msgError messageRequired
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }

get_obj_store_info

Description

This API is used to retrieve the S3 Access Key (AK) and Secret Key (SK) configured for a given instance. This API can be called multiple times using the same parameters.

Request

  • Syntax
  1. PUT /MetaService/http/get_obj_store_info?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {"cloud_unique_id": "<cloud_unique_id>"}
  • Parameter
ParameterDescriptionRequired/OptionalNotes
cloud_unique_idcloud_unique_id of nodeRequiredThe unique_id of a node under an instance can be used to retrieve the S3 information configured for the entire instance.
  • Example
  1. PUT /MetaService/http/get_obj_store_info?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {"cloud_unique_id": "1:regression_instance0:cloud_unique_id_compute_node1"}
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
resultResult objectsRequired
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": "",
  4. "result": {
  5. "obj_info": [
  6. {
  7. "ctime": "1662543056",
  8. "mtime": "1662543056",
  9. "id": "1",
  10. "ak": "xxxx",
  11. "sk": "xxxxx",
  12. "bucket": "doris-xxx-1308700295",
  13. "prefix": "selectdb-xxxx-regression-prefix",
  14. "endpoint": "cos.ap-yyy.xxxx.com",
  15. "region": "ap-xxx"
  16. }
  17. ]
  18. }
  19. }
  • Example of unsuccessful response
  1. {
  2. "code": "INVALID_ARGUMENT",
  3. "msg": "empty instance_id"
  4. }

update_ak_sk

Description

This API is used to update the S3 and RAM_USER Access Key (AK) and Secret Key (SK) information configured for a given instance. It uses user_id to identify the item to be modified. This API is typically used for AK/SK rotation, and calling it with the same parameters will result in an error.

Request

  • Syntax
  1. PUT /MetaService/http/update_ak_sk?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string,
  6. "internal_bucket_user":[
  7. {
  8. "user_id": string,
  9. "ak": string,
  10. "sk": string
  11. },
  12. {
  13. "user_id": string,
  14. "ak": string,
  15. "sk": string
  16. }
  17. ],
  18. "ram_user": {
  19. "user_id": string,
  20. "ak": string,
  21. "sk": string
  22. }
  23. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idinstance_idRequired
internal_bucket_userbucket_user list to be modifiedEither fill in internal_bucket_user or ram_userArray
internal_bucket_user.user_idThe relevant user_idRequired
internal_bucket_user.akRequired
internal_bucket_user.skRequired
ram_userram_user to be modifiedEither fill in internal_bucket_user or ram_user
ram_user.user_idThe relevant user_idRequired
ram_user.akRequired
ram_user.skRequired
  • Example
  1. PUT /MetaService/http/update_ak_sk?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id":"test",
  6. "internal_bucket_user":[
  7. {
  8. "user_id": "bucket_user_id_1",
  9. "ak": "xxxx",
  10. "sk": "xxxx"
  11. },
  12. {
  13. "user_id": "bucket_user_id_2",
  14. "ak": "xxxx",
  15. "sk": "xxxx"
  16. }
  17. ],
  18. "ram_user": {
  19. "user_id": "ram_user_id",
  20. "ak": "xxxx",
  21. "sk": "xxxx"
  22. }
  23. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INVALID_ARGUMENT",
  3. "msg": "ak sk eq original, please check it"
  4. }

legacy_update_ak_sk

Meta Service API - 图2caution

This is a legacy interface and is deprecated in newer versions.

Description

This API is used to update the S3 Access Key (AK) and Secret Key (SK) configured for an instance. It uses ID to identify the item to be modified. The ID can be obtained by calling get_obj_store_info. Calling this API multiple times with the same parameters will result in an error.

Request

  • Syntax
  1. PUT /MetaService/http/legacy_update_ak_sk?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": string,
  6. "obj": {
  7. "id": string,
  8. "ak": string,
  9. "sk": string,
  10. }
  11. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
cloud_unique_idcloud_unique_id of nodeRequired
objObjectRequiredS3 information object
obj.idObject IDRequiredID ranges from 1 to 10
obj.akObject Access KeyRequired
obj.skObject Secret KeyRequiredString array
  • Example
  1. PUT /MetaService/http/legacy_update_ak_sk?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": "1:regression_instance0:cloud_unique_id_compute_node1",
  6. "obj": {
  7. "id": "1",
  8. "ak": "test-ak",
  9. "sk": "test-sk",
  10. }
  11. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INVALID_ARGUMENT",
  3. "msg": "ak sk eq original, please check it"
  4. }

add_obj_info

Description

This API is used to add S3 configurations for an instance. It supports a maximum of 10 S3 configurations, and each configuration must not exceed 1024 bytes in size.

Request

  • Syntax
  1. PUT /MetaService/http/add_obj_info?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": string,
  6. "obj": {
  7. "ak": string,
  8. "sk": string,
  9. "bucket": string,
  10. "prefix": string,
  11. "endpoint": string,
  12. "region": string
  13. }
  14. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
cloud_unique_idcloud_unique_id of nodeRequired
objObjectRequiredS3 object
obj.akS3 Access Key to be addedRequired
obj.skS3 Secret Key to be addedRequired
obj.bucketS3 bucket to be addedRequired
obj.prefixS3 prefix to be addedRequired
obj.endpointS3 endpoint to be addedRequired
obj.regionS3 region to be addedRequired
  • Example
  1. PUT /MetaService/http/add_obj_info?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": "1:regression_instance0:cloud_unique_id_compute_node1",
  6. "obj": {
  7. "ak": "test-ak91",
  8. "sk": "test-sk1",
  9. "bucket": "test-bucket",
  10. "prefix": "test-prefix",
  11. "endpoint": "test-endpoint",
  12. "region": "test-region"
  13. }
  14. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INVALID_ARGUMENT",
  3. "msg": "s3 conf info err, please check it"
  4. }

add_cluster

Description

This API is used to create a compute cluster that belongs to an instance. The compute cluster contains information about a number (greater than or equal to 0) of nodes of the same type. This API cannot be called with the same parameters.

Request

  • Syntax
  1. PUT /MetaService/http/add_cluster?token=<token HTTP/1.1
  2. Content-Length: <ContentLength
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string,
  6. "cluster": object {
  7. "cluster_name": string,
  8. "cluster_id": string,
  9. "type": enum,
  10. "nodes": [
  11. {
  12. "cloud_unique_id": string,
  13. "ip": string,
  14. "heartbeat_port": int
  15. }
  16. ]
  17. }
  18. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idinstance_idRequiredGlobally unique
clusterCluster objectRequired
cluster.cluster_nameCluster nameRequiredThe FE cluster name is special. The default value of it is RESERVED_CLUSTER_NAME_FOR_SQL_SERVER. This can be modified by configuring cloud_observer_cluster_name in the fe.conf file.
cluster.cluster_idCluster IDRequiredThe FE cluster ID is special. The default value of it is RESERVED_CLUSTER_ID_FOR_SQL_SERVER. This can be modified by configuring cloud_observer_cluster_id in the fe.conf file.
cluster.typeCluster node typeRequiredTwo types are supported: SQL and COMPUTE. SQL represents the SQL Service corresponding to FE, while COMPUTE means that the compute nodes are corresponding to BE.
cluster.nodesNodes in the clusterRequiredArray
cluster.nodes.cloud_unique_idcloud_unique_id of nodesRequiredcloud_unique_id in fe.conf and be.conf
cluster.nodes.ipNode IPRequiredWhen deploying FE/BE in FQDN mode, this field should be the domain name.
cluster.nodes.hostNode domain nameOptionalThis field is required when deploying FE/BE in FQDN mode.
cluster.nodes.heartbeat_portHeartbeat port of BERequired for BEheartbeat_service_port in be.conf
cluster.nodes.edit_log_portEdit log port of FERequired for FEedit_log_port in fe.conf
cluster.nodes.node_typeFE node typeRequired for FEThis field is required when the cluster type is SQL. It can be either FE_MASTER or FE_OBSERVER. FE_MASTER indicates that the node is of Master role, and FE_OBSERVER indicates that the node is an Observer. Note that in an SQL type cluster, the nodes array can only have one FE_MASTER node, but it can include multiple FE_OBSERVER nodes.
  • Example
  1. PUT /MetaService/http/add_cluster?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": "123456",
  6. "cluster": {
  7. "cluster_name": "cluster_name1",
  8. "cluster_id": "cluster_id1",
  9. "type": "COMPUTE",
  10. "nodes": [
  11. {
  12. "cloud_unique_id": "1:regression_instance0:cloud_unique_id_compute_node1",
  13. "ip": "172.21.0.5",
  14. "heartbeat_port": 9050
  15. }
  16. ]
  17. }
  18. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INTERANAL_ERROR",
  3. "msg": "cluster is SQL type, must have only one master node, now master count: 0"
  4. }

get_cluster

Description

This API is used to retrieve the information of a compute cluster. It can be called repeatedly.

Request

  • Syntax
  1. PUT /MetaService/http/get_cluster?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id":string,
  6. "cloud_unique_id":string,
  7. "cluster_name":string,
  8. "cluster_id":string
  9. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
cloud_unique_idcloud_unique_idRequiredIt can be used to retrieve the relevant instance_id
cluster_nameCluster nameOptionalNote: One of the three parameters (cluster_name, cluster_id, and mysql_user_name) must be provided. If all three are empty, the API will return the information of all clusters under the instance.
cluster_idCluster IDOptionalNote: One of the three parameters (cluster_name, cluster_id, and mysql_user_name) must be provided. If all three are empty, the API will return the information of all clusters under the instance.
mysql_user_nameAvailable cluster configured by mysql_user_nameOptionalNote: One of the three parameters (cluster_name, cluster_id, and mysql_user_name) must be provided. If all three are empty, the API will return the information of all clusters under the instance.
  • Example
  1. PUT /MetaService/http/get_cluster?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id":"regression_instance0",
  6. "cloud_unique_id":"1:regression_instance0:regression-cloud-unique-id-fe-1",
  7. "cluster_name":"RESERVED_CLUSTER_NAME_FOR_SQL_SERVER",
  8. "cluster_id":"RESERVED_CLUSTER_ID_FOR_SQL_SERVER"
  9. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
resultResult objectsRequired
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": "",
  4. "result": {
  5. "cluster_id": "cluster_id1",
  6. "cluster_name": "cluster_name1",
  7. "type": "COMPUTE",
  8. "nodes": [
  9. {
  10. "cloud_unique_id": "1:regression_instance0:cloud_unique_id_compute_node0",
  11. "ip": "172.21.16.42",
  12. "ctime": "1662695469",
  13. "mtime": "1662695469",
  14. "heartbeat_port": 9050
  15. }
  16. ]
  17. }
  18. }
  • Example of unsuccessful response
  1. {
  2. "code": "NOT_FOUND",
  3. "msg": "fail to get cluster with instance_id: \"instance_id_deadbeef\" cloud_unique_id: \"1:regression_instance0:xxx_cloud_unique_id_compute_node0\" cluster_name: \"cluster_name\" "
  4. }

drop_cluster

Description

This API is used to delete the information of a compute cluster under an instance. Calling this API multiple times with the same parameters will result in an error.

Request

  • Syntax
  1. PUT /MetaService/http/drop_cluster?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id":string,
  6. "cluster": {
  7. "cluster_name": string,
  8. "cluster_id": string,
  9. }
  10. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idinstance_idRequired
clusterCluster objectRequired
cluster.cluster_nameName of the cluster to be deletedRequired
cluster.cluster_idID of the cluster to be deletedRequired
  • Example
  1. PUT /MetaService/http/drop_cluster?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id":"regression_instance0",
  6. "cluster": {
  7. "cluster_name": "cluster_name1",
  8. "cluster_id": "cluster_id1",
  9. }
  10. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INTERANAL_ERROR",
  3. "msg": "failed to find cluster to drop, instance_id=dx_dnstance_id_deadbeef cluster_id=11111 cluster_name=2222"
  4. }

rename_cluster

Description

This API is used to rename a compute cluster under an instance. It searches for the corresponding cluster based on the provided cluster_id and renames it accordingly. Calling this API multiple times with the same parameters will result in an error.

Request

  • Syntax
  1. PUT /MetaService/http/rename_cluster?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id":string,
  6. "cluster": {
  7. "cluster_name": string,
  8. "cluster_id": string,
  9. }
  10. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idinstance_idRequired
clusterCluster objectRequired
cluster.cluster_nameNew cluster nameRequired
cluster.cluster_idID of the cluster to be renamedRequiredBased on this, the system retrieves the corresponding cluster, and renames it accordingly.
  • Example
  1. PUT /MetaService/http/rename_cluster?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id":"regression_instance0",
  6. "cluster": {
  7. "cluster_name": "cluster_name2",
  8. "cluster_id": "cluster_id1",
  9. }
  10. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INTERANAL_ERROR",
  3. "msg": "failed to rename cluster, name eq original name, original cluster is {\"cluster_id\":\"3333333\",\"cluster_name\":\"444444\",\"type\":\"COMPUTE\"}"
  4. }

add_node

Description

This API is used to add nodes of the same type to a specific compute cluster under an instance. Calling this API multiple times with the same parameters will result in an error.

This API can be used to add either FE or BE nodes.

Request

  • Syntax
  1. PUT /MetaService/http/add_node?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string,
  6. "cluster": {
  7. "cluster_name": string,
  8. "cluster_id": string,
  9. "type": enum,
  10. "nodes": [
  11. {
  12. "cloud_unique_id": string,
  13. "ip": string,
  14. "heartbeat_port": int
  15. },
  16. {
  17. "cloud_unique_id": string,
  18. "ip": string,
  19. "heartbeat_port": int
  20. }
  21. ]
  22. }
  23. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idinstance_idRequired
clusterCluster objectRequired
cluster.cluster_nameName of the target clusterRequired
cluster.cluster_idID of the target clusterRequired
cluster.typeCluster node typeRequiredTwo types are supported: SQL and COMPUTE. SQL represents the SQL Service corresponding to FE, while COMPUTE means that the compute nodes are corresponding to BE.
cluster.nodesNodes in the clusterRequiredArray
cluster.nodes.cloud_unique_idcloud_unique_id of nodesRequiredcloud_unique_id in fe.conf and be.conf
cluster.nodes.ipNode IPRequiredWhen deploying FE/BE in FQDN mode, this field should be the domain name.
cluster.nodes.hostNode domain nameOptionalThis field is required when deploying FE/BE in FQDN mode.
cluster.nodes.heartbeat_portHeartbeat port of BERequired for BEheartbeat_service_port in be.conf
cluster.nodes.edit_log_portEdit log port of FERequired for FEedit_log_port in fe.conf
cluster.nodes.node_typeFE node typeRequired for FEThis field is required when the cluster type is SQL. It can be either FE_MASTER or FE_OBSERVER. FE_MASTER indicates that the node is of Master role, and FE_OBSERVER indicates that the node is an Observer. Note that in an SQL type cluster, the nodes array can only have one FE_MASTER node, but it can include multiple FE_OBSERVER nodes.
  • Example
  1. PUT /MetaService/http/add_node?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": "instance_id_deadbeef_1",
  6. "cluster": {
  7. "cluster_name": "cluster_name1",
  8. "cluster_id": "cluster_id1",
  9. "type": "COMPUTE",
  10. "nodes": [
  11. {
  12. "cloud_unique_id": "1:regression_instance0:cloud_unique_id_compute_node2",
  13. "ip": "172.21.0.50",
  14. "heartbeat_port": 9051
  15. },
  16. {
  17. "cloud_unique_id": "1:regression_instance0:cloud_unique_id_compute_node3",
  18. "ip": "172.21.0.52",
  19. "heartbeat_port": 9052
  20. }
  21. ]
  22. }
  23. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INTERANAL_ERROR",
  3. "msg": "cloud_unique_id is already occupied by an instance, instance_id=instance_id_deadbeef_1 cluster_name=dx_cluster_name1 cluster_id=cluster_id1 cloud_unique_id=cloud_unique_id_compute_node2"
  4. }

drop_node

Description

This API is used to reduce nodes of the same type for a specific compute cluster under an instance.

Request

  • Syntax
  1. PUT /MetaService/http/drop_node?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string,
  6. "cluster": {
  7. "cluster_name": string,
  8. "cluster_id": string,
  9. "type": enum,
  10. "nodes": [
  11. {
  12. "cloud_unique_id": string,
  13. "ip": string,
  14. "heartbeat_port": int
  15. },
  16. {
  17. "cloud_unique_id": string,
  18. "ip": string,
  19. "heartbeat_port": int
  20. }
  21. ]
  22. }
  23. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idinstance_idRequired
clusterCluster objectRequired
cluster.cluster_nameName of the target clusterRequired
cluster.cluster_idID of the target clusterRequired
cluster.typeCluster node typeRequired
cluster.nodeNodes in the clusterRequiredArray
  • Example
  1. PUT /MetaService/http/drop_node?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": "instance_id_deadbeef_1",
  6. "cluster": {
  7. "cluster_name": "cluster_name1",
  8. "cluster_id": "cluster_id1",
  9. "type": "COMPUTE",
  10. "nodes": [
  11. {
  12. "cloud_unique_id": "1:instance_id_deadbeef_1:cloud_unique_id_compute_node2",
  13. "ip": "172.21.0.50",
  14. "heartbeat_port": 9051
  15. },
  16. {
  17. "cloud_unique_id": "1:instance_id_deadbeef_1:cloud_unique_id_compute_node3",
  18. "ip": "172.21.0.52",
  19. "heartbeat_port": 9052
  20. }
  21. ]
  22. }
  23. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INTERANAL_ERROR",
  3. "msg": "cloud_unique_id can not find to drop node, instance_id=instance_id_deadbeef_1 cluster_name=cluster_name1 cluster_id=cluster_id1 cloud_unique_id=cloud_unique_id_compute_node2"
  4. }

update_cluster_mysql_user_name

Description

This API is used to add a user to a specific compute cluster under an instance, allowing that user to log in to the system using a MySQL Client and access the default compute cluster.

Request

  • Syntax
  1. PUT /MetaService/http/update_cluster_mysql_user_name?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string,
  6. "cluster": {
  7. "cluster_name": "string",
  8. "cluster_id": "string",
  9. "mysql_user_name": [
  10. string
  11. ]
  12. }
  13. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idinstance_idRequired
clusterCluster objectRequired
cluster.cluster_nameName of the target clusterRequired
cluster.cluster_idID of the target clusterRequired
cluster.mysql_user_namemysql_user_nameRequiredString array
  • Example
  1. PUT /MetaService/http/update_cluster_mysql_user_name?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": "instance_id_deadbeef",
  6. "cluster": {
  7. "cluster_name": "cluster_name2",
  8. "cluster_id": "cluster_id1",
  9. "mysql_user_name": [
  10. "jack",
  11. "root"
  12. ]
  13. }
  14. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INTERANAL_ERROR",
  3. "msg": "no mysql user name to change"
  4. }

cloud_cluster_status

Description

This API is used to retrieve the status of Fragments running on BE nodes within the compute cluster.

Meta Service API - 图3tip

This API is a request to the FE.

Request

  • Syntax
  1. GET /rest/v2/manager/cluster/cluster_info/cloud_cluster_status HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  • Parameter
ParameterDescriptionRequired/OptionalNotes
userUsernameRequiredAuthentication information
passwordPasswordRequiredAuthentication information
  • Example
  1. curl -u root: http://127.0.0.1:12100/rest/v2/manager/cluster/cluster_info/cloud_cluster_status
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequired
msgError messageRequired
dataMap returned. The Key is Cluster ID and the Value is a BE list.
  • Successful response
  1. {
  2. "msg": "success",
  3. "code": 0,
  4. "data": {
  5. "regression_cluster_id2": [
  6. {
  7. "host": "127.0.0.1",
  8. "heartbeatPort": 14102,
  9. "bePort": -1,
  10. "httpPort": -1,
  11. "brpcPort": -1,
  12. "currentFragmentNum": 0,
  13. "lastFragmentUpdateTime": 0
  14. }
  15. ],
  16. "regression_test_cluster_id0": [
  17. {
  18. "host": "127.0.0.1",
  19. "heartbeatPort": 11102,
  20. "bePort": 11100,
  21. "httpPort": 11101,
  22. "brpcPort": 11103,
  23. "currentFragmentNum": 3,
  24. "lastFragmentUpdateTime": 1684152350291
  25. }
  26. ]
  27. },
  28. "count": 0
  29. }

enable_instance_sse

Description

This API is used to enable server-side encryption for the instance object data.

Request

  • Syntax
  1. PUT /MetaService/http/enable_instance_sse?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": string
  6. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idinstance_idRequiredGlobally unique
  • Example
  1. PUT /MetaService/http/enable_instance_sse?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_id": "123456"
  6. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequiredEnumerated values, including OK, INVALID_ARGUMENT, INTERNAL_ERROR, and ALREADY_EXISTED
msgError messageRequiredIf an error occurs, an error message will be returned; if no error occurs, an empty string will be returned.
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }
  • Example of unsuccessful response
  1. {
  2. "code": "INVALID_ARGUMENT",
  3. "msg": "failed to enable sse, instance has enabled sse"
  4. }

get_cluster_status

Description

This API is used to retrieve the runtime status of the compute clusters across multiple instances.

Request

  • Syntax
  1. PUT /MetaService/http/get_cluster_status?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "instance_ids": [string, string],
  6. "status": string
  7. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
instance_idsIDs of the instancesRequired
cloud_unique_idscloud_unique_idsOptionalinstance_ids is required while cloud_unique_ids is optional
statusFiltering conditionOptionalPossible status includes NORMAL, STOPPED, and TO_RESUME. If this parameter is not filled in, the systen will return the status of all clusters.
  • Example
  1. PUT /MetaService/http/get_cluster_status?token=greedisgood9999 HTTP/1.1
  2. Content-Length: 109
  3. Content-Type: text/plain
  4. {
  5. "instance_ids":["regression_instance-dx-1219", "regression_instance-dx-0128"],
  6. "status":"NORMAL"
  7. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequired
msgError messageRequired
result.detailsReturned status list of all compute clustersRequired
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": "",
  4. "result": {
  5. "details": [
  6. {
  7. "instance_id": "regression_instance-dx-1219",
  8. "clusters": [
  9. {
  10. "cluster_id": "regression_cluster_id2",
  11. "cluster_name": "regression_cluster_name2-changed-again",
  12. "cluster_status": "NORMAL"
  13. },
  14. {
  15. "cluster_id": "regression_cluster_id3",
  16. "cluster_name": "regression_cluster_name3",
  17. "cluster_status": "NORMAL"
  18. },
  19. {
  20. "cluster_id": "regression_test_cluster_id0",
  21. "cluster_name": "regression_test_cluster_name0",
  22. "cluster_status": "NORMAL"
  23. }
  24. ]
  25. }
  26. ]
  27. }
  28. }

set_cluster_status

Description

This API is used to set the runtime status of compute clusters.

Request

  • Syntax
  1. PUT /MetaService/http/set_cluster_status?token=<token> HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": string,
  6. "cluster": {
  7. "cluster_id": string,
  8. "cluster_status":string
  9. }
  10. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
cloud_unique_idOptional
instance_idRequired
cluster_idID of the target clusterRequired
cluster_statusStatus of the target clusterRequiredPossible status includes NORMAL, STOPPED, and TO_RESUME.
  • Example
  1. PUT /MetaService/http/set_cluster_status?token=greedisgood9999 HTTP/1.1
  2. Content-Length: 128
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": "1:regression_instance0:regression-cloud-unique-id-fe-0128",
  6. "cluster": {
  7. "cluster_id": "test_cluster_1_id1",
  8. "cluster_status":"STOPPED"
  9. }
  10. }
  • Returned parameter
ParameterDescriptionRequired/OptionalNotes
codeResponse status codeRequired
msgError messageRequired
  • Successful response
  1. {
  2. "code": "OK",
  3. "msg": ""
  4. }

Since this API is used by both the cloud management platform and the FE, certain rules needs to be followed. Only the following status transitions are allowed:

  • ClusterStatus::UNKNOWN -> ClusterStatus::NORMAL (When a compute cluster is created using the cloud management platform, the initial status of the cluster is directly set to NORMAL. This operation is usually completed via the add_cluster interface.)
  • ClusterStatus::NORMAL -> ClusterStatus::SUSPENDED (Set when the cloud management platform suspends the compute cluster)
  • ClusterStatus::SUSPENDED -> ClusterStatus::TO_RESUME (Set when the FE wakes up the compute cluster)
  • ClusterStatus::TO_RESUME -> ClusterStatus::NORMAL (Set when the cloud management platform resumes the status of the compute cluster)

Attempts to execute status transitions other than those listed above will incur errors.

  1. {
  2. "code": "INVALID_ARGUMENT",
  3. "msg": "failed to set cluster status, original cluster is NORMAL and want set TO_RESUME"
  4. }

decode_key

Description

This API is used to decode the Key from the Meta Service Log for debugging purposes.

Request

  • Syntax
  1. GET /MetaService/http/decode_key?token=greedisgood9999&key={key} HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  • Parameter
ParameterDescriptionRequired/OptionalNotes
keyKey to be decodedRequired
unicodeResponse formatOptional
  • Example
  1. GET /MetaService/http/decode_key?token=greedisgood9999&key=0110696e7374616e636500011072656772657373696f6e5f696e7374616e6365300001 HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  • Successful response
  1. ┌───────────────────────── 0. key space: 1
  2. ┌─────────────────────── 1. instance
  3. ┌─ 2. regression_instance0
  4. 0110696e7374616e636500011072656772657373696f6e5f696e7374616e6365300001

get_tablet_stats

Description

This API is used to query the status of a tablet for debugging purposes.

Request

  • Syntax
  1. POST /MetaService/http/get_tablet_stats?token=greedisgood9999 HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": string,
  6. "tablet_idx": [{
  7. "table_id": int64,
  8. "index_id": int64,
  9. "partition_id": int64,
  10. "tablet_id": int64
  11. }]
  12. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
cloud_unique_idcloud_unique_id of nodeRequired
tablet_idxTablet list to queryRequiredArray
tablet_idx.table_idtable_id of the tablet to queryRequired
tablet_idx.index_idindex_id of the tablet to queryRequired
tablet_idx.partition_idpartition_id of the tablet to queryRequired
tablet_idx.tablet_idtablet_id of the tablet to queryRequired
  • Example
  1. POST /MetaService/http/get_tablet_stats?token=greedisgood9999 HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id":"1:regression_instance0:regression-cloud-unique-id0",
  6. "tablet_idx": [{
  7. "table_id":113973,
  8. "index_id":113974,
  9. "partition_id":113966,
  10. "tablet_id":114739
  11. }]
  12. }
  • Successful response
  1. status {
  2. code: OK
  3. msg: ""
  4. }
  5. tablet_stats {
  6. idx {
  7. table_id: 113973
  8. index_id: 113974
  9. partition_id: 113966
  10. tablet_id: 114739
  11. }
  12. data_size: 0
  13. num_rows: 0
  14. num_rowsets: 2
  15. num_segments: 0
  16. base_compaction_cnt: 0
  17. cumulative_compaction_cnt: 0
  18. cumulative_point: 2
  19. }

abort_txn

Description

This API is used to abort a transaction during debugging.

Request

  • Syntax
  1. POST /MetaService/http/abort_txn?token=greedisgood9999 HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": string,
  6. "txn_id": int64
  7. }
  8. or
  9. {
  10. "cloud_unique_id": string,
  11. "db_id": int64,
  12. "label": string
  13. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
cloud_unique_idcloud_unique_id of nodeRequired
txn_idID of the transaction to abortOptional
db_iddb_id of the transaction to abortOptional
labelLabel of the transaction to abortOptional
  • Example
  1. POST /MetaService/http/abort_txn?token=greedisgood9999 HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": "1:regression_instance0:regression-cloud-unique-id0",
  6. "txn_id": 869414052004864
  7. }
  • Successful response
  1. status {
  2. code: OK
  3. msg: ""
  4. }

abort_tablet_job

Description

This API is used to abort a job running on a tablet. Currently, it only supports compaction jobs. It is used for debugging purposes.

Request

  • Syntax
  1. POST /MetaService/http/abort_tablet_job?token=greedisgood9999 HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": string,
  6. "job" : {
  7. "idx": {"tablet_id": int64},
  8. "compaction": [{"id": string}]
  9. }
  10. }
  • Parameter
ParameterDescriptionRequired/OptionalNotes
cloud_unique_idcloud_unique_id of nodeRequired
jobJob to abortRequiredCurrently only supports compaction jobs
job.idxIndex to abortRequired
job.idx.tablet_idThe corresponding tablet_id to abort.idx
job.compactionThe compaction to abortArray
job.compaction.idID of the compaction to abort
  • Example
  1. POST /MetaService/http/abort_tablet_job?token=greedisgood9999 HTTP/1.1
  2. Content-Length: <ContentLength>
  3. Content-Type: text/plain
  4. {
  5. "cloud_unique_id": "1:regression_instance0:regression-cloud-unique-id0",
  6. "job" : {
  7. "idx": {"tablet_id": 113973},
  8. "compaction": [{"id": 113974}]
  9. }
  10. }
  • Successful response
  1. status {
  2. code: OK
  3. msg: ""
  4. }