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)
- 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)
- tolerant-size-ratio: (number)
- low-space-ratio: (number)
- high-space-ratio: (number)
- 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.
/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 specific store's state.
Set the store's state.
post /store/{storeId}/state
Set the store's state.
The specific store's label.
Set the store's label.
The specific store's weight.
Set the store's leader/region weight.
post /store/{storeId}/weight
/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 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.
/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/cache/region/{id}
Drop a specific region from cache.
/log
/classifier
The namespace classifier. Methods depend on current classifier.