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

# Pin a namespace

> A pinned namespace stays in cache after idle time, so its queries do not go cold. Pinning is a namespace setting with a price per GiB-month.

A pinned namespace stays in Brussle's cache after Brussle loads it. Idle time then does not make its queries slow.

For example, a tenant's namespace gets a query once a day. Without pinning, the first query of each day is a cold query. With pinning, that query is as fast as the queries that follow it.

## Cold queries

Brussle keeps the namespaces that you query in a cache. A namespace that gets no queries for some time falls out of the cache. The next query must load the namespace first. We call this a cold query. A cold query takes some hundreds of milliseconds. See the [latency targets](/tradeoffs#speed-and-limits).

## Pin a namespace

Set `pinned` to `true` in the namespace's settings:

```http theme={"theme":{"light":"css-variables","dark":"css-variables"}}
PATCH /namespaces/acme%2Fprod%2Ftenant_123
{"pinned": true}
```

In the SDKs, call `ns.update({ pinned: true })` (TypeScript) or `ns.update(pinned=True)` (Python). The response is the namespace with its new settings. `GET /namespaces/{ns}` and `ns.metadata()` also show `pinned`.

In the dashboard, open the namespace and use the **Pinned** switch at the top of the page. Owners and admins can change it.

## What you can rely on

* After Brussle loads a pinned namespace, the namespace stays in the cache. Idle time does not remove it.
* The first query after you pin the namespace can still be cold. Pinning does not load the namespace. [Warm](/guides/warm-a-namespace) the namespace after you pin it.
* A query after Brussle restarts a node can be cold. Warm the namespace again if you can.
* Pinning changes no answer and no document. It changes only how fast queries are after idle time.

## Unpin a namespace

Set `pinned` to `false`. The namespace then leaves the cache when Brussle needs the room, like any other namespace. Brussle stops to bill the namespace as pinned at its next hourly measurement.

## Price

Brussle bills a pinned namespace at \$0.50 per GiB-month, on the `pinned_bytes_hours` line, on top of its storage. Brussle measures the namespace's size each hour. See [pricing](/pricing#usage).

For example, a pinned namespace of 2 GiB costs \$1.00 a month to pin, plus its storage.

## When to pin

Pin a namespace when a slow first query is not acceptable, and the namespace is often idle. A namespace that gets queries all day stays in the cache without pinning. For a namespace that is idle until a known moment, such as a session that starts when a user signs in, [warming](/guides/warm-a-namespace) is free and is often enough.


## Related topics

- [Multi-tenant platforms](/guides/multi-tenant-platforms.md)
- [Warm a namespace](/guides/warm-a-namespace.md)
- [Namespaces](/concepts/namespaces.md)
- [Change budget, pinning and default engine](/api-reference/namespaces/change-budget-pinning-and-default-engine.md)
- [Writing a context recipe](/guides/context-recipes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.