Concepts

Every segment answers four questions. Answer them deliberately and your model trains on exactly the data you intended; leave them implicit and you're training on accidents.

Columns: features, labels, engineered features

• Features are input columns — signal keys the model may learn from (["foot_traffic", "promo_active"]).
• Labels are output columns — what the model predicts (["daily_sales"]). A label can also appear as a feature (its own history is usually the strongest predictor).
• Engineered features are derived columns computed from a source field: lags, rolling statistics, event flags, calendar fields. They're declared once on the segment and computed identically at training and inference time — see Engineered features.

Every segment must declare at least one feature and one label — that's enforced at create time, so a segment can never enter an untrainable state. Plan limits cap how many features and labels a segment may carry.

Grid: interval and tolerance

The grid turns irregular arrivals into regular rows:

• interval — seconds between rows. 86400 means one row per day; 3600 one per hour.
• tolerance — how far (in seconds) from the row's timestamp a raw value may sit and still bind to that row. A daily grid with tolerance: 43200 accepts any value within ±12 hours.

Values inside tolerance snap to the grid; cells with nothing inside tolerance are gaps — which is where normalization takes over.

Don't guess these numbers: check each signal's real cadence in the signal list and set the grid from your slowest relevant signal — the interval should match how often it actually arrives, with a tolerance of about half that.

Window: live vs historical

• Live (live: true) — the window rolls forward: tail_seconds back from now (default ~8 months). Every read sees the freshest data. Use this for segments that feed scheduled retraining and live inference.
• Historical (live: false) — a fixed range pinned by window_start / window_end (ISO 8601). The table never changes. Use this for reproducible experiments and backtests. If the bounds are omitted, the tail-based fallback applies.

Normalization in one paragraph

Each cell that has no raw value within tolerance is filled by a strategy — carry the previous value forward, interpolate linearly, use the mean, leave it empty. A segment sets one global strategy (with a fallback chain) and may override it per field, because a temperature sensor and a status flag should not be filled the same way. The full catalog, fallback semantics, and templates are on Normalization.

Other things a segment carries

• Time zone (time_zone, default UTC) — how bucket timestamps and calendar features are interpreted.
• Sharing (data_sharing) — private (default), org (any organization member can use it), or public_inference.
• Feature beliefs — optional per-column confidence, impact, and direction priors (feature_beliefs, feature_impact, feature_direction). Hand-built segments default every column to full confidence; goal-built segments carry measured evidence from discovery.
• Origin — segments built by goal discovery show up alongside yours with "origin": "discovery"; they don't count against your segment quota and are maintained by their goal.

The contract with training and serving

The segment is the single source of truth for data shape. Whatever the grid, window, normalization, and engineered features produce is exactly what the trainer sees — and exactly what segment-based inference prepares when a deployed model is asked for a forecast. If a configuration can't be served (an unsupported technique or strategy), the API rejects it at create/edit time with a 422 rather than letting a segment exist that could never train.