Placement Driver API API documentation

/cluster/status

Cluster status.

/version

The version of PD server.

/status

The build info of PD server.

/diagnose

Diagnostic information of the cluster.

/members

The PD servers in the cluster.

/members get

get

List all PD servers in the cluster.

/members/name/{name} delete post

A specific PD server.

delete

Remove a PD server from the cluster.

post

Set leader priority of a PD member.

/leader

The leader PD server of the cluster.

/health

Health status of PD servers.

/config

PD cluster configuration.

/config/schedule get post

Schedule configuration.

get

Get schedule config.

post

Update a schedule config item.

/config/replicate get post

Replication configuration.

get

Get replication config.

post

Update a replication config item.

/config/namespace/{namespaceName} get post delete

The config of a namespace.

get

Get configuration of a namespace.

post

Update a namespace config item.

delete

Delete a namespace config.

/config/label-property get post

The label property configuration.

get

Get label property config.

post

Update label property config item.

/stores

The stores in the cluster.

/stores get

get

Get stores in the cluster.

Request
Response

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)

HTTP status code 500

PD server failed to proceed the request.

/store/{storeId}

A specific store.

/store/{storeId} get delete

get

Get a store's information.

delete

Take down a store from the cluster.

Get a store's information.

Request
Response

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.

/labels

The store label values in the cluster.

/labels/stores get

get

List stores that have specific label values.

Request
Response

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.

/region/id/{id} get

get

Search for a region by region ID.

Request
Response

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)
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.

/region/key/{key} get

get

Search for a region by a key.

Request
Response

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)
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.

/regions get

get

List all regions in the cluster.

Response

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)
- 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/writeflow get

get

List regions with the highest write flow.

Request
Response

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)
- 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.

/regions/readflow get

get

List regions with the highest read flow.

Request
Response

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)
- 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.

/regions/confver get

get

List regions with the largest conf version.

Request
Response

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)
- 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.

/regions/version get

get

List regions with the largest version.

Request
Response

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)
- 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.

/regions/size get

get

List regions with the largest size.

Request
Response

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)
- 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.

/regions/key get

get

List regions start from a key.

Request
Response

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)
- 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.

/regions/check/{filter} get

get

List regions with unhealthy status.

Request
Response

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)
- 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/sibling/{id} get

get

List sibling regions of a specific region.

Request
Response

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)
- 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.

/regions/store/{id} get

get

List all regions of a specific store.

Request
Response

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)
- 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.

/schedulers get post

get

List running schedulers.

post

Create a scheduler.

/operators

Pending operators.

/operators get post

get

List pending operators.

post

Create an operator.

/operators/{regionId} get delete

A specific Region's pending operator.

get

Get a Region's pending operator.

delete

Cancel a Region's pending operator.

/hotspot

The hot spots status in the cluster.

/stats

Statistics of the cluster.

/stats/region get

get

Get region statistics of a specified range.

/trend

Trend of data growth and movements.

/trend get

get

Get the growth and changes of data in the most recent period of time.

Request
Response

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

/classifier

The namespace classifier. Methods depend on current classifier.

Placement Driver API API documentation version v1

/cluster/status

get /cluster/status

HTTP status code 200

Body

HTTP status code 500

/version

get /version

HTTP status code 200

Body

/status

get /status

HTTP status code 200

Body

/diagnose

get /diagnose

HTTP status code 200

Body

HTTP status code 500

/members

get /members

HTTP status code 200

Body

HTTP status code 500

delete /members/name/{name}

URI Parameters

HTTP status code 200

HTTP status code 400

HTTP status code 404

HTTP status code 500

post /members/name/{name}

URI Parameters

Body

HTTP status code 200

HTTP status code 400

HTTP status code 404

HTTP status code 500

delete /members/id/{id}

URI Parameters

HTTP status code 200

HTTP status code 400

HTTP status code 500

/leader

get /leader

HTTP status code 200

Body

HTTP status code 500

post /leader/resign

HTTP status code 200

HTTP status code 500

post /leader/transfer/{nextLeader}

URI Parameters

HTTP status code 200

HTTP status code 500

/health

get /health

HTTP status code 200

Body

HTTP status code 500

/config

get /config

HTTP status code 200

Body

post /config

Body

HTTP status code 200

HTTP status code 500

get /config/schedule

HTTP status code 200

Body

post /config/schedule

Body

HTTP status code 200

HTTP status code 400

HTTP status code 500

get /config/replicate

HTTP status code 200

Body

post /config/replicate

Body