> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Work with Namespaces in StreamNative Cloud

<Note title="Note">
  This document introduces the instructions for working with namespaces on StreamNative Console. The details may vary depending on the specific product and version number that you use.
</Note>

A **namespace** is a logical grouping of topics. After creating a tenant, you can create one or more namespaces for the tenant.

## Namespace Overview

A namespace represents an administrative unit within a tenant. The configuration policies set on a namespace apply to all the topics created in that namespace. You can create multiple namespaces for a tenant using the StreamNative Cloud Console, REST API or the pulsar-admin CLI tool.

### Permissions

In Pulsar, permissions are managed at the namespace level (within tenants and clusters). You can grant permissions to specific users for lists of operations such as `produce` and `consume`. In addition, you can revoke permissions from specific users, which means that those users cannot access the specified namespace.

### Backlog quotas

Backlogs are sets of unacknowledged messages for a topic that have been stored by bookies. Pulsar stores all unacknowledged messages in backlogs until they are processed and acknowledged.
You can use the backlog quotas to control the allowable size of backlogs at the namespace level. You can set the following items for a backlog quota:

* an allowable size threshold for each topic in the namespace
* a retention policy that determines the action the broker takes if the threshold is exceeded.

The following table lists available retention policies.

| Policy                      | Action                                                            |
| --------------------------- | ----------------------------------------------------------------- |
| `producer_request_hold`     | The broker holds but does not persist producers' request payload. |
| `producer_exception`        | The broker disconnects from the client by throwing an exception.  |
| `consumer_backlog_eviction` | The broker begins discarding backlog messages.                    |

### Bundles

For assignment, a namespace is sharded into a list of bundles, with each bundle comprising a portion of the overall hash range of the namespace. A bundle is a virtual group of topics that belong to the same namespace. A namespace bundle is defined as a range between two 32-bit hashes, such as 0x00000000 and 0xffffffff. By default, four bundles are supported for each namespace.

Since the load for topics in a bundle might change over time, one bundle can be split into two bundles by brokers. Then, the new smaller bundle is reassigned to different brokers. By default, the newly split bundles are immediately offloaded to other brokers to facilitate the traffic distribution.

### Dispatch rate

Dispatch rate refers to the number of messages dispatched per second by topics for a namespace. Dispatch rate can be restricted by the number of messages per second (`msg-dispatch-rate`) or by the number of bytes of messages per second (`byte-dispatch-rate`). Dispatch rate is in seconds and it can be configured with `dispatch-rate-period`. By default, `msg-dispatch-rate` and `byte-dispatch-rate` are both set to -1, which indicates that throttling is disabled.

## Create a namespace

<Tabs>
  <Tab title="StreamNative Console">
    To create a namespace, follow these steps.

    1. On the left navigation pane, under **Tenants/Namespaces**, select the name of the tenant you want to associate with the new namespace, and click **New Namespace**.

    2. On the Namespace page, click **New Namespace**.

    3. Enter a name for the namespace and then click **Confirm**. A namespace name can contain any combination of lowercase letters (a-z), numbers (0-9), and hyphens (-).
  </Tab>
</Tabs>

## Manage a namespace

<Tabs>
  <Tab title="StreamNative Console">
    This section describes how to manage namespaces through the StreamNative Console.

    1. On the left navigation pane, under **Tenants/Namespaces**, select the name of the Tenant/Namespace you want to manage.

    2. Select the **OVERVIEW** tab to check statistics about the namespace, as well as unload and split bundles. The following table lists statistics about the namespace.

       | Item           | Description                              |
       | -------------- | ---------------------------------------- |
       | In Rate        | The ingress rate of the namespace.       |
       | Out Rate       | The egress rate of the namespace.        |
       | In Throughput  | The ingress throughput of the namespace. |
       | Out Throughput | The egress throughput of the namespace.  |

    3. Select the **TOPICS** tab to check the number of topics included in the namespace and statistics about topics. In addition, you can update specific topics. For details about how to update topics, see [edit topics](/cloud/manage-data-streams/topic#create-a-topic).

    4. Select the **POLICIES** tab to configure related policies for the namespace. For details, see [configure policies for a namespace](#configure-policies-for-a-namespace).
  </Tab>
</Tabs>

### Unload bundles for a namespace

<Tabs>
  <Tab title="StreamNative Console">
    For an assignment, a namespace is sharded into a list of bundles, with each bundle comprising a portion of the overall hash range of the namespace. By default, four bundles are supported for each namespace.

    To unload bundles for a namespace, follow these steps.

    1. On the left navigation pane, under **Tenants/Namespaces**, select the name of the Tenant/Namespace you need to edit, and click **New Namespace**.

    2. Click **Edit** in the **Actions** column.

    3. Select the **OVERVIEW** tab.

           <img src="https://mintcdn.com/streamnative/URPLmIWqdNJY7HIj/media/unload-bundles.png?fit=max&auto=format&n=URPLmIWqdNJY7HIj&q=85&s=cfa889518614e7f5ebdf8642a759a9a8" alt="image of namespace overview" width="1600" height="954" data-path="media/unload-bundles.png" />

    4. In the **Bundle** section, select the target cluster from the **Cluster** drop-down list, and then do one of the following:

       * Click **Unload All** to unload all bundles for the namespaces in the cluster.

       * Click **Unload** in the Operation column to unload a specific bundle for the namespace.
  </Tab>
</Tabs>

### Split bundles for a namespace

<Tabs>
  <Tab title="StreamNative Console">
    Because the load for topics in a bundle might change over time, one bundle can be split in two bundles by brokers. Then, the new smaller bundles are reassigned to different brokers. By default, the newly split bundles are immediately offloaded to other brokers to facilitate the traffic distribution.

    To split bundles for a namespace, follow these steps.

    1. From the left navigation pane, click **Namespaces**.

    2. Click **Edit** icon (it looks like a pencil.) in the **Action** column or click the link of the namespace name.

    3. Select **OVERVIEW** tab.

           <img src="https://mintcdn.com/streamnative/URPLmIWqdNJY7HIj/media/split-bundles.png?fit=max&auto=format&n=URPLmIWqdNJY7HIj&q=85&s=6ea0e6a3c8299de37e446af8db87517c" alt="screenshot for splitting bundles" width="1600" height="939" data-path="media/split-bundles.png" />

    4. Click **Split**.
  </Tab>
</Tabs>

### Clear namespace backlog

<Tabs>
  <Tab title="StreamNative Console">
    To clear backlog for bundles of a namespace, follow these steps.

    1. On the left navigation pane, under **ADMIN**, click **Tenants/Namespaces**.

    2. Select the name of the tenant that is associated with the target namespace.

    3. Click the name of the namespace that you want to clear backlog for.

    4. In the **Bundle** section of the **OVERVIEW** tab, click **Clean All Backlog** to clear the backlog for all the topics of the namespace.
  </Tab>
</Tabs>

### Configure policies for a namespace

<Tabs>
  <Tab title="StreamNative Console">
    To configure policies for a namespace, follow these steps.

    1. From the left navigation pane, click **Namespaces**.

    2. Click **Edit** in the **Action** column or click the link of the namespace name.

    3. Select the **Policies** tab.

           <img src="https://mintcdn.com/streamnative/tIZ04bis3aV5g7je/media/namespace-policy.png?fit=max&auto=format&n=tIZ04bis3aV5g7je&q=85&s=8e606e5140a2b660e4dc7972b18b7bed" alt="screenshot of namespace policy" width="1660" height="1478" data-path="media/namespace-policy.png" />

    4. Configure policies for the namespace, as listed in the following table.

       | Item     | Description                                                                                                                                                                                                                                                            |
       | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
       | Clusters | Select a replication cluster. Messages of the topics in this namespace are asynchronically replicated between the configured replication clusters. Currently, this item is set to the cluster you created because there is only one cluster available for an instance. |

    <br />

    <br />

    <br />

    <br />

    <br />

    <br />

    <br />

    <br />
  </Tab>
</Tabs>

## Delete a namespace

<Note title="Note">
  You cannot delete a namespace if there are resources associated with the namespace.
</Note>

<Tabs>
  <Tab title="StreamNative Console">
    To delete a namespace, follow these steps.

    1. On the left navigation pane, in the **Admin** section, click **Namespaces**.

    2. In the **Warning** section at the bottom of the Namespace Policy page, click **Delete Namespace**. A dialog box displays asking, *Are you sure you want to delete this?*

    3. Enter the namespace name and then click **Confirm**.
  </Tab>
</Tabs>

## Next step

* [Work with topics](/cloud/manage-data-streams/topic)

## Related content

* Learn more information about managing namespaces using Pulsar Admin API, see [Managing Namespaces](https://pulsar.apache.org/docs/admin-api-namespaces/).