Skip to main content
PUT
/
datasets
/
{dataset_id}
/
retention-policy
Upsert retention policies for a dataset
curl --request PUT \
  --url https://api-dev.narrative.io/datasets/{dataset_id}/retention-policy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "expire_everything"
}
'
{
  "id": 18923,
  "company_id": 382,
  "created_at": "2021-06-24T00:54:40.029056Z",
  "description": "Mobile identifiers tied to birth information provided as part of app registration.",
  "name": "declared_age",
  "display_name": "Declared Age",
  "schema": {
    "file_config": {
      "type": "flat",
      "delimiter": ",",
      "escape": "\"",
      "header": true,
      "quote": "\""
    },
    "type": "object",
    "properties": {
      "idValue": {
        "display_name": "id value",
        "order": 0,
        "approximate_cardinality": 100000,
        "description": "ID values",
        "type": "string"
      },
      "idType": {
        "display_name": "id type",
        "order": 1,
        "approximate_cardinality": 1,
        "type": "string",
        "enum": [
          "md5_email",
          "sha256_email"
        ]
      },
      "eventTimestamp": {
        "display_name": "event timestamp",
        "order": 2,
        "description": "When the observation was collected",
        "type": "timestamptz",
        "validations": [
          "eventTimestamp < current_timestamp()"
        ]
      },
      "countryCode": {
        "display_name": "country code",
        "order": 3,
        "approximate_cardinality": 6,
        "description": "The country of residence of the individual",
        "type": "string"
      },
      "age": {
        "display_name": "age",
        "order": 4,
        "approximate_cardinality": 90,
        "description": "How old this individual is in years",
        "type": "long"
      },
      "birthInfo": {
        "display_name": "birth info",
        "order": 5,
        "description": "The year this individual was born",
        "type": "double"
      }
    },
    "required": [
      "idValue",
      "idType",
      "eventTimestamp",
      "countryCode",
      "age"
    ],
    "primary": "/age"
  },
  "status": "active",
  "tags": [
    "age",
    "demo",
    "demographic",
    "demographics"
  ],
  "updated_at": "2021-06-24T00:54:40.029056Z",
  "write_mode": "append",
  "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
  "last_snapshot_created_at": "2023-06-09T16:51:34.215Z",
  "stats": {
    "est_total_dataset_stored_files": 10,
    "est_total_dataset_stored_records": 500059,
    "est_total_dataset_stored_bytes": 4206454,
    "active_dataset_stored_files": 10,
    "active_dataset_stored_records": 500059,
    "active_dataset_stored_bytes": 4206454,
    "last_snapshot_added_files": 2,
    "last_snapshot_added_records": 499999,
    "last_snapshot_deleted_records": 0,
    "last_snapshot_added_bytes": 4193500,
    "last_snapshot_deleted_files": 0,
    "last_snapshot_added_delete_files": 0,
    "last_snapshot_removed_delete_files": 0,
    "last_snapshot_removed_bytes": 0
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
dataset_id
integer
required

Unique identifier for a dataset.

Body

application/json

Backwards-compatible legacy payloads. Interpreted as snapshot-level retention on Iceberg. Returned response will be unified v1 shape with compat.mode=legacy.

​
type
enum<string>
Available options:
expire_everything

Response

200 - application/json

OK

​
id
integer
required

Unique identifier for the dataset.

​
company_id
integer
required

The ID of the company owning the dataset.

​
created_at
string
required

ISO-8601 timestamp indicating when the dataset was created

​
name
string
required

The Dataset's name. Should be unique, contain only alpanum chars and underscores. Max length is 256.

​
display_name
string
required

The Dataset's name to display at UI.

​
retention_policy
object
required

Backwards-compatible legacy payloads. Interpreted as snapshot-level retention on Iceberg. Returned response will be unified v1 shape with compat.mode=legacy.

Example:
{ "type": "expire_everything" }
​
schema
object
required

Schema describing a dataset's input file type and the kind of data the file contains. Note: when the file type is "flat" then the order of the properties describing the must be given in the order they appear in the input file.

​
status
enum<string>
required

The dataset status.

  • active means that data can be added to the dataset but the schema is locked in place
  • pending means the dataset has been created, but the schema can still be altered and no data can be added to the dataset
Available options:
active,
pending
​
tags
string[]
required

Tags that describe the dataset.

​
write_mode
enum<string>
required

How Narrative will treat new data uploaded for the dataset.

  • append means data will be added to the dataset, this is what to choose if you incrementally update your dataset over time.
  • overwrite means that all existing data will be overwritten with new data.
Available options:
append,
overwrite
​
updated_at
string
required

ISO-8601 timestamp indicating when the dataset was last updated.

​
description
string

A description of the data contained with the dataset.

​
subscription_id
string

Id of a subscription which writes output to the dataset

​
last_snapshot_created_at
string

ISO-8601 timestamp indicating when the last snapshot was created.

​
stats
object