---
title: "Replace a dataset table promotion policy"
method: PUT
path: "/v1/datasets/{id}/tables/{tableKey}/promotion"
tags: ["Datasets"]
---

# Replace a dataset table promotion policy

`PUT /v1/datasets/{id}/tables/{tableKey}/promotion`

## Request

- Base URL: `https://docs.grepr.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.grepr.ai/v1/datasets/{id}/tables/{tableKey}/promotion`
- Auth: one of:
  - API key in header `GREPR-API-KEY`
  - OpenID Connect (`https://grepr-prod.us.auth0.com/.well-known/openid-configuration`)

Validates and stores the complete promotion policy on the table. Newly included tag columns, and the columns of exact attribute includes the attribute cap has room for, are added synchronously before the request returns, in the same commit as the policy. Send back the revision the policy was read at to be refused rather than overwrite a change made since; omit it to replace whatever is stored.

## Path parameters

- `id` string, required
- `tableKey` string, required

## Request body

- PromotionPolicy
  - `attributes` PromotionPolicyAttributes, required
    - `cap` integer, required
    - `exclude` PromotionPolicyAttributeExclude[]
      - `path` string, required
      - `prefix` boolean
      - `scheduledRemovalAt` string, date-time: When the columns this entry excludes are removed from the table, assigned by the server. Taking the entry off the exclude list before then keeps them.
    - `excludeAllByDefault` boolean: Whether every path no include covers is excluded. Writers stop filling the existing columns no include covers, and they are removed from the table at excludeAllScheduledRemovalAt.
    - `excludeAllScheduledRemovalAt` string, date-time: When the columns excludeAllByDefault excludes are removed from the table, assigned by the server. Turning excludeAllByDefault off before then keeps them.
    - `include` PromotionPolicyAttributeInclude[]
      - `numeric` boolean: Whether the path gets a numeric index column when the policy is stored, without waiting for a number. Exact entries only: refused when prefix is true.
      - `path` string, required
      - `prefix` boolean
  - `columnRemovalDelay` string, ISO-8601: How long after a path or key is excluded its index columns are removed from the table, as an ISO-8601 duration. Defaults to 6 hours when absent.
  - `revision` integer: Which store of the table's policy this is, assigned by the server: 0 when the table has none. Echo it on a PUT to be refused with 409 if the policy changed since it was read; omit it to replace whatever is stored.
  - `tags` PromotionPolicyTags, required
    - `cap` integer, required
    - `exclude` string[]
    - `include` string[]
    - `scheduledRemovalAt` object: When each excluded key's column is removed from the table, assigned by the server. Taking the key off the exclude list before then keeps the column.
  - `v` integer, required: Promotion policy document version.

## Response `200`

The persisted promotion policy.

- PromotionPolicy
  - `attributes` PromotionPolicyAttributes, required
    - `cap` integer, required
    - `exclude` PromotionPolicyAttributeExclude[]
      - `path` string, required
      - `prefix` boolean
      - `scheduledRemovalAt` string, date-time: When the columns this entry excludes are removed from the table, assigned by the server. Taking the entry off the exclude list before then keeps them.
    - `excludeAllByDefault` boolean: Whether every path no include covers is excluded. Writers stop filling the existing columns no include covers, and they are removed from the table at excludeAllScheduledRemovalAt.
    - `excludeAllScheduledRemovalAt` string, date-time: When the columns excludeAllByDefault excludes are removed from the table, assigned by the server. Turning excludeAllByDefault off before then keeps them.
    - `include` PromotionPolicyAttributeInclude[]
      - `numeric` boolean: Whether the path gets a numeric index column when the policy is stored, without waiting for a number. Exact entries only: refused when prefix is true.
      - `path` string, required
      - `prefix` boolean
  - `columnRemovalDelay` string, ISO-8601: How long after a path or key is excluded its index columns are removed from the table, as an ISO-8601 duration. Defaults to 6 hours when absent.
  - `revision` integer: Which store of the table's policy this is, assigned by the server: 0 when the table has none. Echo it on a PUT to be refused with 409 if the policy changed since it was read; omit it to replace whatever is stored.
  - `tags` PromotionPolicyTags, required
    - `cap` integer, required
    - `exclude` string[]
    - `include` string[]
    - `scheduledRemovalAt` object: When each excluded key's column is removed from the table, assigned by the server. Taking the key off the exclude list before then keeps the column.
  - `v` integer, required: Promotion policy document version.

## Other responses

- `400`: Invalid promotion policy.
- `404`: Dataset or table not found.
- `409`: The policy changed since the revision the request was made against; read it again and reapply the change. Or the table kept changing under the request, which a running writer's own evolution can cause; retry.

---

[API](https://skmtc.dev/grepr/apis/grepr-api.md) - [All operations](https://skmtc.dev/grepr/apis/grepr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/grepr/apis/grepr-api/revisions/2a5ce03a0bf0?raw)