Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.narrative.io/llms.txt

Use this file to discover all available pages before exploring further.

Archiving a compute pool removes it from selection without permanently deleting it. The archive flow behaves differently on Snowflake and AWS data planes, and in-flight jobs that still reference the pool are failed by the operator on their next iteration. This guide walks through the order in which to clear references so the archive succeeds and your jobs report meaningful errors.

​
Prerequisites

  • A Narrative API token with Compute Pools Read and Write permissions (manage API keys)
  • The computePoolId of the pool you want to archive
  • For AWS data planes: knowledge of any datasets that pin this pool as a default

​
When archive rejects

On AWS data planes, the API rejects the archive when the pool is still:
  • The data plane default — used as the level-3 fallback when a job does not specify a compute pool
  • A dataset default — pinned to one or more datasets as their default compute pool
When this happens, the API returns a CannotArchiveDefault error describing every reference that would dangle. Clear those references first, then retry. On Snowflake data planes, both reference paths are reconciled automatically: the platform re-elects another active pool as the new data plane default (or clears it if none remain) and clears the dataset default on every affected dataset before archiving. You can skip the manual steps below and call the archive endpoint directly.
Snowflake users frequently mutate their warehouse list outside the platform. The Snowflake archive flow is permissive so the platform can track reality when a backing warehouse disappears. See Compute Pools › Archiving compute pools for the rationale.

​
Archive on an AWS data plane

1

Reassign or clear the data plane default

If the compute pool you want to archive is the data plane default, update the data plane to point at a different active compute pool, or clear the default entirely. After this step, jobs that do not specify a computePoolId either resolve to the new default or fail with an actionable error at job creation.
2

Clear the pool from every dataset that pins it

Update each affected dataset’s computePoolConfig.defaultComputePoolId to a different pool or to null. Datasets whose default is cleared fall through to the data plane default on their next job.
Dataset defaults are a user-specific choice. The platform does not auto-pick a replacement on AWS data planes — you decide whether to repoint each dataset or let it fall through.
3

Call the archive endpoint

Send a DELETE request to /compute-pools/{id}. The pool’s status changes to archived and it stops appearing in list responses.
curl -X DELETE \
  -H "Authorization: Bearer $NARRATIVE_API_TOKEN" \
  https://api.narrative.io/compute-pools/<id>
4

Decide what to do with in-flight jobs

The data plane operator fails any job whose compute pool resolves to a non-active status on its next polling iteration. If you do not want in-flight jobs to fail, wait until they reach a terminal state before archiving, or resubmit them against a different active pool first.

​
What happens to in-flight jobs

After archive, the operator treats the pool as unresolvable for every Pending, Running, and PendingCancellation job that referenced it. The job is reported as failed with a message similar to: 
compute pool '<id>' could not be resolved (it may have been archived or does not exist).
Resubmit the job with an active compute pool.
Jobs in PendingCancellation are failed rather than reported as cancelled. The missing pool is the actionable signal users need to see — a successful cancellation report would hide the underlying cause. From the user’s perspective the job is terminal either way, so failing it is the safe and informative choice.

​
Verifying the archive

The pool’s record stays in the database, so GET /compute-pools/{id} still returns it with status: archived. The pool is filtered out of GET /compute-pools list responses by default. Job creation requests that try to resolve to an archived pool fail validation at the API layer; existing jobs that resolved to it at submission time fail at runtime as described above.

​
Related content

Compute Pools

How compute pools work and why archive behavior diverges by provider

Data Planes

Where data lives and how the operator processes jobs

Migrate to Compute Pools

Transition from a single Snowflake warehouse to compute pools

API keys

Manage API tokens with the permissions needed to archive pools