You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by va...@apache.org on 2019/04/02 15:57:45 UTC
[couchdb-documentation] 01/01: Add _reshard HTTP API reference
documentation
This is an automated email from the ASF dual-hosted git repository.
vatamane pushed a commit to branch reshard-docs
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
commit 531e2d638b11d1cb27774c313d3f13fd39335653
Author: Nick Vatamaniuc <va...@apache.org>
AuthorDate: Tue Apr 2 11:56:41 2019 -0400
Add _reshard HTTP API reference documentation
Related to the main PR: https://github.com/apache/couchdb/pull/1972
---
src/api/server/common.rst | 485 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 485 insertions(+)
diff --git a/src/api/server/common.rst b/src/api/server/common.rst
index 752c522..1cdc787 100644
--- a/src/api/server/common.rst
+++ b/src/api/server/common.rst
@@ -1675,3 +1675,488 @@ You can verify the change by obtaining a list of UUIDs:
:>header Content-Type: :mimetype:`image/x-icon`
:code 200: Request completed successfully
:code 404: The requested content could not be found
+
+.. _api/server/_reshard:
+
+=============
+``/_reshard``
+=============
+
+.. versionadded:: 2.4
+
+.. http:get:: /_reshard
+ :synopsis: Retrieve summary information about resharding on the cluster
+
+ Returns a count of completed, failed, running, stopped, and total jobs
+ along with the state of resharding on the cluster.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :>json string state: ``stopped`` or ``running``
+ :>json string state_reason: ``null`` or string describing additional
+ information or reason associated with the state
+ :>json number completed: Count of completed resharding jobs
+ :>json number failed: Count of failed resharding jobs
+ :>json number running: Count of running resharding jobs
+ :>json number stopped: Count of stopped resharding jobs
+ :>json number total: Total count of resharding jobs
+
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /_reshard HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "completed": 21,
+ "failed": 0,
+ "running": 3,
+ "state": "running",
+ "state_reason": null,
+ "stopped": 0,
+ "total": 24
+ }
+
+.. http:get:: /_reshard/state
+ :synopsis: Retrieve the state of resharding on the cluster
+
+ Returns the resharding state and optional information about the state.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :>json string state: ``stopped`` or ``running``
+ :>json string state_reason: Additional information or reason associated
+ with the state
+
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /_reshard/state HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "reason": null,
+ "state": "running"
+ }
+
+.. http:put:: /_reshard/state
+ :synopsis: Change resharding state on the cluster
+
+ Change the resharding state on the cluster. The states are
+ ``stopped`` or ``running``. This starts and stops global resharding on all
+ the nodes of the cluster. If there are any running jobs, they
+ will be stopped when the state changes to ``stopped``. When the state
+ changes back to ``running`` those job will continue running.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :<json string state: ``stopped`` or ``running``
+ :<json string state_reason: Optional string describing additional
+ information or reason associated with the state
+
+ :>json boolean ok: ``true``
+
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /_reshard/state HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ {
+ "state": "stopped",
+ "reason": "Rebalancing in progress"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "ok": true
+ }
+
+.. http:get:: /_reshard/jobs
+ :synopsis: Retrieve information about all the resharding jobs on the cluster
+
+ Get information about the resharding job identified by ``jobid``.
+
+ .. note:: The shape of the response and the ``total_rows`` and ``offset``
+ field in particular are meant to be consistent with the
+ ``_scheduler/jobs`` endpoint.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :>json list jobs: Array of json objects, one for each resharding job. For
+ the fields of each job see the /_reshard/job/{jobid}
+ endpoint.
+ :>json number offset: Offset in the list of jobs object. Currently
+ hard-coded at ``0``.
+ :>json number total_rows: Total number of resharding jobs on the cluster.
+
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /_reshard/jobs HTTP/1.1
+ Accept: application/json
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "jobs": [
+ {
+ "history": [
+ {
+ "detail": null,
+ "timestamp": "2019-03-28T15:28:02Z",
+ "type": "new"
+ },
+ {
+ "detail": "initial_copy",
+ "timestamp": "2019-03-28T15:28:02Z",
+ "type": "running"
+ },
+ ...
+ ],
+ "id": "001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a",
+ "job_state": "completed",
+ "node": "node1@127.0.0.1",
+ "source": "shards/00000000-1fffffff/d1.1553786862",
+ "split_state": "completed",
+ "start_time": "2019-03-28T15:28:02Z",
+ "state_info": {},
+ "target": [
+ "shards/00000000-0fffffff/d1.1553786862",
+ "shards/10000000-1fffffff/d1.1553786862"
+ ],
+ "type": "split",
+ "update_time": "2019-03-28T15:28:08Z"
+ },
+ ...
+ ],
+ "offset": 0,
+ "total_rows": 24
+ }
+
+.. http:get:: /_reshard/jobs/{jobid}
+ :synopsis: Retrieve information about a particular resharding job
+
+ Get information about the resharding job identified by ``jobid``.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :>json string id: Job ID.
+ :>json string type: Currently only ``split`` is implemented.
+ :>json string job_state: The running state of the job. Could be one of
+ ``new``, ``running``, ``stopped``, ``completed``
+ or ``failed``.
+ :>json string split_state: The state of shard splitting. The state specific
+ to ``split`` jobs and indicate how far the shard
+ splitting has progressed. This can be one of
+ ``new``, ``initial_copy``, ``topoff1``,
+ ``build_indices``, ``topoff2``,
+ ``copy_local_docs``, ``update_shardmap``,
+ ``wait_source_close``, ``topoff3``,
+ ``source_delete`` or ``completed``. The
+ progression will be linearly through those
+ states from ``new`` to ``completed``.
+ :>json object state_info: Optional additional info associated with the current state.
+ :>json string source: For ``split`` jobs this will be the source shard.
+ :>json list target: For ``split`` jobs this will be a list of two or more
+ target shards.
+ :>json string start_time: A timestamp when this job had started running.
+ :>json string update_time: A timestamp indicated when this job was last updated.
+ :>json list history: List of json object recording a job's state transition.
+
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1
+ Accept: application/json
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+
+ "id": "001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a",
+ "job_state": "completed",
+ "node": "node1@127.0.0.1",
+ "source": "shards/00000000-1fffffff/d1.1553786862",
+ "split_state": "completed",
+ "start_time": "2019-03-28T15:28:02Z",
+ "state_info": {},
+ "target": [
+ "shards/00000000-0fffffff/d1.1553786862",
+ "shards/10000000-1fffffff/d1.1553786862"
+ ],
+ "type": "split",
+ "update_time": "2019-03-28T15:28:08Z",
+ "history": [
+ {
+ "detail": null,
+ "timestamp": "2019-03-28T15:28:02Z",
+ "type": "new"
+ },
+ {
+ "detail": "initial_copy",
+ "timestamp": "2019-03-28T15:28:02Z",
+ "type": "running"
+ },
+ ...
+ ]
+ }
+
+.. http:post:: /_reshard/jobs/{jobid}
+ :synopsis: Create one or more resharding jobs
+
+ Create one or more resharding jobs. Depending what fields are specified in
+ the request, one or more resharding jobs will be created. The response is
+ a json array of results. Each result object represents a single resharding
+ job on a particular node, in a particular range. Some of the responses
+ could be successful and some could fail. Successful results will have the
+ ``"ok": true`` and an ``"id": {jobid}`` fields and values. A failed job
+ result object will have an ``"error": "{error_message}"`` field and value.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :<json string type: Type of job. Currently only ``"split"`` is accepted. As
+ only shard splitting is implemented.
+
+ :<json string db: Database to split. This is the database name at the
+ cluster level, not the shard name. This is mutually
+ exclusive with the ``"shard``" field.
+ :<json string node: Only split shards located on this node. This is an
+ optional parameter. The value should be one of the
+ nodes returned from the ``_membership`` endpoint
+ response.
+ :<json string range: Only split shards copies in the given range. The
+ range format is ``hhhhhhhh-hhhhhhhh`` where ``h`` is a
+ hexadecimal digit. This format is used since this is how the
+ ranges are represented in the file system. This is
+ parameter is optional and is mutually exclusive
+ with the ``"shard"`` field.
+ :<json string shard: Split a particular shard. The shard should be
+ specified as ``"shards/{range}/{db}.{suffix}"``. Where
+ ``range`` has the ``hhhhhhhh-hhhhhhhh`` format, ``db``
+ is the database name, and ``suffix`` is the shard
+ (timestamp) suffix.
+
+ :>json boolean ok: ``true`` if job created successfully. Indicates a job
+ was created successfully Mutually exclusive with
+ ``error`` field.
+
+ :<json string error: Error message if a job could be not be created.
+ Mutually exclusive with ``"ok"`` field.
+
+ :<json string shard: The source shard if the job is of type ``split``.
+
+ :<json string node: Cluster node where the job was created and is running.
+
+ :code 201: One or more jobs were successfully created
+ :code 404: Db, node, range or shard was not found
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /_reshard/jobs HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+
+ {
+ "db": "db3",
+ "range": "80000000-ffffffff",
+ "type": "split"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Content-Type: application/json
+
+ [
+ {
+ "id": "001-30d7848a6feeb826d5e3ea5bb7773d672af226fd34fd84a8fb1ca736285df557",
+ "node": "node1@127.0.0.1",
+ "ok": true,
+ "shard": "shards/80000000-ffffffff/db3.1554148353"
+ },
+ {
+ "id": "001-c2d734360b4cb3ff8b3feaccb2d787bf81ce2e773489eddd985ddd01d9de8e01",
+ "node": "node2@127.0.0.1",
+ "ok": true,
+ "shard": "shards/80000000-ffffffff/db3.1554148353"
+ }
+ ]
+
+.. http:delete:: /_reshard/jobs/{jobid}
+ :synopsis: Remove a shard splitting job
+
+ If the job is running, stop the job and then remove it.
+
+ :>json boolean ok: ``true`` if job was removed successfully.
+
+ :code 200: The job was removed successfully
+ :code 404: The job was not found
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ DELETE /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "ok": true
+ }
+
+.. http:get:: /_reshard/jobs/{jobid}/state
+ :synopsis: Retrieve the state of a single resharding job
+
+ Returns the running state of a resharding job identified by ``jobid``.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :<json string state: One of ``new``, ``running``, ``stopped``,
+ ``completed`` or ``failed``.`stopped``,
+ ``running``
+ :<json string state_reason: Additional information associated with the
+ state
+
+ :code 200: Request completed successfully
+ :code 404: The job was not found
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /_reshard/jobs/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "reason": null,
+ "state": "running"
+ }
+
+.. http:put:: /_reshard/jobs/{jobid}/state
+ :synopsis: Change the state of a resharding job
+
+ Change the state of a particular resharding job identified by ``jobid``.
+ The state can be changed from ``stopped`` to ``running`` or from
+ ``running`` to ``stopped``. If an individual job is ``stopped`` via this
+ API it will stay ``stopped`` even after the global resharding state is
+ toggled from ``stopped`` to ``running``. If the job is already
+ ``completed`` its state will stay ``completed`` and will not be restarted
+ by this API endpoint.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :<json string state: ``stopped`` or ``running``
+ :<json string state_reason: Optional string describing additional
+ information or reason associated with the state
+
+ :>json boolean ok: ``true``
+
+ :code 200: Request completed successfully
+ :code 404: The job was not found
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /_reshard/state/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ {
+ "state": "stopped",
+ "reason": "Rebalancing in progress"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "ok": true
+ }