Skip to content

Commit e59a3fa

Browse files
ggray-cbPeter-Searby
authored and
julia-cb
committed
DOC-11398 sample bucket loading status (#3547)
* Initial changes to the manage topic on loading example buckets. * Full draft. Cleanup of docs to meet standards. * Some more edits * Added What's New entry * Removed space * Update modules/introduction/partials/new-features-76.adoc Typo fix by Peter. Co-authored-by: Peter Searby <6184793+Peter-Searby@users.noreply.github.com> * Added description of the inventory scope back to discussion of the travel_sample bucket. --------- Co-authored-by: Peter Searby <6184793+Peter-Searby@users.noreply.github.com>
1 parent aa248d9 commit e59a3fa

File tree

9 files changed

+311
-128
lines changed

9 files changed

+311
-128
lines changed

‎modules/introduction/partials/new-features-76.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,10 @@ See xref:rest-api:rest-auditing.adoc[Configure Auditing].
4545
* You can add one or more arbiter nodes to a cluster.
4646
include::learn:partial$arbiter-node-benefits.adoc[]
4747

48+
* The `sampleBuckets/install` REST API method now returns a JSON object containing the list of tasks Couchbase Server started to load the buckets.
49+
In addition, the `/pools/default/tasks` REST API endpoint now takes an optional `taskId` parameter to view details about a sample bucket loading task.
50+
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.
51+
4852
=== Backup and Restore
4953

5054
* 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].

‎modules/manage/pages/manage-settings/install-sample-buckets.adoc‎

Lines changed: 43 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
= Sample Buckets
2-
:description: Sample buckets contain scopes, collections, and documents that are ready to be experimented with.
2+
:description: You can install buckets containing example scopes, collections, and documents that you can experiment with.
33
:page-aliases: settings:install-sample-buckets
44

55
[abstract]
@@ -8,45 +8,20 @@
88
[#configuring-sample-buckets]
99
== Sample Buckets
1010

11-
Sample buckets contain data for experimental use.
12-
Sample buckets are referred to in code and command-line examples throughout Couchbase-Server documentation.
13-
14-
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].
11+
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].
1512

1613
[#scopes-collection-and-sample-buckets]
1714
=== Scopes, Collections, and Sample Buckets
1815

19-
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.
20-
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.
21-
From this point, data can be selectively migrated from the default collection into other, administrator-defined collections.
22-
23-
Each sample bucket provided with 7.x contains its data _either_:
24-
25-
* Entirely within the default scope and collection.
26-
These buckets are `beer-sample` and `gamesim-sample`.
27-
28-
* 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.
29-
This is the configuration provided for the `travel-sample` bucket.
30-
In total, _seven_ scopes exist within this bucket:
31-
32-
** `_default`.
33-
This contains the `_default` collection; within which all documents reside.
34-
The `_default` collection therefore itself contains all documents that existed in pre-7.0 versions of the `travel-sample` bucket.
35-
36-
** `inventory`.
37-
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`.
16+
xref:learn:data/scopes-and-collections.adoc[Scopes and Collections] let you organize data within a bucket by type.
17+
The `beer-sample` and `gamesim-sample` sample buckets store all of their data in the default scope.
18+
The `travel-sample` bucket contains data in six scopes in addition to the `_default` scope.
19+
These additional scopes define several collections.
20+
The `inventory` scope has collections that organize travel data such as airlines and airports.
21+
The data within the `tenant_agent_00` through `tenant_agent_04` scopes let you experiment with multi-tenancy applications.
3822

39-
** `tenant_agent_00` to `tenant_agent_04`.
40-
Each of these five scopes contains two collections; which are named `users` and `bookings`.
41-
42-
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.
43-
All three buckets can also be used for experiments with _migration_, whereby the data is selectively redistributed into administrator-created collections.
44-
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].
45-
46-
The `travel-sample` bucket contains travel-related data already in migrated form, within the collections in the scope `inventory`.
47-
The bucket can thus be used for immediate experimentation with application-access to scopes and collections.
48-
49-
The `travel-sample` bucket also contains data within the `tenant_agent` scopes, which is appropriate for experimentation with _multi-tenancy-based_ application access.
23+
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.
24+
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.
5025

5126
[#install-sample-buckets-with-the-ui]
5227
== Install Sample Buckets with the UI
@@ -56,9 +31,9 @@ The *Sample Buckets* screen now appears, as follows:
5631

5732
image::manage-settings/settings-samples.png[,720,align=left]
5833

59-
Note that if one or more sample buckets have already been loaded, they are listed under the *Installed Samples* section of the page.
34+
If one or more sample buckets are already loaded, they're listed under the *Installed Samples* section of the page.
6035

61-
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].
36+
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.
6237

6338
To install, select one or more sample buckets from the displayed list, using the checkboxes provided.
6439
For example, select the `travel-sample` bucket:
@@ -69,8 +44,8 @@ If there is insufficient memory available for the specified installation, a noti
6944

7045
image::manage-settings/insufficientRamWarning.png[,290,align=left]
7146

72-
For information on configuring memory quotas, see the information on xref:manage:manage-settings/general-settings.adoc[General] settings.
73-
For information on managing (including deleting) buckets, see xref:manage:manage-buckets/bucket-management-overview.adoc[Manage Buckets].
47+
For information about configuring memory quotas, see xref:manage:manage-settings/general-settings.adoc[General] settings.
48+
For information about managing (including deleting) buckets, see xref:manage:manage-buckets/bucket-management-overview.adoc[Manage Buckets].
7449

7550
If and when you have sufficient memory, click [.ui]*Load Sample Data*.
7651

@@ -83,15 +58,37 @@ See xref:manage:manage-buckets/bucket-management-overview.adoc[Manage Buckets],
8358
[#install-sample-buckets-with-the-rest-api]
8459
== Install Sample Buckets with the REST API
8560

86-
To install sample buckets with the REST API, use the `POST /sampleBuckets/install` HTTP method and URI, as follows:
61+
To install sample buckets with the REST API, use the `POST /sampleBuckets/install` HTTP method and URI.
62+
For example:
63+
64+
[source,console]
65+
----
66+
include::rest-api:example$install-sample-bucket.sh[]
67+
----
68+
69+
If successful, the call returns a JSON dictionary that lists the tasks Couchbase Server started to load the buckets:
70+
71+
[source,json]
72+
----
73+
include::rest-api:example$sample-bucket-install-response.json[]
74+
----
75+
76+
You can monitor the status of these tasks using the `/pools/default/tasks` REST API endpoint.
77+
Pass it the `taskId` value from the task list returned by the call to `sampleBuckets/install`:
78+
79+
[source,console]
80+
----
81+
curl -s -u Administrator:password -G http://localhost:8091/pools/default/tasks \
82+
-d taskId=439b29de-0018-46ba-83c3-d3f58be68b12 | jq '.'
83+
----
84+
85+
The command returns the current status of the task:
8786

87+
[source,json]
8888
----
89-
curl -X POST -u Administrator:password \
90-
http://10.143.194.101:8091/sampleBuckets/install \
91-
-d '["travel-sample", "beer-sample"]'
89+
include::rest-api:example$beer-sample-task-status.json[]
9290
----
9391

94-
If successful, the call returns an empty list.
92+
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[].
93+
For information about deleting buckets (including sample buckets), see xref:rest-api:rest-bucket-delete.adoc[].
9594

96-
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].
97-
For information on _deleting_ buckets (including sample buckets), see xref:rest-api:rest-bucket-delete.adoc[Deleting Buckets].

‎modules/rest-api/examples/beer-sample-task-status.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[
2+
{
3+
"task_id": "439b29de-0018-46ba-83c3-d3f58be68b12",
4+
"status": "running",
5+
"type": "loadingSampleBucket",
6+
"bucket": "beer-sample",
7+
"bucket_uuid": "not_present"
8+
}
9+
]

‎modules/rest-api/examples/install-sample-bucket.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
curl -X POST -u Administrator:password \
2+
http://localhost:8091/sampleBuckets/install \
3+
-d '["travel-sample", "beer-sample"]' | jq .

‎modules/rest-api/examples/sample-bucket-install-response.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"tasks": [
3+
{
4+
"taskId": "439b29de-0018-46ba-83c3-d3f58be68b12",
5+
"sample": "beer-sample",
6+
"bucket": "beer-sample"
7+
},
8+
{
9+
"taskId": "ed6cd88e-d704-4f91-8dd3-543e03669024",
10+
"sample": "travel-sample",
11+
"bucket": "travel-sample"
12+
}
13+
]
14+
}

‎modules/rest-api/examples/sample-bucket-tasks.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[
2+
{
3+
"statusId": "e36859e44fb7c226c180b4610313f074",
4+
"type": "rebalance",
5+
"subtype": "rebalance",
6+
"status": "notRunning",
7+
"statusIsStale": false,
8+
"masterRequestTimedOut": false,
9+
"lastReportURI": "/logs/rebalanceReport?reportID=af5b2ac96af031218bae6e3411b007b5"
10+
},
11+
{
12+
"task_id": "439b29de-0018-46ba-83c3-d3f58be68b12",
13+
"status": "running",
14+
"type": "loadingSampleBucket",
15+
"bucket": "beer-sample",
16+
"bucket_uuid": "not_present"
17+
}
18+
]

‎modules/rest-api/examples/sample_bucket_load_status.sh‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
#!/bin/bash
2+
3+
echo -e "Executing command:\ncurl -s -X POST -u Administrator:password http://node1:8091/sampleBuckets/install -d '[\"travel-sample\", \"beer-sample\"]'"
4+
5+
taskIds=$(curl -s -X POST -u Administrator:password http://node1:8091/sampleBuckets/install -d '["travel-sample", "beer-sample"]' \
6+
| jq . | tee install_output.json | jq '.tasks[] | .taskId' | tr -d '"' )
7+
8+
cat install_output.json
9+
10+
echo -e "\ntaskIds: $taskIds\n\n"
11+
12+
sleep 2
13+
14+
echo -e\n\nFull task list:
15+
16+
curl -s -u Administrator:password -X GET http://localhost:8091/pools/default/tasks | jq
17+
18+
for id in ${taskIds}; do
19+
echo -e "\ntaskId: $id"
20+
echo "Running command: curl -s -u Administrator:password -G http://localhost:8091/pools/default/tasks -d \"taskId=$id\" | jq '.' "
21+
curl -s -u Administrator:password -G http://localhost:8091/pools/default/tasks -d "taskId=$id" | jq '.'
22+
done

0 commit comments

Comments
 (0)