The chart language

A chart in Kicklace is a small written question, not a query. You say what to measure, how to cut it, and what to leave out, and Kicklace works it out in the database and draws it. The same question can be asked three ways — typed into the ask box on the dashboard, built by hand under Build a chart, or handed to Claude as run_report — and all three read the language below, so a chart Claude ran is a chart you can save, edit and adjust afterwards.

Nothing here writes SQL, and no model ever does either: the model writes the question, Kicklace runs it.

---

The shape of a question

{
  "title": "Subscribers this month",
  "kind": "number",
  "object": "people",
  "metric": { "fn": "count" },
  "filters": [{ "by": "reachedStage", "value": "subscriber" }, { "by": "thisMonth" }],
  "compare": true
}

How it is drawn

One number for a total. Bars for a breakdown. A line for a trend by month or week. A funnel for people across the stages of a pipeline. A table when a table is what you want.

What it measures

count is how many. sum and avg take a numeric field — an amount, a number you added — or, on an events chart, the property the event carries its number in, which for a purchase is value.

rate is a share: how many of the rows the chart already matched also match one more condition, drawn as a percentage with both numbers under it. "What share of subscribers became customers" is a rate of reachedStage: purchaser over people who reached subscriber.

Stages: where they are, and how far they got

Two conditions look alike and are not:

• is at a stage is where a record sits right now.
• reached a stage is how far it got, counted by that stage's place in its pipeline: everyone at or past it. Somebody who bought has reached Subscriber.

Almost every question about a segment wants "reached". A funnel always counts who reached each stage; bars grouped by stage are a census of where people are today.

Time

withinDays is a rolling window; thisMonth and lastMonth are real calendar months in your workspace's own timezone. They read dateField: when the record was made by default, its last activity, or a date field of its own such as an expected close date. Weeks run Monday to Sunday, and the period you are still inside is drawn lightly and labelled so far, because a month on the 5th is not a collapse.

---

Four questions about time

Four kinds ask when something happened relative to something else — the week somebody was first seen, the stage they came from, their own first purchase. A group and a condition cannot say that, so each one is its own kind.

All four have this in common: they count people, they pick their own periods (so they take no time condition and no dateField), and any conditions you do give them narrow who is counted — "only people on the newsletter", not "only people this month".

A cohort grid

People by the week they were first seen, and the share who reached Subscriber within 7, 14, 30 and 60 days

A row for each week or month, a column for each window, and each cell the share of that row's people who got that far that soon — with the size of the row beside it, because a share is only worth reading next to what it is a share of. It answers "are we getting faster?": each row is a different week's intake, so a change down the grid is a change in the thing itself and not in how much time has passed.

A cell that is still filling is faded. The last person in a row was first seen at the end of that week, so the 60-day window has not finished for everyone in it until 60 days after the week ended. The figure is still shown — it is true as far as it goes — but it is not yet the row's final answer, and the card says so under the grid.

A conversion over time

People who reached Subscriber each week, and the share who went on to Activated

One line: for each week, the people who arrived at one stage that week, and how many of them have since reached another — however long it took. Under the latest reading is the median days it took the ones who made it, over the whole window drawn.

The newest weeks have had the least time to convert, which the card says: a dip at the right-hand end is usually the calendar rather than the funnel.

Sources against a stage

Where people came from, and the share who reached Purchaser

A table: where each person came from, how many came from there, how many of them got as far as one stage, and the rate. Rows are ordered by how many people they are a rate of — one purchase out of one visit is 100% and is not your best source, it is your smallest one.

Coming back

People by their first purchase, and the share who did it again in each month after

Of everyone with a first event on their record, the share who had another one in the first month after it, the second, the third. A month is counted only for the people whose first one is old enough for that month to have finished — so somebody who bought yesterday is not counted as having failed to come back, and a month nobody is old enough for yet says not yet rather than a confident zero.

---

Where "reached" is read from

The three kinds that ask about arriving at a stage read it off the record's own timeline: the earliest move into that stage, or into any stage past it. Every move is written down when it happens, by hand, by an automation or by an event from your website, so this is a record of what really happened rather than a guess from where somebody sits today.

Where a record has no move at all but is already sitting at or past the stage — an import, or a record somebody created there — the day the record was made is taken as the day it arrived. Without that, a workspace whose people all arrived by import would read as though nobody had ever arrived.

---

What a chart will not do

• It never reads another workspace, and it never reads a record that was merged away.
• It never names a stage, list, field or event your workspace does not have: a chart that does is drawn with the problem written inside the card rather than as a confident zero.
• A chart that covers nothing says what would fill it, rather than drawing four empty bars.
• Anonymous visitors are deleted once they have been quiet for as long as your privacy setting says, so a chart reaching back past that cutoff says on the card that the older counts are lower than they were.

---

Asking for one

On the dashboard, the ask pill in the corner takes the question in words, shows what it worked out, and adds the card if you keep it. Every card can be adjusted the same way afterwards.

Build a chart is the same language as a form, with every choice coming from your own workspace, so nothing invalid can be picked and the preview is the real thing running on your real data. It is also how a chart is edited by hand, and it needs no AI at all.

Through Claude, run_report answers a question and save_report keeps the answer as a card on one of your dashboards. Both read exactly the language above, and a spec that ran in one saves in the other unchanged.