Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Getting System Information

  • concept
March 23, 2025
+ 12
SQL++ has a system catalog that stores metadata about a database. The system catalog is a namespace called system.

There is a keyspace for each type of artifact. The keyspace names are plural in order to avoid conflicting with SQL++ keywords.

Logical Hierarchy

SQL++ has the following artifacts:

Datastores

Datastores are similar to sites. A datastore is a database deployment, for example, a server cluster, cloud service, or mobile installation. It is analogous to a relation database instance.

Namespaces

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. Currently, only the default and system namespaces are available.

Buckets

A bucket is the fundamental space for storing data in Couchbase Server. Each bucket contains at least one scope by default, and you can create more scopes as required. It is analogous to a relational database table space or file group.

Scopes

A scope is a set of one or more collections. Each scope contains at least one collection by default, and you can create more collections as required. It is analogous to a group of relational database tables.

Collections

A collection 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.

Keyspaces

Keyspaces map to collections in Couchbase Server. A keyspace may be referred to using a full keyspace reference. For example, default:`travel-sample`.inventory.airline refers to the airline collection in the inventory scope in the travel-sample bucket. A keyspace may also be referred to using a partial keyspace reference, comprising just the collection name. In this case, the namespace, bucket, and scope must be implied by the current query context.

For compatibility with legacy versions of Couchbase Server, the name of the scope and collection may be omitted when referring to the default collection in the default scope within a bucket. So for example, we may refer to the travel-sample keyspace, meaning the default collection in the default scope in the travel-sample bucket.

The term is also used to refer to any of the catalogs in the system namespace.

Indexes

An index on a keyspace. It is analogous to a relational database index. Types of indexes include b-tree (ForestDB or MOI) and view indexes.

Dual

The dual keyspace has been added for evaluating constant expressions. It contains a single entry with no attributes.

Querying Datastores

You can query datastores using the system:datastores keyspace as follows:

sql++
Copy
SELECT * FROM system:datastores

The query returns the following attributes:

id

(string) ID of the datastore
url

(string) URL of the datastore instance

Querying Namespaces

You can query namespaces using the system:namespaces keyspace as follows:

sql++
Copy
SELECT * FROM system:namespaces

The query returns the following attributes:

id

(string) ID of the namespace
name

(string) Name of the namespace
datastore_id

(string) ID of the datastore to which the namespace belongs

Querying Buckets

You can query buckets using the system:buckets keyspace as follows:

sql++
Copy
SELECT * FROM system:buckets

The query returns the following attributes:

datastore_id

(string) ID of the datastore to which the bucket belongs
name

(string) Name of the bucket
namespace

(string) Namespace to which the bucket belongs
namespace_id

(string) ID of the namespace to which the bucket belongs
path

(string) Path of the bucket

Querying Scopes

You can query scopes using the system:scopes keyspace as follows:

sql++
Copy
SELECT * FROM system:scopes

The query returns the following attributes:

bucket

(string) Bucket to which the scope belongs
datastore_id

(string) ID of the datastore to which the scope belongs
name

(string) Name of the scope
namespace

(string) Namespace to which the scope belongs
namespace_id

(string) ID of the namespace to which the scope belongs
path

(string) Path of the scope
Querying system:scopes only returns named scopes — that is, non-default scopes. To return all scopes, including the default scopes, you can query system:all_scopes.

Querying Collections

You can query collections using the system:keyspaces keyspace as follows:

sql++
Copy
SELECT * FROM system:keyspaces

For the default collection in the default scope, the query returns the following attributes:

datastore_id

(string) ID of the datastore to which the keyspace belongs
id

(string) ID of the bucket to which the keyspace belongs
name

(string) Bucket to which the keyspace belongs
namespace

(string) Namespace to which the keyspace belongs
namespace_id

(string) ID of the namespace to which the keyspace belongs
path

(string) Path of the keyspace

For a named, non-default collection, the query returns the following attributes:

bucket

(string) Bucket to which the keyspace belongs
datastore_id

(string) ID of the datastore to which the keyspace belongs
id

(string) ID of the keyspace
name

(string) Name of the keyspace
namespace

(string) Namespace to which the keyspace belongs
namespace_id

(string) ID of the namespace to which the keyspace belongs
path

(string) Path of the keyspace
scope

(string) Scope to which the keyspace belongs
Querying system:keyspaces only returns non-system keyspaces. To return all keyspaces, including the system keyspaces, you can query system:all_keyspaces.

Querying Indexes

You can query indexes using the system:indexes keyspace as follows:

sql++
Copy
SELECT * FROM system:indexes

For an index on the default collection in the default scope, the query returns the following attributes:

condition

(string) Index filter, if present
datastore_id

(string) ID of the datastore to which the index belongs
id

(string) ID of the index
index_key

(array of strings) List of index keys
is_primary

(boolean) True if the index is a primary index
keyspace_id

(string) ID of the bucket to which the index belongs
name

(string) Name of the index
namespace_id

(string) ID of the namespace to which the index belongs
state

(string) State of index, for example, online
using

(string) Type of index, for example, gsi

For an index on a named, non-default collection, the query returns the following attributes:

bucket_id

(string) ID of the bucket to which the index belongs
condition

(string) Index filter, if present
datastore_id

(string) ID of the datastore to which the index belongs
id

(string) ID of the index
index_key

(array of strings) List of index keys
is_primary

(boolean) True if the index is a primary index
keyspace_id

(string) ID of the keyspace to which the index belongs
name

(string) Name of the index
namespace_id

(string) ID of the namespace to which the index belongs
state

(string) State of index, for example, online
using

(string) Type of index, for example, gsi
Querying system:indexes only returns indexes on non-system keyspaces. To return all indexes, including indexes on system keyspaces, you can query system:all_indexes.

Querying Dual

You can use dual to evaluate constant expressions.

sql++
Copy
SELECT 2+5 FROM system:dual

The query returns the result of the expression, 7 in this case.