Placement — MDDB API

(v2.19.8) Collections placed across node groups, and moves between them

Collection placement across node groups (admin) #

GET /v1/placement

(v2.19.8, GO-052) The node groups and their leaders, every collection the placement map names, and the recent moves. Answered by the meta group's leader whichever node receives it. Without MDDB_PLACEMENT_GROUPS the answer is {"enabled": false}. See CLUSTER.

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status Description Body
200 The placement PlacementStatus (application/json)
401 Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. ErrorResponse (application/json)
403 The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). ErrorResponse (application/json)
421 (v2.19.8, GO-051) This cluster node does not lead; send the write to the leader named in the X-MDDB-Leader header and in leaderAddr. Every write endpoint answers so on a node that does not lead; while an election runs it answers 503 with Retry-After instead. See CLUSTER.md. (v2.19.8, GO-052) With collection placement and MDDB_PLACEMENT_ROUTE=redirect, any request for a collection held by another node group (and a write to a global setting or a /v1/placement request on a node outside the meta group's leader) is answered so too: X-MDDB-Leader is that group's leader, X-MDDB-Group the group, and the body carries group instead of term. object (application/json)
503 Not now: the search concurrency limit is reached, the subsystem is disabled, or a write meets the database while its freelist is rebuilt (#333; the body then adds phase and progress). Retry after Retry-After seconds. ErrorResponse (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

Move a collection to another node group (admin) #

POST /v1/placement/move

(v2.19.8, GO-052) Copies the collection to the target group while it keeps serving reads and writes, holds its writes briefly while the map switches, then the old group drops its copy after MDDB_PLACEMENT_DROP_GRACE. No acknowledged write is lost. Run by the meta group's leader. Without wait the answer is 202 at once; poll GET /v1/placement. See CLUSTER.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name In Type Description
wait query boolean true: answer when the move ends (200 done, 409 failed) Default false.

Request body #

Required.

Content type application/json: PlacementMoveRequest

{
  "collection": "articles",
  "group": "g2"
}

Responses #

Status Description Body
200 With wait=true: the move is done object (application/json)
202 The move started object (application/json)
400 collection or group missing, an unknown group, or placement not configured ErrorResponse (application/json)
401 Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. ErrorResponse (application/json)
403 The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). ErrorResponse (application/json)
409 The collection is already in that group, a move of it is running, or (wait=true) the move failed — then move carries its state and error object (application/json)
421 (v2.19.8, GO-051) This cluster node does not lead; send the write to the leader named in the X-MDDB-Leader header and in leaderAddr. Every write endpoint answers so on a node that does not lead; while an election runs it answers 503 with Retry-After instead. See CLUSTER.md. (v2.19.8, GO-052) With collection placement and MDDB_PLACEMENT_ROUTE=redirect, any request for a collection held by another node group (and a write to a global setting or a /v1/placement request on a node outside the meta group's leader) is answered so too: X-MDDB-Leader is that group's leader, X-MDDB-Group the group, and the body carries group instead of term. object (application/json)
503 Not now: the search concurrency limit is reached, the subsystem is disabled, or a write meets the database while its freelist is rebuilt (#333; the body then adds phase and progress). Retry after Retry-After seconds. ErrorResponse (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}