Analizy tablicy (Platform MCP)
Użyj tego narzędzia, aby uzyskać statystyczne podsumowania danych z tablicy bez pobierania poszczególnych elementów. Możesz grupować wyniki według wartości w kolumnach, stosować funkcje agregujące (zliczanie, sumowanie, średnia, minimum, maksimum i inne), filtrować zestaw elementów oraz sortować wyniki. Typowe zastosowania to zliczanie elementów według statusu, sumowanie wartości liczbowych według właściciela lub obliczanie średniego czasu trwania osi czasu w grupach.
Warunek wstępny: Przed użyciem tego narzędzia wywołaj get_board_info, aby poznać identyfikatory i typy kolumn. Dla każdego typu kolumny użytego w agregacjach lub filtrach wywołaj get_column_type_info z fetchMode: "guidelines", aby sprawdzić obsługiwane dla tego typu funkcje agregujące i reguły filtrowania.
Podczas grupowania każda kolumna w groupBy musi też wystąpić w aggregations bez funkcji (jako zwykłe odwołanie do kolumny). Czytelne dla człowieka etykiety pogrupowanych kolumn są zwracane w polu LABEL_<columnId>.
Parametry
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| boardId | number |
Tak | Identyfikator tablicy, dla której mają zostać obliczone statystyki. |
| aggregations | array |
Nie | Tablica obiektów agregacji. Każdy obiekt zawiera columnId i opcjonalnie function. Obsługiwane funkcje to m.in. COUNT, COUNT_ITEMS, SUM, AVERAGE, MIN, MAX, MEDIAN, LABEL, DATE_TRUNC_MONTH i DATE_TRUNC_WEEK. Kolumny z groupBy również muszą się tu znaleźć, ale bez funkcji. |
| groupBy | array |
Nie | Tablica identyfikatorów kolumn, według których mają być grupowane wyniki. Wszystkie kolumny z groupBy muszą również występować w aggregations bez funkcji. |
| limit | number |
Nie | Maksymalna liczba zwracanych wierszy wyników. Maksymalna wartość to 1000. Domyślnie 1000. |
| filters | array |
Nie | Tablica obiektów filtrów kolumn (o takiej samej strukturze jak filtry w get_board_items_page). Ogranicza zestaw elementów przed agregacją. |
| filtersOperator | string |
Nie | Operator logiczny łączący wiele filtrów: and (domyślny) lub or. |
| orderBy | array |
Nie | Tablica obiektów sortowania zawierających columnId i direction (asc lub desc). |
Przykład
Zlicz elementy pogrupowane według kolumny Status na tablicy 18392419286:
{
"boardId": 18392419286,
"aggregations": [
{ "columnId": "status", "function": "COUNT_ITEMS" },
{ "columnId": "status" }
],
"groupBy": ["status"]
}
W odpowiedzi zwrócono 5 wierszy - po jednym dla każdej etykiety statusu - wraz z liczbą elementów: W trakcie (Working on it) (6), Gotowe (Done) (4), Wymaga sprawdzenia (Needs Review) (2), Zablokowane (Stuck) (1) oraz pusty status/brak statusu (3). Każdy wiersz zawierał pole LABEL_status z czytelną dla człowieka etykietą i kolorem tego statusu zapisanym w formacie szesnastkowym.
Odpowiednik programistyczny
Użyj GraphQL API, aby uzyskać ten sam wynik. Analizy tablicy łączą filtrowanie elementów z agregacją. W API można to przybliżyć za pomocą items_by_column_values i późniejszego przetwarzania wyników albo pobrać wszystkie elementy i wykonać agregację po stronie klienta:
query {
boards(ids: [18392419286]) {
items_page(limit: 500) {
items {
id
column_values(ids: ["status"]) {
id
text
value
}
}
}
}
}
Pełną dokumentację znajdziesz w sekcji Items.