> For the complete documentation index, see [llms.txt](https://docs.apica.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apica.io/platform-docs/irondb/administration/compacting-numeric-rollups.md).

# Compacting Numeric Rollups

Although numeric shards can be configured with [retention windows](/platform-docs/irondb/getting-started/configuration.md#nntbs), this only removes entire shards once they are past the window. In cases where one has [fully deleted](/platform-docs/irondb/api/data-deletion.md#deleting-all-data-for-a-metric-or-a-set-of-metrics) all data for a significant number of metrics, the storage space they occupy in rollups may be recovered by performing a compaction of one or more NNTBS shards using a map of active IDs from the [surrogate database](/platform-docs/irondb/getting-started/configuration.md#surrogate_database).

Compaction is performed by running the `shard_compactor` tool. It has two required arguments:

* `-d <nntbs_dir>` - The path where NNTBS shards are stored. This is typically\
  found under `/irondb/nntbs`, or `/snowth/nntbs` on deployments hosted by\
  Circonus. The directory name matches the node's cluster UUID.
* `-s <shard>` - The name of a shard to compact. Shards are named for the rollup period and the start and end timestamps that they represent. This option may be specified multiple times to compact more than one shard. Shards will be compacted serially.

Run `/opt/circonus/bin/shard_compactor --help` for full usage information. The tool must be run as the unprivileged user that IRONdb runs as, typically `nobody`.

This is an online operation (the IRONdb service must be running). Each shard will be put into an "offline" mode while it is being compacted. Requests for data within the shard will be redirected to other cluster nodes during the operation.

## Caveats

* Compaction should only be performed on shards that are no longer getting new data. In other words, shards that are older than the raw database's `min_delete_age` plus `delete_after_quiescent_age`.
* A surrogate ID map is only valid for the host from which it was obtained, and should *never* be used for compacting shards on a different host.
* Care should be taken to avoid compacting the same shard at the same time on multiple cluster nodes. Doing so may jeopardize the availability of metric data if too many of one shard are offline at once. Since compaction is a background maintenance task, it is preferable to run it on one node at a time.

## Example

Given an IRONdb node whose cluster ID is `84d2979a-f233-47d3-9a15-d4f8885c9b7c`:

```
$ sudo -u nobody /opt/circonus/bin/shard_compactor \
    -d /irondb/nntbs/84d2979a-f233-47d3-9a15-d4f8885c9b7c \
    -s 60_1551432000-1552041600 \
    -s 60_1552041600-1552651200
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.apica.io/platform-docs/irondb/administration/compacting-numeric-rollups.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.