Ta wersja wprowadza nowy typ tablicy, który obsługuje wiele poziomów podelementów, oraz nową funkcję kolumny podsumowującej. W tym dokumencie opisujemy nowe funkcje i zmiany w API, które należy uwzględnić.

Podsumowanie zmian

• Tablice wielopoziomowe obsługują maksymalnie pięć poziomów podelementów. Elementy nadrzędne i podelementy mają tę samą strukturę kolumn.
• Do wersji API 2026-04 tablice wielopoziomowe nie są zwracane domyślnie przez zapytanie boards.
• Kolumny podsumowujące to nowa funkcja kolumn dostępna na tablicach wielopoziomowych. Mogą zawierać wartości statyczne i obliczone na podstawie elementów podrzędnych.
• Domyślnie API zwraca puste wartości dla kolumn podsumowujących. Aby je pobrać, musisz przekazać capabilities: [CALCULATED].
• Kolumny statusu z podsumowaniem zwracają typ BatteryValue zamiast StatusValue - także w przypadku elementów końcowych.
• Mutacje i filtrowanie wprowadzają nowe zachowania, które należy uwzględnić podczas zapisywania danych na tablicach wielopoziomowych i ich odczytywania.

Informacje ogólne

Wprowadzamy w monday dwie nowe funkcje: tablice wielopoziomowe i kolumny podsumowujące.

Tablice wielopoziomowe

Tablica wielopoziomowa to nowy typ tablicy, który obsługuje maksymalnie pięć poziomów podelementów.

Początkowo ten układ będzie dostępny tylko na tablicach projektowych w ramach rozwiązania Portfolio. Podczas tworzenia tablicy projektowej użytkownik może wybrać ten typ układu. Przy tworzeniu zwykłej tablicy domyślnie nadal będzie dostępna tablica klasyczna.

Różnice architektoniczne w porównaniu z tablicami klasycznymi

Zrozumienie różnic w strukturze tablic klasycznych i wielopoziomowych jest niezbędne do pracy z nimi przez API:

Aspekt	Tablice klasyczne	Tablice wielopoziomowe
Poziomy podelementów	Tylko jeden poziom	Maksymalnie pięć poziomów
Gdzie znajdują się podelementy	Na osobnej, ukrytej tablicy podelementów, która ma własny identyfikator tablicy i strukturę kolumn	Na tej samej tablicy co elementy nadrzędne - wszystkie elementy mają ten sam identyfikator tablicy
Struktura kolumn	Podelementy mają własną, niezależną strukturę kolumn	Wszystkie elementy i podelementy mają tę samą strukturę kolumn
board_id dla mutacji	Podczas wykonywania mutacji na podelementach używaj identyfikatora tablicy podelementów	Zawsze używaj identyfikatora głównej tablicy - zarówno dla elementów nadrzędnych, jak i podelementów na dowolnym poziomie
Zwracane przez zapytanie boards	Tak (domyślnie)	Domyślnie nie, do wersji 2026-04. Użyj hierarchy_types: [multi_level].

Kolumny podsumowujące

Wraz z wprowadzeniem tablic wielopoziomowych potrzebny był też sposób na podsumowywanie wartości elementów podrzędnych. Służą do tego kolumny podsumowujące.

Podsumowanie to nowa funkcja, którą można włączyć w kolumnach liczbowych, daty, osi czasu i statusu na tablicach wielopoziomowych.

Kolumny z włączonym podsumowaniem mogą podsumowywać dane elementów podrzędnych. Poszczególne komórki takiej kolumny zawierają albo dane statyczne, albo podsumowanie danych elementów znajdujących się niżej w hierarchii. Jeśli element jest nadrzędny, komórka zawiera podsumowanie jego elementów podrzędnych. Jeśli element nie ma elementów podrzędnych, komórka zawiera wartość statyczną.

Obsługiwane typy kolumn i funkcje podsumowujące

Każdy typ kolumny obsługuje określone funkcje podsumowujące:

Typ kolumny	Obsługiwane funkcje	Funkcja domyślna
numbers	SUM, MIN, MAX, NONE	SUM
date	MIN, MAX, NONE	MAX
timeline	MIN_MAX, NONE	MIN_MAX
status	COUNT_KEYS, NONE	COUNT_KEYS

Funkcja NONE wyłącza obliczanie podsumowania dla kolumny, ale pozostawia metadane funkcji.

Szacowany harmonogram

Poniższy harmonogram rozróżnia dostęp użytkowników do funkcji i dostęp przez API. Harmonogram może ulec zmianie. Najnowsze informacje znajdziesz w informacjach o wydaniach API.

Kwartał	Zmiany dla użytkowników	Zmiany w API
Q4 2025	Testy alfa dla niewielkiej grupy użytkowników na tablicach projektowych. Konta deweloperskie uzyskują dostęp.	Wersja API 2025-10: Zapytanie boards domyślnie zwraca tylko tablice klasyczne. Do obiektu boards zostaje dodane pole hierarchy_type.
Q1 2026	Tablice wielopoziomowe stają się dostępne jako opcja dla wszystkich nowych tablic.	Wersja API 2026-04 zostaje udostępniona jako wersja RC. Zapytanie boards domyślnie zwraca tablice klasyczne i wielopoziomowe.
Q2 2026	Brak nowych zmian	Wersja API 2026-04 zostaje ustawiona jako bieżąca wersja domyślna.

Zgodność wsteczna

Aby uniknąć problemów z działaniem istniejących integracji, wprowadzamy te funkcje stopniowo:

• Do wersji 2026-04 zapytanie boards domyślnie zwraca tylko tablice classic. Istniejące zapytania będą działać jak dotychczas.
• Wszystkie istniejące mutacje nadal działają. Ograniczenia dotyczące podsumowań, takie jak blokowanie aktualizacji, obowiązują tylko na tablicach wielopoziomowych.

✅ Oznacza to, że istniejące zapytania będą działać bez zmian. Aktualizacji kodu wymagają tylko te rozwiązania, które mają korzystać z tablic wielopoziomowych lub podsumowań.

Zmiany w API

Mając na uwadze harmonogram wdrażania, przyjrzyjmy się konkretnym zmianom w API i sposobom dostosowania istniejących zapytań.

Tablice wielopoziomowe

Tablice wielopoziomowe	Tablice klasyczne	Jak dostosować
Obsługują maksymalnie pięć poziomów podelementów	Obsługują tylko jeden poziom podelementów	Podelementy mogą teraz mieć własne podelementy. Hierarchia tablic jest głębsza niż wcześniejsza, dwupoziomowa struktura.
Wszystkie elementy i podelementy znajdują się na tej samej tablicy - nie ma osobnej tablicy podelementów	Podelementy znajdują się na ukrytej tablicy podelementów	Na tablicach klasycznych podelementy miały własny identyfikator tablicy i strukturę kolumn. Na tablicach wielopoziomowych wszystkie elementy mają ten sam identyfikator tablicy. Zawsze używaj identyfikatora głównej tablicy w mutacjach.
Wszystkie podelementy są zwracane przez obiekt subitems, niezależnie od poziomu	Takie samo zachowanie	Użyj pola parent_item, aby określić hierarchię elementów nadrzędnych i podrzędnych.
Podelementy mają taką samą strukturę kolumn jak elementy nadrzędne	Podelementy mają niezależną strukturę kolumn	Na tablicach wielopoziomowych wszystkie elementy mają tę samą strukturę kolumn, niezależnie od poziomu.
Domyślnie nie są zwracane przez zapytanie boards	Domyślnie są zwracane	Ze względu na zgodność wsteczną pole boards domyślnie pomija tablice wielopoziomowe. Od wersji 2026-04 pole boards domyślnie zwraca tablice klasyczne i wielopoziomowe. Użyj argumentu hierarchy_types: [multi_level], aby filtrować tablice klasyczne lub wielopoziomowe.
Domyślnie filtry dotyczą elementów nadrzędnych	Takie samo zachowanie	Filtry używane w zapytaniach items_page lub items_page_by_column_values domyślnie dotyczą tylko elementów nadrzędnych. Przekaż opcjonalny argument hierarchy_scope_config z wartością "allItems", aby zastosować filtr zarówno do elementów, jak i podelementów. Jeśli podelement spełnia warunek filtra, zostanie zwrócony razem ze swoimi elementami nadrzędnymi.
Archiwizowanie, usuwanie i duplikowanie elementów obejmuje też wszystkie ich podelementy	Takie samo zachowanie	Mutacje move_item_to_group, move_item_to_board, archive_item, delete_item i duplicate_item obejmują docelowy element i wszystkie jego elementy podrzędne.
Podczas tworzenia pierwszego podelementu wartości elementu nadrzędnego są kopiowane	Takie samo zachowanie	Utworzenie pierwszego podelementu danego elementu nadrzędnego kopiuje do niego wartości elementu nadrzędnego, chyba że podano je jawnie. Kolejne podelementy powodują ponowne obliczenie podsumowania, ale nie kopiują wartości.
Zmiana wartości kolumn (kolumn podsumowujących): zablokowana, gdy element ma co najmniej jeden podelement (wartość komórki elementu nadrzędnego jest obliczana)	Takie samo zachowanie	Usuń wszystkie podelementy, aby odblokować edycję elementu nadrzędnego, albo zaktualizuj elementy podrzędne.

Kolumny podsumowujące

Zmiana	Szczegóły
Wartości kolumn podsumowujących nie są zwracane domyślnie	Domyślnie pole column_values nie zwraca wartości kolumn podsumowujących - API zwraca dla nich pustą tablicę. Aby zwrócić wartości podsumowań, musisz przekazać argument capabilities: [CALCULATED] w polu column_values. Zwrócone zostaną wtedy zarówno wartości podsumowane (obliczone), jak i statyczne. Dotyczy to wszystkich elementów na tablicy wielopoziomowej, w tym elementów końcowych bez podelementów.
Kolumny statusu z podsumowaniem zwracają typ BatteryValue	Kolumny statusu z funkcją podsumowania zwracają typ BatteryValue zamiast StatusValue. Dotyczy to wszystkich elementów - zarówno nadrzędnych (wartości obliczane), jak i końcowych (wartości statyczne). Aby odczytać te wartości, użyj ... on BatteryValue zamiast ... on StatusValue. Pole battery_value zwraca tablicę obiektów {key, count}.
Kolumny liczbowe, daty i osi czasu zachowują standardowe typy	W przeciwieństwie do kolumn statusu, te kolumny zwracają swoje standardowe typy (NumbersValue, DateValue, TimelineValue) niezależnie od tego, czy mają włączone podsumowanie. Użyj pola is_leaf, aby odróżnić wartości statyczne od obliczonych wartości podsumowania.
Pole is_leaf w wartościach kolumn	Wszystkie typy wartości kolumn zawierają teraz pole is_leaf (Boolean!). To pole określa, czy element ma podelementy, i dotyczy tablic klasycznych oraz wielopoziomowych. Na tablicach wielopoziomowych z kolumnami podsumowującymi: true - element nie ma podelementów; wartość jest statyczna. false - element ma podelementy; wartość jest obliczonym podsumowaniem ich danych.
Kolumny mają pole capabilities, które informuje, czy włączono dla nich podsumowanie	Pole capabilities w obiekcie Column zawiera metadane podsumowania. Użyj go, aby sprawdzić funkcję agregującą używaną przez kolumnę (np. SUM, MIN, COUNT_KEYS itd.). Możesz też przekazać capabilities: [CALCULATED] w polu columns tablicy, aby wyświetlić tylko kolumny obsługujące podsumowania.
Mutacje create_column i update_column mają argument capabilities, który pozwala dodać, usunąć lub zmienić funkcję podsumowującą	Jeśli nie podasz tego argumentu, zastosowane zostaną wartości domyślne: • Na tablicach wielopoziomowych kolumny liczbowe, daty, osi czasu i statusu są tworzone z włączoną funkcją obliczania podsumowania. • We wszystkich pozostałych przypadkach nie są stosowane żadne funkcje. Aby wyłączyć podsumowanie na tablicy wielopoziomowej, przekaż capabilities: {calculated: {function: NONE}}.
Mutacje w komórkach obliczanych (z podsumowaniem) kończą się powodzeniem bez zmiany wartości	Zapis do komórki podsumowania elementu nadrzędnego nie zwraca błędu. API zwraca informację o powodzeniu, ale wartość nie zostaje zmieniona - pozostaje wartością obliczoną. Zamiast tego zaktualizuj elementy podrzędne.
Filtry obejmują elementy nadrzędne i podelementy, w tym wartości podsumowań	Użyj hierarchy_scope_config: "allItems" w zapytaniu items_page, aby przeszukać elementy nadrzędne i podelementy. Jeśli podelement spełnia warunek filtra, w odpowiedzi zostaną uwzględnione także jego elementy nadrzędne.

Przykładowe zapytania

Skorzystaj z poniższych przykładowych zapytań, aby rozpocząć pracę z tablicami wielopoziomowymi i kolumnami podsumowującymi.

Zapytania dotyczące tablic wielopoziomowych

Sprawdzanie typu tablicy za pomocą hierarchy_type

Użyj pola hierarchy_type w obiekcie Board, aby sprawdzić, czy tablica jest wielopoziomowa. To pole może przyjmować dwie wartości: multi_level i classic.

query {
  boards(hierarchy_types: [classic, multi_level]) {
    id
    name
    hierarchy_type
  }
}

{
  "data": {
    "boards": [
      {
        "id": "1234567890",
        "name": "Product Roadmap",
        "hierarchy_type": "multi_level"
      },
      {
        "id": "9876543210",
        "name": "Sprint Board",
        "hierarchy_type": "classic"
      }
    ]
  }
}

Pobieranie elementów, podelementów i relacji z elementem nadrzędnym

To zapytanie pobiera elementy i ich podelementy. Pole parent_item pozwala odtworzyć hierarchię - podelementy, których pole parent_item wskazuje inny podelement, znajdują się głębiej w strukturze.

query {
  boards(ids: 1234567890) {
    items_page(limit: 1) {
      items {
        id
        name
        subitems {
          id
          name
          parent_item {
            id
            name
          }
        }
      }
    }
  }
}

{
  "data": {
    "boards": [
      {
        "items_page": {
          "items": [
            {
              "id": "1000000001",
              "name": "Partner Integration Campaign",
              "subitems": [
                {
                  "id": "1000000002",
                  "name": "Recruit partners",
                  "parent_item": {
                    "id": "1000000001",
                    "name": "Partner Integration Campaign"
                  }
                },
                {
                  "id": "1000000003",
                  "name": "List of potential partners",
                  "parent_item": {
                    "id": "1000000002",
                    "name": "Recruit partners"
                  }
                },
                {
                  "id": "1000000004",
                  "name": "Google research",
                  "parent_item": {
                    "id": "1000000003",
                    "name": "List of potential partners"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Pobieranie wszystkich elementów i podelementów za pomocą hierarchy_scope_config

Domyślnie items_page zwraca tylko elementy najwyższego poziomu. Przekaż hierarchy_scope_config: "allItems", aby uwzględnić wszystkie elementy i podelementy na jednej, spłaszczonej liście.

query {
  boards(ids: 1234567890) {
    items_page(limit: 25, hierarchy_scope_config: "allItems") {
      items {
        id
        name
      }
    }
  }
}

Po połączeniu z filtrem zwracane są pasujące podelementy wraz z ich elementami nadrzędnymi:

query {
  boards(ids: 1234567890) {
    items_page(
      limit: 25
      hierarchy_scope_config: "allItems"
      query_params: {
        rules: [
          {
            column_id: "numbers"
            compare_value: [100]
            operator: greater_than
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Zapytania dotyczące kolumn podsumowujących

Pobieranie wartości kolumn podsumowujących

Domyślnie pole column_values nie zwraca wartości kolumn podsumowujących. API zwraca dla nich pustą tablicę.

Aby zwrócić wartości podsumowań, musisz przekazać argument capabilities: [CALCULATED]. Zostaną zwrócone zarówno wartości podsumowań, jak i wartości statyczne:

query {
  boards(ids: 1234567890) {
    items_page(limit: 10) {
      items {
        id
        name
        column_values(capabilities: [CALCULATED]) {
          id
          text
          value
          ... on NumbersValue {
            number
            is_leaf
          }
          ... on DateValue {
            date
            is_leaf
          }
          ... on TimelineValue {
            from
            to
            is_leaf
          }
          ... on BatteryValue {
            battery_value {
              key
              count
            }
            is_leaf
          }
        }
      }
    }
  }
}

Rozróżnianie wartości statycznych i obliczonych za pomocą is_leaf

Pole is_leaf występuje we wszystkich typach wartości kolumn na tablicach klasycznych i wielopoziomowych. Na tablicach wielopoziomowych z kolumnami podsumowującymi informuje, czy wartość jest statyczna (element nie ma elementów podrzędnych), czy obliczona (podsumowana na podstawie elementów podrzędnych):

query {
  items(ids: [1234567890]) {
    id
    name
    column_values(ids: ["numbers"], capabilities: [CALCULATED]) {
      ... on NumbersValue {
        number
        is_leaf
      }
    }
    subitems {
      id
      name
      column_values(ids: ["numbers"], capabilities: [CALCULATED]) {
        ... on NumbersValue {
          number
          is_leaf
        }
      }
    }
  }
}

{
  "data": {
    "items": [
      {
        "id": "1000000001",
        "name": "Campaign",
        "column_values": [
          {
            "number": 125,
            "is_leaf": false
          }
        ],
        "subitems": [
          {
            "id": "1000000002",
            "name": "Phase 1",
            "column_values": [
              {
                "number": 125,
                "is_leaf": false
              }
            ]
          },
          {
            "id": "1000000003",
            "name": "Task A",
            "column_values": [
              {
                "number": 100,
                "is_leaf": true
              }
            ]
          },
          {
            "id": "1000000004",
            "name": "Task B",
            "column_values": [
              {
                "number": 25,
                "is_leaf": true
              }
            ]
          }
        ]
      }
    ]
  }
}

W tym przykładzie dla elementów „Campaign” i „Phase 1” pole is_leaf ma wartość false - ich wartości (125) są sumą wartości elementów podrzędnych. „Task A” i „Task B” to elementy końcowe z wartościami statycznymi.

Pobieranie wartości podsumowania w kolumnie statusu

Kolumny statusu z podsumowaniem zwracają typ BatteryValue, a nie StatusValue. Dotyczy to wszystkich elementów, także końcowych:

query {
  items(ids: [1234567890]) {
    id
    name
    column_values(ids: ["status"], capabilities: [CALCULATED]) {
      id
      type
      ... on BatteryValue {
        battery_value {
          key
          count
        }
        is_leaf
      }
    }
  }
}

{
  "data": {
    "items": [
      {
        "id": "1000000001",
        "name": "Campaign",
        "column_values": [
          {
            "id": "status",
            "type": "status",
            "battery_value": [
              { "key": "0", "count": 1 },
              { "key": "1", "count": 1 }
            ],
            "is_leaf": false
          }
        ]
      }
    ]
  }
}

Tablica battery_value zawiera jeden wpis dla każdej etykiety statusu występującej wśród elementów podrzędnych. Każdy wpis zawiera key etykiety statusu (jej identyfikator lub indeks) oraz liczbę elementów z tym statusem w polu count.

Wyszukiwanie kolumn obsługujących podsumowania

Użyj argumentu capabilities w polu columns, aby filtrować kolumny obsługujące podsumowania:

query {
  boards(ids: 1234567890) {
    columns(capabilities: [CALCULATED]) {
      id
      title
      type
      capabilities {
        calculated {
          function
          calculated_type
        }
      }
    }
  }
}

{
  "data": {
    "boards": [
      {
        "columns": [
          {
            "id": "numbers",
            "title": "Budget",
            "type": "numbers",
            "capabilities": {
              "calculated": {
                "function": "SUM",
                "calculated_type": "numbers"
              }
            }
          },
          {
            "id": "status",
            "title": "Status",
            "type": "status",
            "capabilities": {
              "calculated": {
                "function": "COUNT_KEYS",
                "calculated_type": null
              }
            }
          },
          {
            "id": "timeline",
            "title": "Timeline",
            "type": "timeline",
            "capabilities": {
              "calculated": {
                "function": "MIN_MAX",
                "calculated_type": "timeline"
              }
            }
          }
        ]
      }
    ]
  }
}

Pobieranie metadanych kolumny podsumowującej

Pole capabilities w obiekcie Column zawiera metadane podsumowania, w tym używaną funkcję agregującą:

query {
  boards(ids: 1234567890) {
    columns(ids: "numbers") {
      title
      capabilities {
        calculated {
          function
          calculated_type
        }
      }
    }
  }
}

Pole function zwraca aktywną funkcję podsumowującą (np. SUM, MIN, MAX, MIN_MAX, COUNT_KEYS lub NONE). Pole calculated_type określa typ zwracanej wartości obliczonej (np. "numbers", "date", "timeline" lub null w przypadku statusu).

Tworzenie kolumn z funkcją podsumowania

Tworzenie kolumny z podsumowaniem

Na tablicach wielopoziomowych kolumny liczbowe, daty, osi czasu i statusu mają domyślnie włączone podsumowanie. Możesz jawnie wskazać używaną funkcję:

mutation {
  create_column(
    board_id: 1234567890
    title: "Budget"
    column_type: numbers
    capabilities: { calculated: { function: SUM } }
  ) {
    id
    title
  }
}

Tworzenie kolumny bez podsumowania

Aby utworzyć kolumnę na tablicy wielopoziomowej bez podsumowania, przekaż function: NONE:

mutation {
  create_column(
    board_id: 1234567890
    title: "Reference Number"
    column_type: numbers
    capabilities: { calculated: { function: NONE } }
  ) {
    id
    title
  }
}

Kolumny statusu używają typowanej mutacji

Kolumny statusu mają dedykowaną mutację create_status_column z argumentem capabilities, który przyjmuje typ StatusColumnCapabilitiesInput. Jedyną funkcją obsługującą podsumowanie statusu jest COUNT_KEYS.

mutation {
  create_status_column(
    board_id: 1234567890
    title: "Task Status"
    capabilities: { calculated: { function: COUNT_KEYS } }
    defaults: {
      labels: [
        { color: done_green, label: "Done", index: 0, is_done: true }
        { color: working_orange, label: "Working on it", index: 1 }
        { color: stuck_red, label: "Stuck", index: 2 }
      ]
    }
  ) {
    id
    title
  }
}

Działanie mutacji na kolumnach podsumowujących

Zapisywanie wartości w elementach końcowych

Mutacje dotyczące elementów końcowych (bez podelementów) działają standardowo. Wartość jest ustawiana bezpośrednio:

mutation {
  change_multiple_column_values(
    board_id: 1234567890
    item_id: 9876543210
    column_values: "{\"numbers\": \"100\"}"
  ) {
    id
  }
}

Zapisywanie wartości w elementach nadrzędnych (komórki obliczane)

Zmiana wartości statycznych na obliczane i odwrotnie

Po utworzeniu pierwszego podelementu danego elementu nadrzędnego:

1. Wartości statyczne elementu nadrzędnego zostają skopiowane do nowego podelementu, chyba że podano je jawnie.
2. Kolumny podsumowujące elementu nadrzędnego zaczynają zwracać wartości obliczone - sumę, wartość minimalną lub maksymalną albo liczbę elementów podrzędnych.
3. Kolejne podelementy powodują ponowne obliczenie podsumowań, ale nie kopiują wartości.

Usunięcie wszystkich podelementów elementu nadrzędnego zmienia komórki z powrotem na statyczne i pozwala edytować je bezpośrednio.

Uzyskaj pomoc

Jeśli masz pytania lub uwagi, wyślij zgłoszenie do pomocy technicznej. Możesz też opublikować wpis w społeczności deweloperów, gdzie doświadczony deweloper monday lub pracownik naszego zespołu pomoże Ci znaleźć odpowiedź.