Reports & TraddalQL

Reports live at Reports in the sidebar. Open a default report, or start a New exploration, edit the query, press Run (⌘/Ctrl + Enter) and save what you find. Saved reports can be personal or shared with the whole team.

The query language

TraddalQL is a small, ShopifyQL-shaped language. Every query starts with the data to report on and what to measure:

FROM shipments
SHOW shipments, payment_collected
GROUP BY destination_country
DURING last_30_days
ORDER BY shipments DESC
LIMIT 20

Clause	What it does	Example
`FROM`	Choose the schema (table)	`FROM charges`
`SHOW`	Metrics to measure (`AS` renames a column)	`SHOW amount AS revenue, margin`
`GROUP BY`	Dimensions to slice by	`GROUP BY customer, currency`
`WHERE`	Filter rows before aggregation	`WHERE status != 'cancelled' AND destination_country IN ('US', 'CA')`
`TIMESERIES`	One row per `hour`, `day`, `week`, `month`, `quarter` or `year`, gaps filled with zero	`TIMESERIES week`
`DATE BY`	Which date the time clauses use	`DATE BY paid_at`
`SINCE` / `UNTIL`	Time window (`'2026-01-01'`, `today`, `yesterday`, `-30d`, `-12m`, `-1y`, `startOfMonth(-1m)`)	`SINCE -90d UNTIL today`
`DURING`	A preset window	`DURING last_month`
`COMPARE TO`	Compare against `previous_period` or `previous_year`	`COMPARE TO previous_period`
`WITH`	`TOTALS` adds a totals row; `PERCENT_CHANGE` shows change vs the comparison	`WITH TOTALS, PERCENT_CHANGE`
`ORDER BY`	Sort by a shown metric or grouped dimension	`ORDER BY amount DESC`
`LIMIT`	Cap rows (default 1000, max 5000)	`LIMIT 50`
`VISUALIZE`	Draw a metric (`TYPE line`, `bar`, `area` or `table`)	`VISUALIZE amount TYPE bar`

WHERE supports =, !=, <, <=, >, >=, IN (...), NOT IN (...), IS NULL, IS NOT NULL, CONTAINS 'text', STARTS WITH 'text', combined with AND, OR, NOT and parentheses. Text comparisons are case-insensitive. Comments start with --. DURING presets: today, yesterday, this_week, last_week, this_month, last_month, this_quarter, last_quarter, this_year, last_year, last_7_days, last_30_days, last_90_days, last_365_days, all_time. A TIMESERIES without a window defaults to the last 30 days.

Schemas

Schema	One row per	Highlights
`shipments`	shipment	`shipments`, `parcels`, `declared_weight_kg`, `goods_value`, `delivered_shipments`, `average_days_to_deliver`, `payment_collected`; by `destination_country`, `carrier`, `customer`, `incoterm`, `hs_codes`, `item_origin_countries`
`parcels`	parcel	`parcels`, `measured_weight_kg`, `volume_m3`, `volumetric_weight_kg`, `chargeable_weight_kg`, `weight_difference_kg`, `pure_alcohol_litres`; by `parcel`, `dimensions`, `measured_dimensions`, `parcel_weight`, `carrier`, `service`, `max_abv`
`items`	item line	`quantity`, `value`, `weight_kg`, `volume_litres`, `pure_alcohol_litres`, `average_abv`, `skus`; by `sku`, `hs_code`, `hs_chapter`, `country_of_origin`, `abv`, `product_type`
`orders`	order	`orders`, `order_value`, `average_order_value`, `shipping_charges`; by `order_ref`, `currency`, `customer`
`labels`	carrier label	`labels`, `voided_labels`, `void_rate`; by `carrier`, `service`, `role`, `status`
`charges`	billing ledger line	`amount`, `cost`, `margin`, `margin_percent`, `invoiced_amount`, `uninvoiced_amount`; by `kind`, `product_code`, `zone_code`, `customer`, `currency`
`invoices`	invoice	`total`, `tax`, `amount_paid`, `outstanding`, `overdue`, `average_days_to_pay`; by `status`, `customer`, `currency`
`payments`	receiver payment link	`payment_links`, `paid_links`, `conversion_rate`, `amount_paid`, `fees`, `average_hours_to_pay`
`duties`	duty assessment	`duty`, `taxes`, `fees`, `total`; by `kind`, `source`, `destination_country`
`events`	parcel event	`events`, `parcels`; by `event`, `canonical_type`, `source`, `location_country`
`exceptions`	exception	`exceptions`, `open_exceptions`, `average_hours_to_resolve`; by `code`, `severity`, `status`
`holds`	hold	`holds`, `active_holds`, `average_hours_held`; by `hold_type`, `status`, `source`
`cases`	claim / dispute	`cases`, `open_cases`, `won_cases`, `lost_cases`, `average_days_to_resolve`; by `type`, `status`, `provider`
`containers`	warehouse group	`containers`, `pieces`, `manifested_containers`; by `kind`, `status`, `destination`
`manifests`	manifest	`manifests`, `items`, `mismatches`; by `kind`, `status`, `origin`, `destination`, `carrier_code`

Every schema that belongs to a shipment also groups by the shipment’s fields (shipment_ref, destination_country, receiver, incoterm, …) and its customer. Weights and dimensions are stored in each shipment’s own units; the _kg, _m3 and _litres metrics convert them so totals add up. Volumetric weight uses the 5000 cm³/kg divisor. The editor’s suggestions list every metric and dimension with a description, and the Controls rail edits the same query text — pick metrics, dimensions, a time window and a chart type without typing. You can also ask the Assistant. With an exploration open, describe the report (“shipments by carrier per week this quarter”) and it writes the query into the editor and runs it. From any page it can save a report for you (personal unless you ask it to share it) or change one you’ve saved — changes to a saved report ask for your approval first. Export downloads the results as an Excel workbook (numbers and dates stay real values) or a CSV file. Money metrics are summed in the row’s own currency: group by the schema’s currency dimension when you bill in more than one.

Limits

Reports run inside the organisation’s row-level security and never see another tenant’s data.
A query runs for at most 15 seconds and returns at most 5,000 rows; a TIMESERIES may produce at most 2,000 buckets.
Report runs are limited per organisation (60 per minute) to keep dashboards responsive for everyone.

Scheduled deliveries

Any shared report can be sent to a customer automatically — as a file on their SFTP server or as an email attachment — at a set time. Open the report and choose Deliveries. Example: every weekday at 06:30 send a customer the shipment reference and the final-mile tracking number of their FedEx parcels:

FROM parcels
SHOW parcels
GROUP BY shipment_ref, final_mile_tracking_number
WHERE carrier_code = 'fedex' AND final_mile_tracking_number IS NOT NULL
SINCE -7d

Setting	What it does
Customer	Limits every file to that customer’s rows, on top of the report’s own `WHERE` — editing the report can never widen a customer’s file.
Format	CSV (choose the delimiter), Excel, JSON or XML (choose the root and row element names). Values are written exactly as stored — leading zeros are kept.
Columns	Pick and order the columns and rename the headers to what the customer’s system expects.
File name	A pattern with `{date}`, `{time}`, `{datetime}`, `{report}` and `{run}` tokens, e.g. `ACME_{date}` → `ACME_20261014.csv`.
Only new rows	Rows already delivered are left out of later files, so the customer only gets what is new since the last send. A row that only qualifies later (e.g. its tracking number arrives a day late) goes in the next file. Choose which columns identify a row (default: all of them).
Schedule	Daily, weekdays, chosen days of the week, or every n days, at a local time in any timezone (daylight saving is handled). Files go out within a minute of the set time.
Destination	SFTP — host, port, user, password or private key, and directory. Email — up to 10 recipients, with the file attached.

Use Test connection to check an SFTP login before saving; the server’s host key is shown so you can trust it. The key is pinned on first use and a delivery fails rather than send to a server whose key has changed. Passwords and keys are stored encrypted and are never shown again. Every run is listed with its row count and status, and the file it sent can be downloaded. Send now sends straight away; Resend these rows puts a past run’s rows back in the queue for the next file.

When nothing is new the run is recorded as empty and no file is sent (switch on Send a file even when there’s nothing new if the customer expects one every day). After 5 failed runs in a row a delivery pauses itself and you are notified; switch it back on once the problem is fixed.

Limits: up to 50 deliveries per organisation, 24 runs per delivery per day, Send now up to 6 times an hour, files up to 10 MB (5,000 rows).

Getting started

Concepts

The query language

Schemas

Limits

Scheduled deliveries

​The query language

​Schemas

​Limits

​Scheduled deliveries

The query language

Schemas

Limits

Scheduled deliveries