A newer version of this documentation is available.

View Latest

Getting System Information

  • concept
    +
    N1QL 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 N1QL keywords.

    Logical Hierarchy

    N1QL 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 in full using a keyspace path. For example, default:`travel-sample`.inventory.airline refers to the airline collection in the inventory scope in the travel-sample bucket. The keyspace may also be referred to briefly using just the collection name, for example when the namespace, bucket, and scope are 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.

    Query Context

    The query context specifies the the namespace, bucket, and scope used to resolve partial keyspace references.

    When the query context is set, you can refer to a collection using just the collection name, without having to enter the keyspace path. When the query context is not set, it defaults to the default namespace, with no bucket, scope, or collection.

    • To set the query context in the Query Workbench, use the the query context drop-down menu in the Query Editor.

    • To set the query context from the cbq shell or the REST API, use the query_context request-level parameter.

    Tenant separation

    By using queries with partial keyspace references, which are resolved using the query context, a database application can be switched from one scope to another simply by changing the query context. This can be used to support the separation of tenant data in a multi-tenancy environment.

    Querying Datastores

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

    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:

    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:

    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:

    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:

    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:

    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.

    SELECT 2+5 FROM system:dual

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