> ## 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.

# Warm a namespace

> Warming loads a namespace into Brussle's cache before you query it, so the queries that follow are not cold. It is free and best effort.

Warming loads a namespace into Brussle's cache before you query it. The queries that follow are then not cold.

For example, a user of your product signs in. Their tenant's namespace was idle since yesterday. You warm the namespace when the user signs in. By the time the user opens a page that queries Brussle, the namespace is loaded.

## 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).

## Warm a namespace

Post to the namespace's `warm` route:

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

In the SDKs, call `ns.warm()`. The response is `202 Accepted` with no body. Brussle loads the namespace in the background.

A read-only key can warm a namespace. Warming changes nothing. The route accepts an `Idempotency-Key` header, so a retried call warms the namespace once.

In the dashboard, open the namespace and press **Warm** at the top of the page. Developers, admins and owners can press it.

## What you can rely on

* Warming is free. It adds nothing to your bill.
* Warming is best effort. Brussle loads the namespace when it can. The call returns before the namespace is loaded, and the response does not say when the namespace is loaded. Do not wait for it in your code.
* Warming changes no answer and no document.
* A warmed namespace stays in the cache until idle time removes it. Warm a namespace shortly before you query it, not long before.
* A namespace that must never go cold needs [pinning](/guides/pin-a-namespace), not warming. Pinning has a price.

## When to warm

Warm a namespace when you know that queries are about to start. Good moments are a user's sign-in, the start of a job that queries one tenant, and after you [pin](/guides/pin-a-namespace) a namespace, because pinning does not load it.


## Related topics

- [Multi-tenant platforms](/guides/multi-tenant-platforms.md)
- [Warm the namespace's caches](/api-reference/namespaces/warm-the-namespaces-caches.md)
- [Pin a namespace](/guides/pin-a-namespace.md)
- [Namespaces](/concepts/namespaces.md)
- [Tradeoffs](/tradeoffs.md)


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