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"
}