Placement Driver API API documentation version v1
http://{pdAddr}/pd/api/{version}
- pdAddr: required (string)
The PD server address, formatted as 'host:port'.
- version: required (v1)
/cluster/status
Cluster status.
Get cluster status.
/version
/status
/diagnose
Diagnostic information of the cluster.
/members
The PD servers in the cluster.
List all PD servers in the cluster.
get /members
List all PD servers in the cluster.
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- members: (array of Member)
Items: Member
- name: (string)
- member_id: (integer)
- peer_urls: (array of string)
- client_urls: (array of string)
- leader_priority: (integer)
- leader: (object)
- name: (string)
- member_id: (integer)
- peer_urls: (array of string)
- client_urls: (array of string)
- leader_priority: (integer)
- etcd_leader: (object)
- name: (string)
- member_id: (integer)
- peer_urls: (array of string)
- client_urls: (array of string)
- leader_priority: (integer)
HTTP status code 500
PD server failed to proceed the request.
A specific PD server.
Remove a PD server from the cluster.
Set leader priority of a PD member.
delete /members/name/{name}
post /members/name/{name}
Set leader priority of a PD member.
URI Parameters
- name: required (string)
Body
Media type: application/json
Type: object
Properties- leader-priority: required (integer)
A specific PD server.
Remove a PD server from the cluster.
/leader
The leader PD server of the cluster.
Get the leader PD server of the cluster.
get /leader
Get the leader PD server of the cluster.
Transfer leadership to another PD server.
Transfer leadership to the specific PD server.
/health
Health status of PD servers.
/config
PD cluster configuration.
Get full config.
Update a config item.
Schedule configuration.
Get schedule config.
Update a schedule config item.
get /config/schedule
Get schedule config.
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- max-snapshot-count: (integer)
- max-pending-peer-count: (integer)
- max-merge-region-size: (integer)
- max-merge-region-keys: (integer)
- split-merge-interval: (string)
- enable-one-way-merge: (boolean)
- patrol-region-interval: (string)
- max-store-down-time: (string)
- leader-schedule-limit: (integer)
- region-schedule-limit: (integer)
- replica-schedule-limit: (integer)
- merge-schedule-limit: (integer)
- hot-region-schedule-limit: (integer)
- hot-region-cache-hits-threshold: (integer)
- store-balance-rate: (number)
- tolerant-size-ratio: (number)
- low-space-ratio: (number)
- high-space-ratio: (number)
- scheduler-max-waiting-operator: (integer)
- disable-raft-learner: (boolean)
- disable-remove-down-replica: (boolean)
- disable-replace-offline-replica: (boolean)
- disable-make-up-replica: (boolean)
- disable-remove-extra-replica: (boolean)
- disable-location-replacement: (boolean)
- schedulers-v2: (object)
Replication configuration.
Get replication config.
Update a replication config item.
The config of a namespace.
Get configuration of a namespace.
Update a namespace config item.
Delete a namespace config.
get /config/namespace/{namespaceName}
Get configuration of a namespace.
URI Parameters
- namespaceName: required (string)
The name of the namespace.
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- leader-schedule-limit: required (integer)
- region-schedule-limit: required (integer)
- replica-schedule-limit: required (integer)
- merge-schedule-limit: required (integer)
- max-replicas: required (integer)
HTTP status code 404
The namespace does not exist.
post /config/namespace/{namespaceName}
The label property configuration.
Get label property config.
Update label property config item.
post /config/label-property
Update label property config item.
/stores
The stores in the cluster.
Get stores in the cluster.
get /stores
Get stores in the cluster.
Query Parameters
- state: (array of )
Specify accepted store states.
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- stores: required (array of Store)
Items: Store
- store: required (object)
- id: required (integer)
- address: required (string)
- state: required (one of 0, 1, 2)
- state_name: required (one of Up, Disconnected, Down, Offline, Tombstone)
- labels: (array of StoreLabel)
Items: StoreLabel
- key: required (string)
- value: required (string)
- version: (string)
- status: required (object)
- capacity: required (string)
- available: required (string)
- leader_count: (integer)
- leader_weight: (number)
- leader_score: (number)
- leader_size: (integer)
- region_count: (integer)
- region_weight: (number)
- region_score: (number)
- region_size: (integer)
- sending_snap_count: (integer)
- receiving_snap_count: (integer)
- applying_snap_count: (integer)
- is_busy: (boolean)
- start_ts: (string)
- last_heartbeat_ts: (string)
- uptime: (string)
- store: required (object)
HTTP status code 500
PD server failed to proceed the request.
The balance rate limit for all stores.
Get all stores' balance rate limit.
Set all stores' balance rate limit.
Remove all tombstone stores.
Remove all tombstone stores.
/store/{storeId}
A specific store.
Get a store's information.
Take down a store from the cluster.
get /store/{storeId}
Get a store's information.
URI Parameters
- storeId: required (integer)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- store: required (object)
- id: required (integer)
- address: required (string)
- state: required (one of 0, 1, 2)
- state_name: required (one of Up, Disconnected, Down, Offline, Tombstone)
- labels: (array of StoreLabel)
Items: StoreLabel
- key: required (string)
- value: required (string)
- version: (string)
- status: required (object)
- capacity: required (string)
- available: required (string)
- leader_count: (integer)
- leader_weight: (number)
- leader_score: (number)
- leader_size: (integer)
- region_count: (integer)
- region_weight: (number)
- region_score: (number)
- region_size: (integer)
- sending_snap_count: (integer)
- receiving_snap_count: (integer)
- applying_snap_count: (integer)
- is_busy: (boolean)
- start_ts: (string)
- last_heartbeat_ts: (string)
- uptime: (string)
HTTP status code 400
The input is invalid.
HTTP status code 500
PD server failed to proceed the request.
delete /store/{storeId}
Take down a store from the cluster.
URI Parameters
- storeId: required (integer)
Query Parameters
- force: (string)
Set status to Tombstone directly.
The state for the specific store.
Set the store's state.
post /store/{storeId}/state
Set the store's state.
The label for the specific store.
Set the store's label.
The weight for the specific store.
Set the store's leader/region weight.
post /store/{storeId}/weight
The balance rate limit for the specific store.
Set the store's balance rate limit.
post /store/{storeId}/limit
/labels
The store label values in the cluster.
List all label values.
List stores that have specific label values.
get /labels/stores
List stores that have specific label values.
Query Parameters
- name: required (string)
- value: required (string)
HTTP status code 200
Body
Media type: application/json
Type: array of object
Items: Store
- store: required (object)
- id: required (integer)
- address: required (string)
- state: required (one of 0, 1, 2)
- state_name: required (one of Up, Disconnected, Down, Offline, Tombstone)
- labels: (array of StoreLabel)
Items: StoreLabel
- key: required (string)
- value: required (string)
- version: (string)
- status: required (object)
- capacity: required (string)
- available: required (string)
- leader_count: (integer)
- leader_weight: (number)
- leader_score: (number)
- leader_size: (integer)
- region_count: (integer)
- region_weight: (number)
- region_score: (number)
- region_size: (integer)
- sending_snap_count: (integer)
- receiving_snap_count: (integer)
- applying_snap_count: (integer)
- is_busy: (boolean)
- start_ts: (string)
- last_heartbeat_ts: (string)
- uptime: (string)
HTTP status code 500
PD server failed to proceed the request.
/region
A specific region in the cluster.
Search for a region by region ID.
get /region/id/{id}
Search for a region by region ID.
URI Parameters
- id: required (integer)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 400
The input is invalid.
HTTP status code 500
PD server failed to proceed the request.
Search for a region by a key.
get /region/key/{key}
Search for a region by a key.
URI Parameters
- key: required (string)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 500
PD server failed to proceed the request.
/regions
The regions in the cluster.
List all regions in the cluster.
get /regions
List all regions in the cluster.
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- regions: required (array of Region)
Items: Region
- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 500
PD server failed to proceed the request.
List regions with the highest write flow.
get /regions/writeflow
List regions with the highest write flow.
Query Parameters
- limit: (integer - default: 16)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- regions: required (array of Region)
Items: Region
- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 400
The input is invalid.
HTTP status code 500
PD server failed to proceed the request.
List regions with the highest read flow.
get /regions/readflow
List regions with the highest read flow.
Query Parameters
- limit: (integer - default: 16)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- regions: required (array of Region)
Items: Region
- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 400
The input is invalid.
HTTP status code 500
PD server failed to proceed the request.
List regions with the largest conf version.
get /regions/confver
List regions with the largest conf version.
Query Parameters
- limit: (integer - default: 16)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- regions: required (array of Region)
Items: Region
- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 400
The input is invalid.
HTTP status code 500
PD server failed to proceed the request.
List regions with the largest version.
get /regions/version
List regions with the largest version.
Query Parameters
- limit: (integer - default: 16)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- regions: required (array of Region)
Items: Region
- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 400
The input is invalid.
HTTP status code 500
PD server failed to proceed the request.
List regions with the largest size.
get /regions/size
List regions with the largest size.
Query Parameters
- limit: (integer - default: 16)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- regions: required (array of Region)
Items: Region
- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 400
The input is invalid.
HTTP status code 500
PD server failed to proceed the request.
List regions start from a key.
get /regions/key
List regions start from a key.
Query Parameters
- key: required (string)
- limit: (integer - default: 16)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- regions: required (array of Region)
Items: Region
- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 400
The input is invalid.
HTTP status code 500
PD server failed to proceed the request.
List regions with unhealthy status.
get /regions/check/{filter}
List regions with unhealthy status.
URI Parameters
- filter: required (one of miss-peer, extra-peer, pending-peer, down-peer, incorrect-ns)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- regions: required (array of Region)
Items: Region
- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 500
PD server failed to proceed the request.
List sibling regions of a specific region.
get /regions/sibling/{id}
List sibling regions of a specific region.
URI Parameters
- id: required (integer)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- regions: required (array of Region)
Items: Region
- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 400
The input is invalid.
HTTP status code 404
The region does not exist.
HTTP status code 500
PD server failed to proceed the request.
List all regions of a specific store.
get /regions/store/{id}
List all regions of a specific store.
URI Parameters
- id: required (integer)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- regions: required (array of Region)
Items: Region
- id: required (integer)
- start_key: required (string)
- end_key: required (string)
- epoch: (object)
- conf_ver: (integer)
- version: (integer)
- peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- leader: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_peers: (array of PeerStats)
Items: PeerStats
- peer: (object)
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- down_seconds: required (integer)
- peer: (object)
- pending_peers: (array of Peer)
Items: Peer
- id: required (integer)
- store_id: required (integer)
- is_learner: (boolean)
- written_bytes: (integer)
- read_bytes: (integer)
- approximate_size: (integer)
- approximate_keys: (integer)
HTTP status code 400
The input is invalid.
HTTP status code 500
PD server failed to proceed the request.
/schedulers
Running schedulers.
List running schedulers.
Create a scheduler.
/operators
Pending operators.
List pending operators.
Create an operator.
A specific Region's pending operator.
Get a Region's pending operator.
Cancel a Region's pending operator.
/hotspot
The hot spots status in the cluster.
List the hot write regions.
List the hot read regions.
List the hot stores.
/stats
Statistics of the cluster.
Get region statistics of a specified range.
get /stats/region
Get region statistics of a specified range.
Query Parameters
- start_key: (string)
- end_key: (string)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- count: required (integer)
- empty_count: required (integer)
- storage_size: required (integer)
- storage_keys: required (integer)
- store_leader_count: required (object)
- store_peer_count: required (object)
- store_leader_size: required (object)
- store_leader_keys: required (object)
- store_peer_size: required (object)
- store_peer_keys: required (object)
HTTP status code 500
PD server failed to proceed the request.
/trend
Trend of data growth and movements.
Get the growth and changes of data in the most recent period of time.
get /trend
Get the growth and changes of data in the most recent period of time.
Query Parameters
- from: required (integer)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- stores: required (array of TrendStore)
Items: TrendStore
- id: required (integer)
- address: required (string)
- state_name: required (string)
- capacity: required (integer)
- available: required (integer)
- region_count: required (integer)
- leader_count: required (integer)
- start_ts: (string)
- last_heartbeat_ts: (string)
- uptime: (string)
- hot_write_flow: required (integer)
- hot_write_region_flows: required (array of integer)
- hot_read_flow: required (integer)
- hot_read_region_flows: required (array of integer)
- history: required (object)
- start: required (integer)
- end: required (integer)
- entries: required (array of TrendHistoryEntry)
Items: TrendHistoryEntry
- from: required (integer)
- to: required (integer)
- kind: required (one of leader, region)
- count: required (integer)
HTTP status code 400
The request is invalid.
HTTP status code 500
PD server failed to proceed the request.
/admin
Drop a specific region from cache.
/classifier
The namespace classifier. Methods depend on current classifier.