Namespaces, keyspaces, buckets: great deal of confusion

I’m a newbie in Couchbase. And while trying to understand the core concepts I was confused with what namespaces, keyspaces and backets are.

In the official Couchbase documentation I found the following statements which in my opinion contradict each other:

  • “Buckets and vBuckets”

A bucket is a logical collection of related documents in Couchbase, just like a database in RDBMS. It is a unique key space.

  • “CREATE INDEX statement”


An identifier that refers to the bucket name. Specifies the bucket as the source for which the index needs to be created. You can add an optional namespace name to the keyspace name in this way:

namespace-name : keyspace-name

For example, main:customer indicates the customer keyspace in the main namespace. If the namespace name is omitted, the default namespace in the current session is used.

  • “Getting system information”

Namespaces are similar to pools. A namespace is a unit of authorization, resource allocation, and tenancy. It is analogous to a relational database or schema.

Keyspaces are similar to buckets. A keyspace is a set of documents that may vary in structure. It is a unit of authorization and resource allocation. It is analogous to a relational database table.

So what is similar to RDBMS databases, namespaces or keyspaces?
Keyspaces seem to be buckets and I’m able to create a few of them. But what about namespaces, how do I create and use them in a way it’s shown on the “CREATE INDEX statement” page?

Hi @dmitryb,

Good questions. The short answer is that Couchbase has not had a container model that maps to RDBMS or other NoSQL databases (e.g. MongoDB). We are fixing that by adding collections in a future release. (The current problem is that documents are stored directly in a bucket, so it becomes the unit of querying and indexing.)

Couchbase 4.x:
keyspace = bucket
namepsace = pool

Couchbase future:
keyspace = collection
namespace = pool + bucket

I would suggest that you not worry about creating namespaces; but if you really want to, you can look up how to create pools (not available via N1QL).

1 Like

Thanks a lot for the answer!
I don’t really need to create pools and wouldn’t have asked the question if the documentation wasn’t so confusing operating with “bucket”, “namespace”, “keyspace” and “pool” terms when in fact there are practically only buckets, at least for now.

Also found this post: which explained the pools idea a bit.