Skip to main content
Citino collects answers every day and rebuilds the figures overnight. A warehouse job that keeps up with it needs one habit: each night, pull yesterday, and only yesterday.

Why one day at a time

  • It always fits. A report’s budget is counted in prompts × engines × days. One day with date as a dimension fits on every plan, however many prompts and engines your project has, so the job you write today keeps working as the project grows.
  • It reads each row once. With date as a dimension, pages run date first and each one reads only its own days, so the job does no repeated work.
  • It is light on your rate limit. One day is only as many pages as that day has rows, and report pages are the kind that count as several requests. See Rate limits.
A first backfill is the same loop over a longer window: keep date in the dimensions and page through. It takes longer, because every page counts as several requests, but up to 366 days it never hits the budget. A longer window is refused with window_too_large:, so pull a longer history in windows of 366 days or fewer.

The job

  1. Work out yesterday’s date in your project’s market time zone (America/New_York for a US market), because days in Citino are the market’s days, and run the job after midnight there. The samples read the zone from MARKET_TZ.
  2. Ask for the report with from and to both set to yesterday and date among the dimensions, plus whatever else you break down by (engine, say).
  3. Follow next_cursor until has_more is false. A page can be short, or even empty, before the end.
  4. Write the rows keyed on date, the other dimensions and the brand (or domain, or URL), replacing any row already stored with the same key.
  5. Run report requests one after another. A second report request from your workspace while one is running gets 503 busy.
The same loop pulls the domains and URLs reports: change brands to domains or urls, and key the rows on the domain or the URL instead of the brand. The URLs report has no prompt dimension.

Late answers, and why you replace rather than append

The figures for a recent day can still change after you first pull them. Every night Citino rebuilds the most recent seven days, because a day’s late answers and their reading can arrive after the day ends. So:
  • Replace, never append. Key each row as above and overwrite. Appending would count a revised day twice.
  • If you need settled numbers, re-pull the last seven days each night instead of only yesterday, with the same loop and from set seven days back. With date as a dimension the budget allows it, and it picks up every revision the nightly rebuild makes.
Older days change only rarely, when Citino re-reads stored answers with an improved reader. A periodic full re-pull of your history catches that too.

Keep the band with the number

Store each figure’s band, n and low_sample beside its value. A dashboard built on your warehouse should show the ± range and mute a change smaller than it, exactly as Citino’s own screens do. See Metric objects.

Reports

Dimensions, filters, budgets and paging.

CSV output

The same rows as a file, for a spreadsheet.

Rate limits

Budgets, weights and busy.

How answers are collected

What happens each day before the figures exist.