> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-poc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# detach_tablespace()

> Detach a tablespace from a hypertable

export const CHUNK_CAP = 'Chunk';

export const CHUNK = 'chunk';

export const HYPERTABLE_CAP = 'Hypertable';

export const HYPERTABLE = 'hypertable';

<Icon icon="tag" iconType="duotone" /> Since [0.7.0][tsdb-0.7.0]

Detach a tablespace from one or more {HYPERTABLE}s. This *only* means
that *new* {CHUNK}s are not placed on the detached tablespace. This
is useful, for instance, when a tablespace is running low on disk
space and one would like to prevent new {CHUNK}s from being created in
the tablespace. The detached tablespace itself and any existing {CHUNK}s
with data on it remains unchanged and continue to work as
before, including being available for queries. Note that newly
inserted data rows may still be inserted into an existing {CHUNK} on the
detached tablespace since existing data is not cleared from a detached
tablespace. A detached tablespace can be reattached if desired to once
again be considered for {CHUNK} placement.

## Samples

Detach the tablespace `disk1` from the {HYPERTABLE} `conditions`:

```sql theme={"dark"}
SELECT detach_tablespace('disk1', 'conditions');
SELECT detach_tablespace('disk2', 'conditions', if_attached => true);
```

Detach the tablespace `disk1` from all {HYPERTABLE}s that the current
user has permissions for:

```sql theme={"dark"}
SELECT detach_tablespace('disk1');
```

## Arguments

The syntax is:

```sql theme={"dark"}
SELECT detach_tablespace(
    tablespace = '<tablespace_name>',
    hypertable = '<hypertable_name>',
    if_attached = true | false
);
```

| Name          | Type     | Default | Required | Description                                                                                                              |
| ------------- | -------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `tablespace`  | TEXT     | -       | ✔        | Tablespace to detach.                                                                                                    |
| `hypertable`  | REGCLASS | -       | ✖        | Hypertable to detach the tablespace from.                                                                                |
| `if_attached` | BOOLEAN  | `FALSE` | ✖        | Set to true to avoid throwing an error if the tablespace is not attached to the given table. A notice is issued instead. |

When giving only the tablespace name as argument, the given tablespace
is detached from all {HYPERTABLE}s that the current role has the
appropriate permissions for. Therefore, without proper permissions,
the tablespace may still receive new {CHUNK}s after this command
is issued.

When specifying a specific {HYPERTABLE}, the tablespace is only
detached from the given {HYPERTABLE} and thus may remain attached to
other {HYPERTABLE}s.

## Returns

| Name               | Type    | Description                                                         |
| ------------------ | ------- | ------------------------------------------------------------------- |
| detach\_tablespace | INTEGER | The number of {HYPERTABLE}s from which the tablespace was detached. |

When called with both `tablespace` and `hypertable` arguments, returns 1 if the tablespace was successfully detached from the specified {HYPERTABLE}. When called with only the `tablespace` argument, returns the total number of {HYPERTABLE}s from which the tablespace was detached.

[tsdb-0.7.0]: https://github.com/timescale/timescaledb/releases/tag/0.7.0