Pisanie dashboardów#

Dashboard składa się z dokumentu dashboards/<slug>/page.md oraz opcjonalnych sąsiadujących plików .sql i .tsx. Markdown tworzy narrację. Komponenty przekształcają nazwane wyniki zapytań w wykresy, tabele, liczby, tabele przestawne i mapy.

Tworzenie strony#

text

dashboards/revenue/
  page.md
  revenue-daily.sql

Umieść tytuł strony, interwał odświeżania, limit wyników i opcjonalny motyw we frontmatter:

text

---
title: Revenue
refresh: 4h
max_rows: 2000
theme: supernova
---

Dodawanie zapytania#

Plik revenue-daily.sql jest dostępny na stronie jako revenue-daily:

sql

select
  cast(created_at as date) as day,
  sum(amount) / 100.0 as revenue
from titan.stripe.charges
where status = 'succeeded' and not _deleted
group by day
order by day

Wbudowany blok nazwany od języka również jest źródłem danych: ``` `sql revenue-daily ```. Sąsiadujące pliki ułatwiają recenzowanie dłuższych zapytań.

Budowanie na innym zapytaniu#

Zapytanie może odczytać inne zapytanie tego samego dashboardu jako queries.<name>:

sql

select sum(revenue) as revenue
from queries."revenue-daily"
where day >= $period.start

Zapytanie, do którego się odwołujesz, jest wstawiane w miejscu użycia, dzięki czemu działa w tym samym zadaniu i zawsze odczytuje bieżące dane — między zapytaniami nic nie jest zapisywane. Wejścia takie jak $period.start działają w obu zapytaniach. Odwołanie do nieistniejącego zapytania lub cykl między dwoma zapytaniami jest zgłaszany nad stroną.

Renderowanie wyniku#

text

<Chart data={revenue-daily} type="line" x="day" y="revenue"
       title="Revenue by day" format={{"type":"money","currency":"USD"}} />

Wbudowane komponenty danych to Chart, Table, BigNumber, Pivot i Map. Dostępne typy wykresów to line, bar, area, donut, pie i scatter. Umieść powiązane komponenty w <Row>, aby współdzieliły wiersz.

Oznaczanie celu#

text

<Chart data={revenue-daily} type="bar" x="day" y="revenue"
       goal={{"y":120000,"label":"Target"}} />

goal rysuje linię odniesienia na osi wartości i rozszerza skalę, aby linia zawsze mieściła się na wykresie. Przekaż tablicę, aby utworzyć najwyżej cztery linie — minimum, plan i cel ambitny. Na poziomych słupkach linia biegnie pionowo, ponieważ podąża za wartością, a nie ekranem. Wykresy pierścieniowe i kołowe nie mają osi wartości, więc odrzucają tę właściwość.

Wyróżnianie jednej serii#

text

<Chart data={revenue-by-plan} type="line" x="day" y="revenue" series="plan" emphasis="enterprise" />

emphasis zachowuje kolor wskazanej serii, a wszystkie pozostałe przycisza — jednocześnie linie, obszary, słupki, punkty, legendę i próbki podpowiedzi. Dopasowanie nie rozróżnia wielkości liter. Nazwa nieobecna w żadnej serii nie zmienia niczego, dlatego wykres nie psuje się po zniknięciu kategorii z danych.

Nazywanie momentu#

text

<Chart data={revenue-daily} type="line" x="day" y="revenue"
       annotations={[{"x":"2026-03-01","label":"Price change"}]} />

Każda adnotacja rysuje pionową cienką linię przy wskazanym x i niewielką etykietę u góry wykresu; można dodać najwyżej osiem. x musi być wartością faktycznie zwróconą przez zapytanie — filtry przesuwają okno, dlatego wartość poza nim jest pomijana, a nie przyciągana do krawędzi. Etykiety są skracane i przesuwane do kolejnego wiersza przy kolizji. Po czterech wierszach linia nadal się pojawia, ale etykieta jest pomijana, bo piąty wiersz tekstu zająłby wykres.

Jedno zapytanie dla liczb i wykresów#

text

<BigNumber data={revenue-daily} value="revenue" label="Revenue" agg="sum" trend />

Duża liczba domyślnie odczytuje pierwszy wiersz. agg składa zamiast tego całą kolumnę — przez sum, avg, last lub first — dzięki czemu dzienne zapytanie może zasilać wykres i rzetelną sumę z tych samych wierszy. trend dodaje obok wartości miniwykres tej kolumny w kolejności wierszy.

Kolumna liczb całkowitych sumuje się dokładnie również po przekroczeniu punktu, w którym suma zmiennoprzecinkowa zaczyna dryfować, dlatego liczby i identyfikatory pozostają poprawne. Domyślny format compact nadal zaokrągla prezentację — do tego służy zapis skrócony. Wybierz number lub integer, gdy liczy się każda cyfra.

Porównywanie z poprzednim okresem#

text

<Chart data={revenue-daily} type="line" x="day" y="revenue" compare="prev-period" />
<BigNumber data={revenue-total} value="revenue" label="Revenue" compare="prev-year" />

compare wykonuje to samo zapytanie drugi raz z zakresem dat przesuniętym wstecz — prev-period o długość bieżącego okna, a prev-year o jeden rok kalendarzowy. Wykres rysuje wcześniejszy okres jako przygaszone widmo pod bieżącym i, jeśli nie podano podtytułu, dodaje opis zmiany. Duża liczba pokazuje zmianę obok wartości.

Zapytanie musi odczytywać zakres dat, aby istniało co przesunąć, dlatego filtruj je przez $period.start i $period.end. Wykres porównuje jedną miarę: bez listy y, series i pierścienia. W dużej liczbie compare zastępuje delta.

Oba okresy są wyrównywane według wartości, nie kolejności wierszy. Na osi dat każdy wcześniejszy wiersz przesuwa się dokładnie o zmianę zastosowaną w zapytaniu, dlatego brak dnia pozostawia lukę, zamiast przesuwać wszystko w lewo. Na osi kategorii — na przykład wykresie top N — wiersze wcześniejszego okresu pasują według nazwy. Kategoria obecna wcześniej, lecz nieobecna teraz, nie ma miejsca i nie jest rysowana; nowa kategoria nie ma widma. Opis zmiany nadal mierzy cały wcześniejszy okres, w tym wiersze, na które zabrakło miejsca na wykresie, dzięki czemu zdanie pozostaje prawdziwe przy częściowym obrazie.

Dodawanie wejść z typami#

text

<DateRange name="period" default="-30d" />
<Select name="currency" options={["usd","eur","gbp"]} default="usd" />

Odwołuj się do wejść w SQL jako $period.start, $period.end i $currency. Wartości są sprawdzane względem deklaracji i wiązane jako parametry przygotowanej instrukcji. Wartości z adresu URL nigdy nie są wstawiane do SQL jako tekst.

Obsługiwane są TextInput, NumberInput, Select i DateRange. Select z multiple wiąże ograniczoną listę. Względne ustawienia dat to -30d, -2w, -6m, -1y, mtd, ytd, today i all.

Rozszerzanie dashboardu#

Dodaj <Name>.tsx obok page.md, aby utworzyć komponent właściwy dla strony, albo umieść komponent współdzielony w dashboards/components/. Komponenty niestandardowe otrzymują ograniczone dane tabelaryczne i te same narzędzia motywu co komponenty wbudowane.