Skip to content

Insights

You will learn how shape rankings and suggested views help you explore a stream without reconstructing filters by hand.

Insights is the place to see what structures Cordo has observed and turn the useful ones into saved views in one or two clicks.

What Insights shows

For the active stream, Insights has two surfaces:

Surface Purpose
Suggested views Create-ready starters derived from dominant shapes (and, when useful, value filters)
Shapes table Every observed shape fingerprint, ranked by how often it appears, with optional sample logs

Shapes are structural fingerprints of which keys appear together (top-level plus one nested level). See Fields and shapes for how they are learned.

Cohort versus columns

A useful suggestion does two separate jobs:

Job Meaning
Cohort Which events belong in the view (structural match, plus optional value filters)
Projection Which columns appear when you open the view

Suggestions never imply row isolation when they only configure columns. After LATT-228, every everyday suggestion includes a real shape matcher so the created view returns the cohort the card described for the same time window.

How matching works

Mode Matches when Typical use
Contains (shape family) Required shallow paths are present; extra paths are allowed Everyday suggested views — resilient to additive schema drift
Exact The shallow path fingerprint matches exactly (including keys whose JSON value is null) Schema debugging, or “Create from this shape” on a raw shape row

Optional value filters (for example level = error) refine the cohort further. Those filters are scored from recent windowed statistics when possible, not from a single sample event.

Families and purpose-built names

Optional fields create many near-identical fingerprints. Insights may group those into a family suggestion with:

  • Required paths (the shared core)
  • Optional paths (present on some members)
  • Combined coverage for the family cohort

When field combinations look like a familiar operational pattern (HTTP access logs, errors, service logs, jobs, audit activity, database queries), Insights may rename the suggestion into a purpose-built label. Unfamiliar schemas keep a clear generic shape or family name — low-confidence labels are not invented.

Preview before you create

You can:

  1. Create view in one click from an unchanged suggestion
  2. Preview to adjust name, lookback, filters, and columns, inspect match count/share and a small redacted sample, then create from that draft
  3. Start from any row in the Shapes table (“Create from this shape”) using the same preview/create flow with exact matching

Preview and create share the same normalized query payload, so the match estimate you see before create agrees with the resulting view for an unchanged window and data set.

What Insights is not

  • Not a replacement for free-form Query
  • Not a guarantee over historical ClickHouse rows ingested before shape metadata existed — new events carry shape identity at materialize time
  • Not ML classification — ranking and recipes are deterministic and schema-agnostic

Next