Put Statistics Configuration - Narrative I/O Knowledge Base

curl --request PUT \ --url https://api-dev.narrative.io/datasets/{dataset_id}/statistics-configuration \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "defaults": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "refresh": { "trigger": "cron", "cron_expression": "<string>" }, "dataset": { "scope": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "fields": [ { "field_name": "<string>", "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": [ { "path": "<string>", "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": "<unknown>" } } ], "items": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": "<unknown>" } } ] }, "rosetta_stone": { "scope": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "fields": [ { "attribute_name": "<string>", "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": [ { "path": "<string>", "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": "<unknown>" } } ], "items": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": "<unknown>" } } ] } } '

{ "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "dataset_id": 123, "version": 123, "created_at": "2023-11-07T05:31:56Z", "created_by": 123, "configuration": { "defaults": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "refresh": { "trigger": "cron", "cron_expression": "<string>" }, "dataset": { "scope": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "fields": [ { "field_name": "<string>", "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": [ { "path": "<string>", "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": "<unknown>" } } ], "items": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": "<unknown>" } } ] }, "rosetta_stone": { "scope": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "fields": [ { "attribute_name": "<string>", "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": [ { "path": "<string>", "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": "<unknown>" } } ], "items": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } }, "self": { "enabled_stats": [ "value_count" ], "stat_options": { "histogram": { "max_bins": 50, "overflow": "none" } } }, "properties": "<array>", "items": "<unknown>" } } ] } } }

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

Configuration payload for computing statistics on dataset fields and Rosetta Stone attributes. Supports recursive nesting for arbitrarily deep schemas.

Inheritance chain

defaults → namespace scope → field override → nested node overrides.

Two distinct inheritance rules apply depending on what is being configured:

1. Stat set (enabled_stats) — all-or-nothing per level

When a level provides enabled_stats, it completely replaces the parent's stat set. There is no merging: the child's list is the final set of stats for that scope. Properties not listed in a parent's properties array receive no stats — they are not inherited from any parent level. Example: an object field address has children city, zip, and state. If the field config lists only city in properties, then zip and state get no stats at all, regardless of what defaults or scope say.

2. Stat options (stat_options) — partial override with per-property inheritance

When a level provides only stat_options (without enabled_stats), it inherits the stat set from its parent and applies option overrides on top. Individual option properties follow a granular rule: only explicitly provided option properties are overridden; unspecified properties keep the value resolved from the parent level. Example: defaults enable histogram with max_bins: 50, overflow: none. A namespace scope provides stat_options: { histogram: { max_bins: 200 } } without enabled_stats. The resolved scope inherits the full stat set from defaults, and the histogram options become max_bins: 200, overflow: none — overflow was not overridden, so the parent's value (none) is preserved.

Chained stat_options overrides across levels

Per-property inheritance applies at every level of the chain, and each level inherits from its resolved parent — not from the original defaults. This means overrides accumulate. Example — scope overrides max_bins, field overrides overflow:

"defaults": {
    "enabled_stats": ["value_count", "histogram"],
    "stat_options": { "histogram": { "max_bins": 50 } }
  },
  "refresh": { "trigger": "manual" },
  "dataset": {
    "scope": {
      "stat_options": { "histogram": { "max_bins": 200 } }
    },
    "fields": [
      {
        "field_name": "price",
        "stat_options": { "histogram": { "overflow": "truncate" } }
      }
    ]
  }
} ```
Resolution for `price`:
1. **defaults** → `histogram(max_bins=50, overflow=none)`
2. **scope** (stat_options only, inherits defaults) → `histogram(max_bins=200, overflow=none)` —
   scope overrides `max_bins` to 200; `overflow` is not specified, so it keeps defaults' `none`.

3. **price field** (stat_options only, inherits resolved scope) → `histogram(max_bins=200, overflow=truncate)` —
   field overrides `overflow` to `truncate`; `max_bins` is not specified, so it keeps scope's `200` (not
   defaults' `50`).

The key point: `price` gets `max_bins=200` from scope, not `max_bins=50` from defaults. Each level inherits from its immediate resolved parent, not from the root.
The same per-property inheritance applies at nested levels (object properties, array items). A deeply nested node that provides only `stat_options` inherits the stat set and unspecified option properties from the effective parent resolved at the namespace level (defaults + scope).

defaults

object

required

Global default stat configuration applied to all eligible fields and properties. The server automatically filters stats incompatible with a field's resolved type and node kind. Note: enabled_stats is required for defaults because there is no parent scope to inherit from. Providing only stat_options without enabled_stats is invalid at this level.

Option 1
Option 2

Show child attributes

refresh

object

required

When to recompute statistics. Exactly one trigger type must be specified.

Option 1
Option 2
Option 3

Show child attributes

dataset

object

Configuration for dataset schema columns. Use 'scope' to override defaults for all dataset fields, or to disable the namespace entirely via enabled_stats: []. Use 'fields' for per-field overrides.

Option 1
Option 2

Show child attributes

rosetta_stone

object

Configuration for Rosetta Stone attributes. Use 'scope' to override defaults for all Rosetta Stone fields, or to disable the namespace entirely via enabled_stats: []. Use 'fields' for per-field overrides.

Option 1
Option 2

Show child attributes

Response

200 - application/json

Full statistics configuration entity with metadata. Returned by both PUT (create/update) and GET endpoints.

string<uuid>

required

Unique identifier for this configuration version.

dataset_id

integer<int64>

required

The dataset this configuration belongs to.

version

integer<int32>

required

Monotonically increasing version number.

created_at

string<date-time>

required

Timestamp when this configuration version was created.

created_by

integer<int64>

required

User ID of the user who created this configuration version.

configuration

object

required

The full statistics configuration payload.

Show child attributes

Access Rules

Access Tokens

App API

App Invites

Apps

Attributes

Auth

Authentication

Billings

Companies

Company

Company Marketing Information

Compute Pools

Connections

Contracts

Data Planes

Data Shops

Data Streams

Dataset Configuration

Dataset Files

Dataset Mappings

Dataset Refresh

Dataset Samples

Dataset Statistics

Datasets

Destinations

Encryption Materials

Installations

Jobs

Mappings

Model Inference

Models

NQL

Payment Methods

Permissions

Products

Profiles

Queries

Resources

Schema Inference

Schema Presets

Subscriptions

Uploads

Usage

Views

Webhooks

Whoami

Workflows

Authorizations

Path Parameters

Body

Inheritance chain

1. Stat set (enabled_stats) — all-or-nothing per level

2. Stat options (stat_options) — partial override with per-property inheritance

Chained stat_options overrides across levels

Response