You are viewing the documentation for a prerelease version.

Manage Scopes and Collections

    +
    Scopes and collections can be managed by means of the UI, CLI, and REST API.

    Understanding Scopes and Collections

    Scopes and collections allow documents to be categorized and organized, within a bucket. A collection is a data container, defined on Couchbase Server, within a bucket whose type is either Couchbase or Ephemeral. A scope is a mechanism for the grouping of multiple collections. A complete overview is provided in Scopes and Collections.

    Examples on This Page

    The examples on this page demonstrate how to manage scopes and collections with the UI, the CLI, and the REST API.

    Manage Scopes and Collections with the UI

    The following sequence demonstrates how to create, examine, and delete scopes and collections, using the UI of Couchbase Web Console. Proceed as follows:

    1. Access Couchbase Web Console, and left-click on the Buckets tab, in the vertical, left-hand navigation bar:

      leftClickOnBucketsTab

      This brings up the Buckets screen.

    2. Add a new bucket, named testBucket. Left-click on the ADD BUCKET tab, at the upper right:

      addBucketTab

      This brings up the Add Data Bucket dialog. Use this to create testBucket as a Couchbase bucket of 256 MB, as follows:

      createTestBucket

      Left-click on the Add Bucket button, to create. The Buckets screen now displays the newly created bucket:

      bucketsScreenWithNewBucket
    3. Examine the new bucket’s default collection. At the right-hand side of the row that displays the new bucket, two options appear: Documents and Scopes & Collections. Left-click on the Scopes & Collections option:

      selectCollectionsOption

      This brings up the Scopes & Collections screen, which appears as follows:

      scopesAndCollectionsScreenInitial

      The screen features a single row, which confirms the existence of the _default scope. As its name indicates, this scope is created by default for each new bucket. Collections that are created without any administrator-defined scope specified as their destination are duly saved in the _default scope.

      To examine the contents of the _default scope, left-click on the row. The row expands as follows:

      sACscreenWithDefaultSandC

      This indicates that the _default scope contains a single collection, which is the _default collection. As its name indicates, this collection is created by default, within the _default scope, for each new bucket. Documents that are created without any administrator-defined collection specified as their destination are duly saved in the _default collection.

    4. Add a scope to the bucket. Left-click on the ADD SCOPE tab, at the upper right of the screen:

      addScope

      This brings up the Add Scope dialog, which appears as follows:

      addScopeDialog

      Enter the name of a new scope into the New Scope Name field: for example, MyScope. Then, left-click on the Save button.

      The Scopes & Collections screen now appears as follows:

      sACscreenWithNewScope

      The new scope, MyScope, is now displayed.

    5. Add a new collection, within the new scope. At the extreme right of the row for MyScope are two options: Drop and Add Collection. Left-click on Add Collection:

      addCollection

      This brings up a dialog entitled Add Collection into MyScope scope:

      addCollectionDialog

      Enter the name of a new collection into the Name field: for example, MyCollection. Left-click on the Save button.

      Next, left-click on the row for MyScope. The row expands, as follows:

      newCollectionInNewScope

      The new collection, MyCollection, is thus shown to have been created within the scope MyScope.

    Manage Scopes and Collections with the CLI

    The following sequence of CLI commands demonstrates how to create, examine, and delete scopes and collections. Proceed as follows:

    At the command-line prompt, proceed as follows:

    1. Create a bucket, named testBucket, using the couchbase-cli bucket-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.

    2. Using the cbstats command, confirm that collections have been enabled:

      /opt/couchbase/bin/cbstats -u Administrator -p password localhost:11210 -b testBucket all | grep collections

      The following output is displayed:

      ep_collections_enabled:                                true

      This indicates that collections are enabled.

    3. 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
    4. 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 scope my_scope.

    5. Use collection-manage successively, to create two collections within my_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:

      Scope my_scope:
          - my_collection_in_my_scope_2
          - my_collection_in_my_scope_1

      The output indicates that my_scope now contains the collections my_collection_in_my_scope_1 and my_collection_in_my_scope_2.

    6. 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:

      Scope _default:
          - 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 collection my_collection_in_default_scope.

    7. 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=0x16418976851b0000
                           SYNCTOKEN=816,280885798870784,5

      Now, create the second document:

      /opt/couchbase/bin/cbc create -u Administrator -P password testDocument2 \
      -U couchbase://localhost/testBucket \
      -V '{"key2" : "value2"}'

      On success, the output is as follows:

      testDocument2        Stored. CAS=0x1641898661110000
                           SYNCTOKEN=569,130353047883317,5
    8. 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:

      0x0:0x0:disk_size:  58
      0x0:0x0:items:      2
      0x0:0x0:mem_used:   180
      0x0:0x0:name:       _default
      0x0:0x0:ops_delete: 0
      0x0:0x0:ops_get:    0
      0x0:0x0:ops_store:  2
      0x0:0x0:scope_name: _default
      0x0:0xa:disk_size:  78848
      0x0:0xa:items:      0
      0x0:0xa:mem_used:   0
      0x0:0xa:name:       my_collection_in_default_scope
      0x0:0xa:ops_delete: 0
      0x0:0xa:ops_get:    0
      0x0:0xa:ops_store:  0
      0x0:0xa:scope_name: _default
      0x8:0x8:disk_size:  80896
      0x8:0x8:items:      0
      0x8:0x8:mem_used:   0
      0x8:0x8:name:       my_collection_in_my_scope_1
      0x8:0x8:ops_delete: 0
      0x8:0x8:ops_get:    0
      0x8:0x8:ops_store:  0
      0x8:0x8:scope_name: my_scope
      0x8:0x9:disk_size:  82944
      0x8:0x9:items:      0
      0x8:0x9:mem_used:   0
      0x8:0x9:name:       my_collection_in_my_scope_2
      0x8:0x9:ops_delete: 0
      0x8:0x9:ops_get:    0
      0x8:0x9:ops_store:  0
      0x8:0x9:scope_name: my_scope
      manifest_uid:       4

      Note that the output identifies the _default collection as 0x0, and indicates that this contains 2 items: these correspond to the two documents previously created with cbc create.

    9. Again display statistics on existing collections using the cbstats command, this time specifying the collections-details parameter.

      /opt/couchbase/bin/cbstats -u Administrator -p password -b testBucket \
      localhost:11210 collections-details

      Statistics are displayed as follows:

      0x0:0x0:name:                     _default
      0x0:0xa:name:                     my_collection_in_default_scope
      0x8:0x8:name:                     my_collection_in_my_scope_1
      0x8:0x9:name:                     my_collection_in_my_scope_2
      manifest_uid:                     4
      vb_0:0x0:disk_size:               0
      vb_0:0x0:high_seqno:              0
      vb_0:0x0:items:                   0
      vb_0:0x0:ops_delete:              0
      vb_0:0x0:ops_get:                 0
      vb_0:0x0:ops_store:               0
      vb_0:0x0:persisted_high_seqno:    0
      vb_0:0x0:scope:                   0x0
      vb_0:0x0:start_seqno:             0
      vb_0:0x8:disk_size:               79
      vb_0:0x8:high_seqno:              2
      vb_0:0x8:items:                   0
      vb_0:0x8:ops_delete:              0
      vb_0:0x8:ops_get:                 0
      vb_0:0x8:ops_store:               0
      vb_0:0x8:persisted_high_seqno:    2
      vb_0:0x8:scope:                   0x8
      
       	.
      	.

      The output, which is presented here in truncated form, provides additional details on scopes, collections, and their content; including sequence numbers, manifest uids, 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:0x0:disk_size:            0
      vb_8:0x0:high_seqno:           0
      vb_8:0x0:items:                0
      vb_8:0x0:ops_delete:           0
      vb_8:0x0:ops_get:              0
      vb_8:0x0:ops_store:            0
      vb_8:0x0:persisted_high_seqno: 0
      vb_8:0x0:scope:                0x0
      vb_8:0x0:start_seqno:          0
      vb_8:0x8:disk_size:            79
      vb_8:0x8:high_seqno:           2
      vb_8:0x8:items:                0
      vb_8:0x8:ops_delete:           0
      vb_8:0x8:ops_get:              0
      vb_8:0x8:ops_store:            0
      vb_8:0x8:persisted_high_seqno: 2
      vb_8:0x8:scope:                0x8
      vb_8:0x8:start_seqno:          2
      vb_8:0x9:disk_size:            81
      vb_8:0x9:high_seqno:           3
      vb_8:0x9:items:                0
      vb_8:0x9:ops_delete:           0
      vb_8:0x9:ops_get:              0
      vb_8:0x9:ops_store:            0
      vb_8:0x9:persisted_high_seqno: 3
      vb_8:0x9:scope:                0x8
      vb_8:0x9:start_seqno:          3
      vb_8:0xa:disk_size:            77
      vb_8:0xa:high_seqno:           4
      vb_8:0xa:items:                0
      vb_8:0xa:ops_delete:           0
      vb_8:0xa:ops_get:              0
      vb_8:0xa:ops_store:            0
      vb_8:0xa:persisted_high_seqno: 4
      vb_8:0xa:scope:                0x0
      vb_8:0xa:start_seqno:          4
      vb_8:collections:              4
      vb_8:manifest:uid:             4
    10. 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 dropped

      Now, list collections in the scope:

      /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:

      Scope my_scope:
          - my_collection_in_my_scope_2

      The output indicates that the collection my_collection_in_my_scope_1 has now been dropped from my_scope.

    11. 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 dropped

      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.

    Manage Scopes and Collections with the REST API

    The following sequence of REST API commands demonstrates how to create, examine, and delete scopes and collections. Proceed as follows:

    At the command-line prompt, proceed as follows:

    1. Create a bucket, named testBucket, using the /pools/default/buckets REST method:

      curl -X POST -u Administrator:password \
      http://localhost:8091/pools/default/buckets \
      -d name=testBucket \
      -d ramQuotaMB=100

      For information on this REST call and its parameters, see Creating and Editing Buckets.

    2. Create a scope. This is a POST operation, using the /pools/default/buckets/<bucket>/collections endpoint, and specifying the -name parameter.

      curl -u Administrator:password -X POST \
      http://localhost:8091/pools/default/buckets/testBucket/collections \
      -d name=my_scope

      If successful, the command returns a uid for the action (this is principally for internal use, and need not be tracked by the user):

      {"uid":1}

      Now, examine the collections manifest for the specified bucket. This is a GET operation, using the same endpoint as the previous POST, with no parameter.

      curl -u Administrator:password -X GET \
      http://localhost:8091/pools/default/buckets/testBucket/collections

      This returns the following output:

      {"uid":"1","scopes":[{"name":"my_scope","uid":"8","collections":[]},{"name":"_default","uid":"0","collections":[{"name":"_default","uid":"0"}]}]}

      Formatted, this output is as follows:

      {
        "uid": "1",
        "scopes": [
          {
            "name": "my_scope",
            "uid": "8",
            "collections": []
          },
          {
            "name": "_default",
            "uid": "0",
            "collections": [
              {
                "name": "_default",
                "uid": "0"
              }
            ]
          }
        ]
      }

      This output shows that the bucket now contains two scopes, which are my_scope and _default. The _default scope contains a single collection, which is also named _default.

    3. Create two collections, within the created scope. This requires a POST operation, specifying the created scope as endpoint, and using the -name parameter to specify the new collection-name. For the first collection, enter the following command:

      curl -u Administrator:password -X POST \
      http://localhost:8091/pools/default/buckets/testBucket/collections/my_scope \
      -d name=my_collection_in_my_scope_1

      If successful, the operation returns a uid.

      {"uid":2}

      Create the second collection as follows:

      curl -u Administrator:password -X POST \
      http://localhost:8091/pools/default/buckets/testBucket/collections/my_scope \
      -d name=my_collection_in_my_scope_2

      Again, success returns a uid:

      {"uid":3}

      Now, re-examine the collections manifest for the bucket.

      curl -u Administrator:password -X GET \
      http://localhost:8091/pools/default/buckets/testBucket/collections

      The unformatted output is as follows:

      {"uid":"3","scopes":[{"name":"my_scope","uid":"8","collections":[{"name":"my_collection_in_my_scope_2","uid":"9"},{"name":"my_collection_in_my_scope_1","uid":"8"}]},{"name":"_default","uid":"0","collections":[{"name":"_default","uid":"0"}]}]}

      When formatted, the output takes the following appearance:

      {
        "uid": "3",
        "scopes": [
          {
            "name": "my_scope",
            "uid": "8",
            "collections": [
              {
                "name": "my_collection_in_my_scope_2",
                "uid": "9"
              },
              {
                "name": "my_collection_in_my_scope_1",
                "uid": "8"
              }
            ]
          },
          {
            "name": "_default",
            "uid": "0",
            "collections": [
              {
                "name": "_default",
                "uid": "0"
              }
            ]
          }
        ]
      }

      This indicates that the collections my_collection_in_my_scope_1 and my_collection_in_my_scope_2 have been successfully created in my_scope.

    4. Create a collection in the default scope. This is a POST operation, specifying the _default scope as endpoint, and the -name parameter to specify the new collection-name.

      curl -u Administrator:password -X POST \
      http://localhost:8091/pools/default/buckets/testBucket/collections/_default \
      -d name=my_collection_in_default_scope

      A uid is returned:

      {"uid":4}

      Now, re-examine the collections manifest for the bucket.

      curl -u Administrator:password -X GET \
      http://localhost:8091/pools/default/buckets/testBucket/collections

      This returns the following:

      {"uid":"4","scopes":[{"name":"my_scope","uid":"8","collections":[{"name":"my_collection_in_my_scope_2","uid":"9"},{"name":"my_collection_in_my_scope_1","uid":"8"}]},{"name":"_default","uid":"0","collections":[{"name":"my_collection_in_default_scope","uid":"a"},{"name":"_default","uid":"0"}]}]}

      When formatted the output is as follows:

      {
        "uid": "4",
        "scopes": [
          {
            "name": "my_scope",
            "uid": "8",
            "collections": [
              {
                "name": "my_collection_in_my_scope_2",
                "uid": "9"
              },
              {
                "name": "my_collection_in_my_scope_1",
                "uid": "8"
              }
            ]
          },
          {
            "name": "_default",
            "uid": "0",
            "collections": [
              {
                "name": "my_collection_in_default_scope",
                "uid": "a"
              },
              {
                "name": "_default",
                "uid": "0"
              }
            ]
          }
        ]
      }

      This indicates that the collection my_collection_in_default_scope has been successfully created in the _default scope, and so appears alongside the _default collection.

    5. Drop a collection from the created scope. This requires a DELETE operation, and the endpoint that specifies the collection that is to be dropped.

      curl -u Administrator:password -X DELETE \
      http://localhost:8091/pools/default/buckets/testBucket/collections/\
      my_scope/my_collection_in_my_scope_1

      This returns a uid:

      {"uid":5}

      Now, re-examine the collections manifest for the bucket.

      curl -u Administrator:password -X GET \
      http://localhost:8091/pools/default/buckets/testBucket/collections

      The output (here formatted) indicates that the collection my_collection_in_my_scope_1 has successfully been dropped from my_scope:

      {
        "uid": "5",
        "scopes": [
          {
            "name": "my_scope",
            "uid": "8",
            "collections": [
              {
                "name": "my_collection_in_my_scope_2",
                "uid": "9"
              }
            ]
          },
          {
            "name": "_default",
            "uid": "0",
            "collections": [
              {
                "name": "my_collection_in_default_scope",
                "uid": "a"
              },
              {
                "name": "_default",
                "uid": "0"
              }
            ]
          }
        ]
      }
    6. Drop the created scope, and examine the manifest.

      curl -u Administrator:password -X DELETE \
      http://localhost:8091/pools/default/buckets/testBucket/collections/my_scope

      This returns a uid:

      {"uid":6}

      Examine the manifest:

      curl -u Administrator:password -X GET \
      http://localhost:8091/pools/default/buckets/testBucket/collections

      The output (here formatted) is as follows:

      {
        "uid": "6",
        "scopes": [
          {
            "name": "_default",
            "uid": "0",
            "collections": [
              {
                "name": "my_collection_in_default_scope",
                "uid": "a"
              },
              {
                "name": "_default",
                "uid": "0"
              }
            ]
          }
        ]
      }

      This indicates that my_scope has successfully been dropped; and with it, the collection my_collection_in_my_scope_2.

    This concludes the sequence of commands.

    See Also

    An overview of scopes and collections is provided in Scopes and Collections. A reference page for each of the available REST methods is provided at Scopes and Collections API. See also the CLI reference page for the collection-manage command. (Note that the REST and CLI pages include information on specifying an expiration time for collections.)

    For information on assigning roles that permit access to scopes and collections, see Manage Users, Groups, and Roles.