Collections via CLI
- Developer Preview
Collections can be managed by means of the Couchbase CLI.
Using the CLI
The following sequence of CLI commands demonstrates how to create, examine, and delete scopes and collections. It assumes that Couchbase Server has been installed, initialized, and provisioned on a Ubuntu system. Note, however, that the sequence should work identically on other Linux systems; as well as on MacOS and Windows systems.
At the command-line prompt, proceed as follows:
-
Create a bucket, named
test-bucket
, using the couchbase-clibucket-create
command./opt/couchbase/bin/couchbase-cli bucket-create \ --cluster localhost:8091 --username Administrator \ --password password --bucket testBucket --bucket-type couchbase \ --bucket-ramsize 100
If the command is successful, the following output is displayed:
SUCCESS: Bucket created
For more information on this command, see bucket-create.
-
Using the
cbstats
command, check that collections have been enabled, and check the maximum size for collections, then for scopes:/opt/couchbase/bin/cbstats -u Administrator -p password localhost:11210 -b testBucket all | grep collections
The following output is displayed:
ep_collections_enabled: true ep_collections_max_size: 1000
This indicates that collections are enabled, and that a maximum number 1000 collections can be created for the bucket.
Check the maximum size for scopes:
/opt/couchbase/bin/cbstats -u Administrator -p password localhost:11210 -b testBucket all | grep scopes
The following output is displayed:
ep_scopes_max_size: 100
The output indicates that a maximum number of 100 scopes can be created for the bucket.
-
Create a scope, using the couchbase-cli
collection-manage
command. The--bucket
parameter specifies the name of the bucket within which the scope will be created; and the--create-scope
parameter specifies the name of the scope./opt/couchbase/bin/couchbase-cli collection-manage \ --cluster http://localhost:8091 \ --username Administrator \ --password password \ --bucket testBucket \ --create-scope my_scope
If the command is successful, the following output is displayed:
SUCCESS: Scope created
-
List the scopes now contained by the bucket
testBucket
./opt/couchbase/bin/couchbase-cli collection-manage \ -c localhost \ --username Administrator \ --password password \ --bucket testBucket \ --list-scopes
The following output is displayed:
_default my_scope
This indicates that
testBucket
now contains two scopes. One is the_default
, the other is the newly created scopemy_scope
. -
Use
collection-manage
successively, to create two collections withinmy_scope
. The name of the collection to be created is specified with the--create-collection
parameter, using a path in dot format (that is, in the form scope-name.collection-name) to specify the destination scope. Then, list the collections in the scope, using collection-manage with the--list-collections
parameter.Create the
my_scope.my_collection_in_my_scope_1
collection:/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \ --username Administrator \ --password password \ --bucket testBucket \ --create-collection my_scope.my_collection_in_my_scope_1
On success, the output is as follows:
SUCCESS: Collection created
Create the
my_scope.my_collection_in_my_scope_2
collection:/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \ --username Administrator \ --password password \ --bucket testBucket \ --create-collection my_scope.my_collection_in_my_scope_2
On success, the output is as again follows:
SUCCESS: Collection created
Now, list all collections:
/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \ --username Administrator \ --password password \ --bucket testBucket \ --list-collections my_scope
If the command is successful, the output features a list of all created collections within
my_scope
:my_collection_in_my_scope_1 my_collection_in_my_scope_2
The output indicates that
my_scope
now contains the collectionsmy_collection_in_my_scope_1
andmy_collection_in_my_scope_1
. -
Create a collection in the
_default
scope, and then list collections within that scope./opt/couchbase/bin/couchbase-cli collection-manage -c localhost \ --username Administrator \ --password password \ --bucket testBucket \ --create-collection _default.my_collection_in_default_scope
On success, the following output is displayed:
SUCCESS: Collection created
Now, list collections within the scope:
/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \ --username Administrator \ --password password \ --bucket testBucket \ --list-collections _default
On success, a list of the collections in the scope is displayed:
my_collection_in_default_scope _default
The output indicates that the _default scope now contains two collections, which are the
_default
collection, and the newly created collectionmy_collection_in_default_scope
. -
Create two documents, within the default scope and collection, using the
cbc create
command. Note that if no scope or collection is explicitly specified, the default scope and collection are assumed./opt/couchbase/bin/cbc create -u Administrator -P password testDocument1 \ -U couchbase://localhost/testBucket \ -V '{"key1" : "value1"}'
On success, this produces output indicating that the named document has been saved, and providing its CAS number.
testDocument1 Stored. CAS=0x15833ec67e800000
Now, create the second document:
/opt/couchbase/bin/cbc create -u Administrator -P password testDocument2 \ -U couchbase://10.143.192.101/testBucket \ -V '{"key2" : "value2"}'
On success, the output is as follows:
testDocument2 Stored. CAS=0x15833ec889540000
-
Display statistics on existing collections, using the
cbstats
command, specifying the collections parameter./opt/couchbase/bin/cbstats -u Administrator -p password \ -b testBucket localhost:11210 collections
Statistics are displayed as follows:
collection:0x0:items: 2 collection:0x8:items: 0 collection:0x9:items: 0 collection:0xa:items: 0 manifest:collection:0x0:name: _default manifest:collection:0x8:name: my_collection_in_my_scope_1 manifest:collection:0x9:name: my_collection_in_my_scope_2 manifest:collection:0xa:name: my_collection_in_default_scope manifest:collections: 4 manifest:default_exists: true manifest:uid: 4
Note that the output identifies the
_default
collection as0x0
, and indicates that this contains 2 items: these correspond to the two documents previously created withcbc create
. -
Again display statistics on existing collections using the
cbstats
command, this time specifying thecollections-details
parameter./opt/couchbase/bin/cbstats -u Administrator -p password -b testBucket \ localhost:11210 collections-details
Statistics are displayed as follows:
manifest:collection:0x0:name: _default manifest:collection:0x8:name: my_collection_in_my_scope_1 manifest:collection:0x9:name: my_collection_in_my_scope_2 manifest:collection:0xa:name: my_collection_in_default_scope manifest:collections: 4 manifest:default_exists: true manifest:uid: 4 vb_0:collection:0x0:entry:high_seqno: 0 vb_0:collection:0x0:entry:items: 0 vb_0:collection:0x0:entry:persisted_high_seqno: 0 vb_0:collection:0x0:entry:scope: 0 vb_0:collection:0x0:entry:start_seqno: 0 vb_0:collection:0x8:entry:high_seqno: 2 vb_0:collection:0x8:entry:items: 0 vb_0:collection:0x8:entry:persisted_high_seqno: 2 vb_0:collection:0x8:entry:scope: 8 vb_0:collection:0x8:entry:start_seqno: 2 vb_0:collection:0x9:entry:high_seqno: 3 vb_0:collection:0x9:entry:items: 0 . .
The output, which is presented here in truncated form, provides additional details on scopes, collections, and their content; including sequence numbers, uid numbers, and per-vBucket information. Note that an identifying vBucket-number can be specified, to produce output for that vBucket alone:
/opt/couchbase/bin/cbstats -u Administrator -p password -b testBucket localhost:11210 collections-details 8
The number
8
having been specified, displayed statistics are for vBucket 8 only:vb_8:collection:0x0:entry:high_seqno: 0 vb_8:collection:0x0:entry:items: 0 vb_8:collection:0x0:entry:persisted_high_seqno: 0 vb_8:collection:0x0:entry:scope: 0 vb_8:collection:0x0:entry:start_seqno: 0 vb_8:collection:0x8:entry:high_seqno: 2 vb_8:collection:0x8:entry:items: 0 vb_8:collection:0x8:entry:persisted_high_seqno: 2 vb_8:collection:0x8:entry:scope: 8 vb_8:collection:0x8:entry:start_seqno: 2 vb_8:collection:0x9:entry:high_seqno: 3 vb_8:collection:0x9:entry:items: 0 vb_8:collection:0x9:entry:persisted_high_seqno: 3 vb_8:collection:0x9:entry:scope: 8 vb_8:collection:0x9:entry:start_seqno: 3 vb_8:collection:0xa:entry:high_seqno: 4 vb_8:collection:0xa:entry:items: 0 vb_8:collection:0xa:entry:persisted_high_seqno: 4 vb_8:collection:0xa:entry:scope: 0 vb_8:collection:0xa:entry:start_seqno: 4 vb_8:manifest:default_exists: true vb_8:manifest:entries: 4
-
Drop a collection from the created scope, then list collections within that scope.
/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \ --username Administrator \ --password password \ --bucket testBucket \ --drop-collection my_scope.my_collection_in_my_scope_1
If the command is successful, the following is displayed:
SUCCESS: Collection deleted
Note that in this context,
deleted
meansdropped
./opt/couchbase/bin/couchbase-cli collection-manage -c localhost \ --username Administrator \ --password password \ --bucket testBucket \ --list-collections my_scope
Output features each collection in the specified scope:
my_collection_in_my_scope_2
The output indicates that the collection
my_collection_in_my_scope_1
has now been dropped frommy_scope
. -
Drop the created scope, then list scopes.
/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \ --username Administrator \ --password password \ --bucket testBucket \ --drop-scope my_scope
On success, the following output is displayed:
SUCCESS: Scope deleted
List all remaining scopes:
/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \ --username Administrator \ --password password \ --bucket testBucket \ --list-scopes
The following output is displayed:
_default
This indicates that
my_scope
, and the collection it contained,my_collection_in_my_scope_2
, have been dropped.
This concludes the sequence of commands.