diff --git a/modules/introduction/partials/new-features-76.adoc b/modules/introduction/partials/new-features-76.adoc index 5ab3834df0..a8c89d22b7 100644 --- a/modules/introduction/partials/new-features-76.adoc +++ b/modules/introduction/partials/new-features-76.adoc @@ -45,6 +45,10 @@ See xref:rest-api:rest-auditing.adoc[Configure Auditing]. * You can add one or more arbiter nodes to a cluster. include::learn:partial$arbiter-node-benefits.adoc[] +* The `sampleBuckets/install` REST API method now returns a JSON object containing the list of tasks Couchbase Server started to load the buckets. +In addition, the `/pools/default/tasks` REST API endpoint now takes an optional `taskId` parameter to view details about a sample bucket loading task. +See xref:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-rest-api[Install Sample Buckets with the REST API] for more information. + === Backup and Restore * The Role-Based Access Control (RBAC) REST API has a new `backup` endpoint that lets you backup and restore user and user groups. See xref:rest-api:rbac.adoc#backup-and-restore-users-and-groups[Backup and Restore Users and Groups]. diff --git a/modules/manage/pages/manage-settings/install-sample-buckets.adoc b/modules/manage/pages/manage-settings/install-sample-buckets.adoc index df5fc4cd3d..4282e4d798 100644 --- a/modules/manage/pages/manage-settings/install-sample-buckets.adoc +++ b/modules/manage/pages/manage-settings/install-sample-buckets.adoc @@ -1,5 +1,5 @@ = Sample Buckets -:description: Sample buckets contain scopes, collections, and documents that are ready to be experimented with. +:description: You can install buckets containing example scopes, collections, and documents that you can experiment with. :page-aliases: settings:install-sample-buckets [abstract] @@ -8,45 +8,20 @@ [#configuring-sample-buckets] == Sample Buckets -Sample buckets contain data for experimental use. -Sample buckets are referred to in code and command-line examples throughout Couchbase-Server documentation. - -Full and Cluster administrators can install sample buckets with xref:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-ui[Couchbase Web Console] and the xref:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-rest-api[REST API]. +Full and Cluster administrators can install sample buckets using the xref:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-ui[Couchbase Server Web Console] and the xref:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-rest-api[REST API]. [#scopes-collection-and-sample-buckets] === Scopes, Collections, and Sample Buckets -Couchbase Server Version 7.0 introduces xref:learn:data/scopes-and-collections.adoc[Scopes and Collections], which allow data within a bucket to be organized according to type. -Buckets created and used on previous versions of the server, after upgrade to 7.x, initially have all their data within the _default_ collection, which is itself within the _default_ scope. -From this point, data can be selectively migrated from the default collection into other, administrator-defined collections. - -Each sample bucket provided with 7.x contains its data _either_: - -* Entirely within the default scope and collection. -These buckets are `beer-sample` and `gamesim-sample`. - -* Within multiple scopes and collections that have been pre-defined to exist in addition to the default scope and collection; _and_ within the default scope and collection also. -This is the configuration provided for the `travel-sample` bucket. -In total, _seven_ scopes exist within this bucket: - -** `_default`. -This contains the `_default` collection; within which all documents reside. -The `_default` collection therefore itself contains all documents that existed in pre-7.0 versions of the `travel-sample` bucket. - -** `inventory`. -This also contains all documents that existed in pre-7.0 versions of the `travel-sample` buckets, but in a different configuration: here, the documents are distributed, according to type, across five collections; which are named `airline`, `airport`, `landmark`, `hotel`, and `route`. +xref:learn:data/scopes-and-collections.adoc[Scopes and Collections] let you organize data within a bucket by type. +The `beer-sample` and `gamesim-sample` sample buckets store all of their data in the default scope. +The `travel-sample` bucket contains data in six scopes in addition to the `_default` scope. +These additional scopes define several collections. +The `inventory` scope has collections that organize travel data such as airlines and airports. +The data within the `tenant_agent_00` through `tenant_agent_04` scopes let you experiment with multi-tenancy applications. -** `tenant_agent_00` to `tenant_agent_04`. -Each of these five scopes contains two collections; which are named `users` and `bookings`. - -Since all three sample buckets contain, in their default collection, all data they held in pre-7.0 versions of Couchbase Server, programs written to access this data in its original locations will be able to continue doing so with minimal adjustment. -All three buckets can also be used for experiments with _migration_, whereby the data is selectively redistributed into administrator-created collections. -See xref:manage:manage-xdcr/replicate-using-scopes-and-collections.adoc#migrate-data-to-a-collection-with-the-ui[Migrate Data to a Collection with the UI]. - -The `travel-sample` bucket contains travel-related data already in migrated form, within the collections in the scope `inventory`. -The bucket can thus be used for immediate experimentation with application-access to scopes and collections. - -The `travel-sample` bucket also contains data within the `tenant_agent` scopes, which is appropriate for experimentation with _multi-tenancy-based_ application access. +NOTE: The `_default` scope of the `travel_sample` bucket duplicates all of the data stored in the `inventory` and `tenant_agent_00` through `tenant_agent_04` scopes. +This duplication makes the bucket compatible with scripts and applications written for versions of Couchbase Server earlier than 7.0 that did not support scopes and collections. [#install-sample-buckets-with-the-ui] == Install Sample Buckets with the UI @@ -56,9 +31,9 @@ The *Sample Buckets* screen now appears, as follows: image::manage-settings/settings-samples.png[,720,align=left] -Note that if one or more sample buckets have already been loaded, they are listed under the *Installed Samples* section of the page. +If one or more sample buckets are already loaded, they're listed under the *Installed Samples* section of the page. -For information on assigning roles to users, so as to enable them to access sample buckets following installation, see xref:manage:manage-security/manage-users-and-roles.adoc[Manage Users and Roles]. +See xref:manage:manage-security/manage-users-and-roles.adoc[Manage Users and Roles] to learn how to assign roles to users to grant access to the sample buckets. To install, select one or more sample buckets from the displayed list, using the checkboxes provided. For example, select the `travel-sample` bucket: @@ -69,8 +44,8 @@ If there is insufficient memory available for the specified installation, a noti image::manage-settings/insufficientRamWarning.png[,290,align=left] -For information on configuring memory quotas, see the information on xref:manage:manage-settings/general-settings.adoc[General] settings. -For information on managing (including deleting) buckets, see xref:manage:manage-buckets/bucket-management-overview.adoc[Manage Buckets]. +For information about configuring memory quotas, see xref:manage:manage-settings/general-settings.adoc[General] settings. +For information about managing (including deleting) buckets, see xref:manage:manage-buckets/bucket-management-overview.adoc[Manage Buckets]. If and when you have sufficient memory, click [.ui]*Load Sample Data*. @@ -83,15 +58,37 @@ See xref:manage:manage-buckets/bucket-management-overview.adoc[Manage Buckets], [#install-sample-buckets-with-the-rest-api] == Install Sample Buckets with the REST API -To install sample buckets with the REST API, use the `POST /sampleBuckets/install` HTTP method and URI, as follows: +To install sample buckets with the REST API, use the `POST /sampleBuckets/install` HTTP method and URI. +For example: + +[source,console] +---- +include::rest-api:example$install-sample-bucket.sh[] +---- + +If successful, the call returns a JSON dictionary that lists the tasks Couchbase Server started to load the buckets: + +[source,json] +---- +include::rest-api:example$sample-bucket-install-response.json[] +---- + +You can monitor the status of these tasks using the `/pools/default/tasks` REST API endpoint. +Pass it the `taskId` value from the task list returned by the call to `sampleBuckets/install`: + +[source,console] +---- +curl -s -u Administrator:password -G http://localhost:8091/pools/default/tasks \ + -d taskId=439b29de-0018-46ba-83c3-d3f58be68b12 | jq '.' +---- + +The command returns the current status of the task: +[source,json] ---- -curl -X POST -u Administrator:password \ -http://10.143.194.101:8091/sampleBuckets/install \ --d '["travel-sample", "beer-sample"]' +include::rest-api:example$beer-sample-task-status.json[] ---- -If successful, the call returns an empty list. +For more information about using the REST API, including details of how to retrieve a list of available sample buckets, see xref:rest-api:rest-sample-buckets.adoc[]. +For information about deleting buckets (including sample buckets), see xref:rest-api:rest-bucket-delete.adoc[]. -For further information on using the REST API, including details of how to retrieve a list of currently available sample buckets, see xref:rest-api:rest-sample-buckets.adoc[Managing Sample Buckets]. -For information on _deleting_ buckets (including sample buckets), see xref:rest-api:rest-bucket-delete.adoc[Deleting Buckets]. diff --git a/modules/rest-api/examples/beer-sample-task-status.json b/modules/rest-api/examples/beer-sample-task-status.json new file mode 100644 index 0000000000..e796290e0c --- /dev/null +++ b/modules/rest-api/examples/beer-sample-task-status.json @@ -0,0 +1,9 @@ +[ + { + "task_id": "439b29de-0018-46ba-83c3-d3f58be68b12", + "status": "running", + "type": "loadingSampleBucket", + "bucket": "beer-sample", + "bucket_uuid": "not_present" + } +] diff --git a/modules/rest-api/examples/install-sample-bucket.sh b/modules/rest-api/examples/install-sample-bucket.sh new file mode 100644 index 0000000000..0a4ed4a3a2 --- /dev/null +++ b/modules/rest-api/examples/install-sample-bucket.sh @@ -0,0 +1,3 @@ +curl -X POST -u Administrator:password \ + http://localhost:8091/sampleBuckets/install \ + -d '["travel-sample", "beer-sample"]' | jq . \ No newline at end of file diff --git a/modules/rest-api/examples/sample-bucket-install-response.json b/modules/rest-api/examples/sample-bucket-install-response.json new file mode 100644 index 0000000000..572ab0a7be --- /dev/null +++ b/modules/rest-api/examples/sample-bucket-install-response.json @@ -0,0 +1,14 @@ +{ + "tasks": [ + { + "taskId": "439b29de-0018-46ba-83c3-d3f58be68b12", + "sample": "beer-sample", + "bucket": "beer-sample" + }, + { + "taskId": "ed6cd88e-d704-4f91-8dd3-543e03669024", + "sample": "travel-sample", + "bucket": "travel-sample" + } + ] +} \ No newline at end of file diff --git a/modules/rest-api/examples/sample-bucket-tasks.json b/modules/rest-api/examples/sample-bucket-tasks.json new file mode 100644 index 0000000000..b408d34fdf --- /dev/null +++ b/modules/rest-api/examples/sample-bucket-tasks.json @@ -0,0 +1,18 @@ +[ + { + "statusId": "e36859e44fb7c226c180b4610313f074", + "type": "rebalance", + "subtype": "rebalance", + "status": "notRunning", + "statusIsStale": false, + "masterRequestTimedOut": false, + "lastReportURI": "/logs/rebalanceReport?reportID=af5b2ac96af031218bae6e3411b007b5" + }, + { + "task_id": "439b29de-0018-46ba-83c3-d3f58be68b12", + "status": "running", + "type": "loadingSampleBucket", + "bucket": "beer-sample", + "bucket_uuid": "not_present" + } +] diff --git a/modules/rest-api/examples/sample_bucket_load_status.sh b/modules/rest-api/examples/sample_bucket_load_status.sh new file mode 100644 index 0000000000..e178b66f02 --- /dev/null +++ b/modules/rest-api/examples/sample_bucket_load_status.sh @@ -0,0 +1,22 @@ +#!/bin/bash + +echo -e "Executing command:\ncurl -s -X POST -u Administrator:password http://node1:8091/sampleBuckets/install -d '[\"travel-sample\", \"beer-sample\"]'" + +taskIds=$(curl -s -X POST -u Administrator:password http://node1:8091/sampleBuckets/install -d '["travel-sample", "beer-sample"]' \ + | jq . | tee install_output.json | jq '.tasks[] | .taskId' | tr -d '"' ) + +cat install_output.json + +echo -e "\ntaskIds: $taskIds\n\n" + +sleep 2 + +echo -e\n\nFull task list: + +curl -s -u Administrator:password -X GET http://localhost:8091/pools/default/tasks | jq + +for id in ${taskIds}; do + echo -e "\ntaskId: $id" + echo "Running command: curl -s -u Administrator:password -G http://localhost:8091/pools/default/tasks -d \"taskId=$id\" | jq '.' " + curl -s -u Administrator:password -G http://localhost:8091/pools/default/tasks -d "taskId=$id" | jq '.' +done diff --git a/modules/rest-api/pages/rest-get-cluster-tasks.adoc b/modules/rest-api/pages/rest-get-cluster-tasks.adoc index 9c2ffd5f86..9a81eed13f 100644 --- a/modules/rest-api/pages/rest-get-cluster-tasks.adoc +++ b/modules/rest-api/pages/rest-get-cluster-tasks.adoc @@ -1,49 +1,67 @@ = Getting Cluster Tasks -:description: pass:q[A list of ongoing cluster tasks can be returned with the `GET /pools/default/tasks` HTTP method and URI.] +:description: pass:q[You can list tasks running on the cluster using the `GET /pools/default/tasks` HTTP method and URI.] :page-topic-type: reference +:page-toclevels: 3 [abstract] {description} -Additionally, a report on the last-completed rebalance can be returned with `GET /logs/rebalanceReport?reportID=`. +In addition, a report on the last-completed rebalance can be returned with `GET /logs/rebalanceReport?reportID=REPORT_ID`. [#http-method-and-uri] -== HTTP methods and URIs +== HTTP Methods and URIs ---- + GET /pools/default/tasks -GET /logs/rebalanceReport?reportID= +GET /pools/default/tasks?taskId=TASK_ID + +GET /logs/rebalanceReport?reportID=REPORT_ID ---- [#rest-get-cluster-tasks-description] == Description -By means of `GET /pools/default/tasks`, ongoing cluster-tasks can be reported; with status, id, and additional information returned for each. +Calling `GET /pools/default/tasks` lists tasks running on the cluster. +The list includes the task's ID, status, and other relevant informaatiom. +You can return information about sample bucket loading tasks by supplying its `taskId` as a parameter: `GET /pools/default/tasks?taskID=TASK_ID`. -By means of `GET /logs/rebalanceReport?reportID=`, a report can be returned, providing information on a completed _rebalance_. +Calling `GET /logs/rebalanceReport?reportID=REPORT_ID`, a report can be returned, providing information on a completed _rebalance_. The required `report-id` is provided in the object returned by `GET /pools/default/tasks`. [#curl-syntax] == Curl Syntax ---- -curl -v -X GET -u : - http://:8091/pools/default/tasks +curl -s -u USER_NAME:PASSWORD -G \ + http://NODE_NAME_OR_ADDRESS:PORT/pools/default/tasks \ + -d "taskId=TASK_ID" + -curl -v -X GET -u : - http://:8091/logs/rebalanceReport?reportID= +curl -s -u USER_NAME:PASSWORD -G + http://NODE_NAME_OR_ADDRESS:PORT/logs/rebalanceReport + -d "reportID=REPORT_ID" ---- -The required `report-id` is provided in the object returned by `GET /pools/default/tasks`, as the value of `lastReportURI`. +The arguments shown in the syntax are: + +* *`USER_NAME`*: the username to use when connecting to Couchbase Server. +* *`PASSWORD`*: the password for the user. +* *`NODE_NAME_OR_ADDRESS`*: the name or IP address of a node in the cluster. +* *`TASK_ID`*: the optional ID of a sample bucket loading task whose status you want ot view. +You can find the `taskId` for a sample bucket task from the return value of calls to either the `/sampleBuckets/install` or `/pools/default/tasks` +If you do not provide a task ID, the call returns all tasks on the cluster. +* *`REPORT_ID`*: the required rebalance report ID. +You can find this ID from the rebalance task's `lastReportURI` field in the task list returned by calling `GET /pools/default/tasks` without parameters. [#responses] == Responses -For `GET /pools/default/tasks`, success gives the response code `200 OK`, and returns an object containing information on the current status of ongoing tasks. -See the examples provided below. +A successful call to `GET /pools/default/tasks` returns the response code `200 OK` and an object containing details about a specific task when you supply a `taskId` argument. +If you do not supply the `taskId` argument, it returns an object containing information about all tasks. -For `GET /logs/rebalanceReport?reportID=`, success gives the response code `200 OK`, and returns an object that contains a report on the last-completed rebalance. -Specifying a `report-id` that cannot be found gives `200 OK`, but returns an object signifying the error, as follows: +A successful call to `GET /logs/rebalanceReport?reportID=REPORT_ID` returns response code `200 OK` and an object containing a report on the rebalance whose `reportID` matches `REPORT_ID`. +If you pass Couchbase Server a `reportID` that it cannot find, it returns the response code `200 OK` and an object containing the following error: ---- { @@ -51,7 +69,7 @@ Specifying a `report-id` that cannot be found gives `200 OK`, but returns an obj } ---- -Specifying a `report-id` of incorrect length gives `400 Bad Request`, and returns an object signifying the error, as follows: +Passing a `reportID` of incorrect length returns `400 Bad Request` and an object with the following error message: ---- { @@ -61,25 +79,25 @@ Specifying a `report-id` of incorrect length gives `400 Bad Request`, and return } ---- -For both calls, failure to authenticate gives `401 Unauthorized`. +For both endpoints, failure to authenticate returns the response `401 Unauthorized`. [#examples] == Examples: Retrieving Cluster Tasks -The following examples show output returned in accordance with _whether_ tasks are in progress; and if so, _which_. +The following examples demonstrate using the `/pools/default/tasks` and `/logs/rebalanceReport` endpoints. [#no-tasks-underway] -=== No Tasks Underway +=== No Tasks Running + +When the cluster has no tasks running, calling the `/pools/default/tasks` method returns just the most recent rebalance task: -When the cluster has no tasks underway, the method verifies this. -Here, the output is piped to the https://stedolan.github.io/jq[jq] tool, to enhance readability. ---- curl -u Administrator:password -v -X GET \ -http://10.143.194.101:8091/pools/default/tasks | jq '.' + http://10.143.194.101:8091/pools/default/tasks | jq '.' ---- -Output is as follows: +Output is piped through the https://stedolan.github.io/jq[`jq`^] tool to enhance readability and appears as the following: ---- [ @@ -96,42 +114,144 @@ Output is as follows: The default output indicates that no rebalance is underway. A `statusId` and task `type` are provided. -The `lastReportURI` specifies the location of the _report_ of the last rebalance to have been performed. +The `lastReportURI` specifies the location of the report of the last rebalance to have been performed. See the xref:rebalance-reference:rebalance-reference.adoc[Rebalance Reference], for further information. [#adding-a-bucket] -=== Adding a Bucket +[#loading-a-sample-bucket] +=== Monitoring Sample Bucket Loading Tasks + +You can monitor the tasks Couchbase Server starts to load one or more samples buckets through the `/pools/default/tasks` method. +The following example starts loading two sample buckets by calling the `/sampleBuckets/install` endpoint: + +[source, console] +---- +include::rest-api:example$install-sample-bucket.sh[] +---- -When a bucket is being added (in this case, the sample bucket `beer-sample`), status can be returned by entering the method in the standard way, specifying the IP address of the cluster, or `localhost`, as appropriate: +The response lists the tasks the method call started to load the sample buckets: +[source, json] +---- +include::rest-api:example$sample-bucket-install-response.json[] +---- + +You can also list the tasks using the `/pools/default/tasks` method: + +[source, console] ---- curl -u Administrator:password -v -X GET \ -http://localhost:8091/pools/default/tasks | jq '.' + http://localhost:8091/pools/default/tasks | jq '.' +---- + +The output of this call returns the active sample bucket task which is loading the `beer-sample` bucket: + +[source, json] +---- +include::rest-api:example$sample-bucket-tasks.json[] +---- + +NOTE: The task for loading the `travel-sample` does not appear in the previous output because it is not currently running. +Only one sample bucket task runs at a time. + +To monitor a sample bucket task specifically, you can call `/pools/default/tasks` with the `taskId` found in either the response from `/sampleBuckets/install` or the list of tasks from `/pools/default/tasks`. +The following example demonstrates getting the status of the `travel-sample` bucket task: + +[source, console] +---- + curl -s -u Administrator:password -G \ + http://localhost:8091/pools/default/tasks \ + -d "taskId=ed6cd88e-d704-4f91-8dd3-543e03669024" | jq '.' +---- + +The result shows that the task is queued: + +[source, json] +---- +[ + { + "task_id": "f1c55abe-926a-415d-bf36-f3d99c27016f", + "status": "queued", + "type": "loadingSampleBucket", + "bucket": "travel-sample", + "bucket_uuid": "not_present" + } +] +---- + +Viewing the status of the `beer-sample` task shows that it's running: + +[source, json] +---- +[ + { + "task_id": "e2a5e251-faee-415d-b146-d0891123075b", + "status": "running", + "type": "loadingSampleBucket", + "bucket": "beer-sample", + "bucket_uuid": "not_present" + } +] ---- -Output is as follows: +After the `beer-sample` tasks finishes, Coucbbase Server starts the `travel-sample` task. +Calling `/pools/default/tasks` again without a `taskId` shows the `travel-sample` task as well as a number of indexing tasks, as shown in the following result: +[source, json] ---- [ { - "statusId": "1f05320a7b359e1672ffc8b7ee69a8b5", + "statusId": "e36859e44fb7c226c180b4610313f074", "type": "rebalance", + "subtype": "rebalance", "status": "notRunning", "statusIsStale": false, "masterRequestTimedOut": false, - "lastReportURI": "/logs/rebalanceReport?reportID=0c41dba637a8971b1aa921a89e851d83" + "lastReportURI": "/logs/rebalanceReport?reportID=af5b2ac96af031218bae6e3411b007b5" + }, + { + "type": "global_indexes", + "recommendedRefreshPeriod": 2, + "status": "running", + "bucket": "travel-sample", + "index": "def_inventory_route_sourceairport", + "id": 5548520957444133000, + "progress": 0, + "statusIsStale": false }, { + "type": "global_indexes", + "recommendedRefreshPeriod": 2, + "status": "running", + "bucket": "travel-sample", + "index": "def_inventory_route_schedule_utc", + "id": 7890207154426784000, + "progress": 19, + "statusIsStale": false + }, + . + . + . + { + "type": "global_indexes", + "recommendedRefreshPeriod": 2, + "status": "running", + "bucket": "travel-sample", + "index": "def_inventory_airline_primary", + "id": 2691871325047162400, + "progress": 12, + "statusIsStale": false + }, + { + "task_id": "f1c55abe-926a-415d-bf36-f3d99c27016f", "status": "running", "type": "loadingSampleBucket", - "bucket": "beer-sample", - "pid": "<0.24849.21>" + "bucket": "travel-sample", + "bucket_uuid": "not_present" } ] ---- -The output indicates that no rebalance is underway, but that the `loadingSampleBucket` operation is ongoing. - [#compacting-a-bucket] === Compacting a Bucket @@ -171,32 +291,13 @@ The output indicates that the `beer-sample` bucket is being compacted. Progress is reported in terms of `changesDone`, `totalChanges`, and a `progress` figure that is a percentage of total completion. A URI is provided for cancelling compaction, if required. -[#loading-a-sample-bucket] -=== Loading a Sample Bucket -If a sample bucket is loaded, task status can be returned, by entering the method in the standard way, specifying the IP address of the cluster, or `localhost`, as appropriate: - ----- -curl -X GET http://localhost:8091/pools/default/tasks -u Administrator:password | jq '.' ----- - -The output includes the following: - ----- -{ - "status": "running", - "type": "loadingSampleBucket", - "bucket": "travel-sample", - "pid": "<0.11528.51>" -} ----- -This indicates that the `travel-sample` bucket is being loaded, and shows the process id for the task. [#performing-xdcr] === Performing XDCR -If an instance of XDCR is underway, its task status can be returned, by entering the method in the standard way, specifying the IP address of the cluster, or `localhost`, as appropriate: +You can monitor an ongoing XDCR task using the `/pools/default/tasks` method: ---- curl -X GET http://localhost:8091/pools/default/tasks -u Administrator:password | jq '.' diff --git a/modules/rest-api/pages/rest-sample-buckets.adoc b/modules/rest-api/pages/rest-sample-buckets.adoc index fb8a4ba0bf..7bf16099a2 100644 --- a/modules/rest-api/pages/rest-sample-buckets.adoc +++ b/modules/rest-api/pages/rest-sample-buckets.adoc @@ -1,18 +1,16 @@ = Managing Sample Buckets -:description: pass:q[Couchbase Server allows _sample buckets_ to be installed. \ -These contain data ready to be used for development and testing.] +:description: pass:q[Couchbase Server offers several sample buckets you can install for development and testing.] :page-topic-type: reference [abstract] -{description} + == Description -Couchbase Server allows _sample buckets_ to be installed, and then used for development and testing. +{description} -== HTTP methods and URIs -The following methods and URIs respectively allow the names of the currently available sample buckets to be retrieved, and one or more to be installed on the cluster. +== HTTP Methods and URIs ---- GET /sampleBuckets @@ -20,40 +18,49 @@ GET /sampleBuckets POST /sampleBuckets/install ---- +== Description + +Gets the list of sample buckets available in Couchbase Server and installs one or more sample buckets. + == Curl Syntax +[source,console] ---- -curl -X GET -u [username]:[password] - http://[node-name-or-ip-address]:8091/sampleBuckets +curl -X GET -u USERNAME:PASSWORD + http://NODE_NAME_OR_IP:PORT/sampleBuckets -curl -X POST -u [username]:[password] - http://[node-name-or-ip-address]:8091/sampleBuckets/install - -d '[ , ]' +curl -X POST -u USERNAME:PASSWORD + http://NODE_NAME_OR_IP:PORT/sampleBuckets/install + -d '[ "SAMPLE_BUCKET_NAME", ... ]' ---- -The `node-name-or-ip-address` can be that of any node in the cluster. -Each `bucketname` must be the name of an available sample bucket, specified as a string. +* *`NODENAME_OR_IP`*: a node in the cluster. +* *`"SAMPLE_BUCKET_NAME"`*: the name of a sample bucket, specified as a string. You can provide a comma separated list of sample buckets to install. == Responses -If the GET is successful, `200 OK` is given, and an object describing available sample buckets is returned. -If the POST is successful, `200 OK` is given, and an empty message-list is returned. -In either case, an incorrectly specified bucket-name or URI gives `404 Object Not Found`; and failure to authenticate gives `401 Unauthorized`. +If the GET succeeds, it returns `200 OK` and a JSON object describing available sample buckets. + +If the POST succeeds, it returns `200 OK` and a JSON array containing information about the tasks Couchbase Server started to load the buckets. -Incorrectly using the POST to install one or more sample buckets that are already installed returns a list containing a message for each error; such as `["Sample bucket travel-sample is already loaded.","Sample bucket beer-sample is already loaded."]`. +For either endpoint, an incorrectly specified bucket-name or URI gives `404 Object Not Found`; and failure to authenticate gives `401 Unauthorized`. + +Calling the POST endpoint to install one or more sample buckets that are already installed returns a list containing a message for each error; such as `["Sample bucket travel-sample is already loaded.","Sample bucket beer-sample is already loaded."]`. == Examples The following example retrieves a list of the currently available sample buckets. Note that the output is piped to the https://https://stedolan.github.io/jq/[jq] program, to facilitate readability. +[source,console] ---- curl -X GET -u Administrator:password \ http://10.143.194.101:8091/sampleBuckets | jq ---- -If successful, the call returns output such as the following: +If successful, the call returns output similar to the following: +[source,json] ---- [ { @@ -74,23 +81,31 @@ If successful, the call returns output such as the following: ] ---- -Each available bucket is listed, along with its current install-status (`true` or `false`). -The memory quota required for each bucket, in Bytes, is also stated: note that this minimum must be available even though the actual sample bucket might not, with its default content, require it all. +The output lists the available sample buckets and whether it's installed and the memory required to install the bucket. + +NOTE: the `quotaNeeded` value is the minimum that Couchbase Server must have available. +The sample bucket might not consume this entire value when you install it. The following example installs the `travel-sample` and `beer-sample` sample buckets: +[source,console] ---- -curl -X POST -u Administrator:password \ -http://10.143.194.101:8091/sampleBuckets/install \ --d '["travel-sample", "beer-sample"]' +include::rest-api:example$install-sample-bucket.sh[] ---- -If successful, the call returns an empty list. +If successful, the call returns a JSON array containing the tasks that Couchbase Server started to load the buckets: -== See Also +[source,json] +---- +include::rest-api:example$sample-bucket-install-response.json[] +---- -Information on _deleting_ buckets is provided in xref:rest-api:rest-bucket-delete.adoc[Deleting Buckets]. +You can monitor the status of these tasks by calling the `/pools/default/tasks` REST API endpoint. +See xref:rest-get-cluster-tasks.adoc[] for more information. -Information on installing sample buckets with the CLI is provided in xref:cli:cbdocloader-tool.adoc[cbdocloader]. +== See Also -Information on installing sample buckets with Couchbase Web Console is provided in xref:manage:manage-settings/install-sample-buckets.adoc[Sample Buckets]. +* For an overview of sample buckets, see xref:manage:manage-settings/install-sample-buckets.adoc[]. +* xref:rest-api:rest-bucket-delete.adoc[] explains deleting buckets using the REST-API. +* xref:cli:cbdocloader-tool.adoc[cbdocloader] explains how to install sample buckets using the command line interface. +* xref:manage:manage-settings/install-sample-buckets.adoc[] explains how to load sample buckets using the Couchbase Server Web Console.