Dokumentacja dla programistów

Pobieranie strony elementów według wartości kolumn

Dokumentacja API (rdzeń)Dokumentacja API

Aktualizacja 2026-09-06

Elementy to podstawowe obiekty na platformie monday.com, które przechowują dane na tablicy. Aby lepiej zrozumieć działanie platformy, wyobraź sobie, że każda tablica jest tabelą, a element to pojedynczy wiersz w tej tabeli. Wypełnij ten wiersz dowolnymi informacjami, a otrzymasz element!

Zapytania

Pobieranie strony elementów według wartości kolumn

Wymagany zakres uprawnień:boards:read
Zwraca tablicę zawierającą metadane jednego lub wielu wskazanych elementów
Można je wywołać tylko bezpośrednio na poziomie głównym; nie można go zagnieżdżać w innym zapytaniu

Obiekt items_page_by_column_values pozwala łączyć wartości z wielu kolumn, przekazując tablicę. Jeśli nie określono inaczej, w przypadku większości wartości kolumn używany jest operator ANY_OF. Zwracane są tylko elementy, które pasują do wszystkich podanych wartości kolumn.

Poniższy przykład kodu zwraca 50 elementów z tablicy 1234567890, które mają wartość „This is a text column” w kolumnie tekstowej ORAZ wartość „United States” lub „Israel” w kolumnie kraju.

query {
  items_page_by_column_values(
    limit: 50
    board_id: 1234567890
    columns: [
      {
        column_id: "text"
        column_values: ["This is a text column"]
      }
      {
        column_id: "country"
        column_values: ["US", "IL"]
      }
    ]
  ) {
    cursor
    items {
      id
      name
    }
  }
}

Zapytanie zwróci również wartość kursora, która wskazuje pozycję w zbiorze danych po zwróceniu 50 elementów. Możesz użyć tego ciągu, aby pobrać następne 50 pasujących elementów ze zbioru danych za pomocą obiektu next_items_page. Po otrzymaniu kolejnej wartości kursora możesz kontynuować stronicowanie aż do pobrania całego zbioru danych.

query {
  next_items_page(
    cursor: "MSw5NzI4MDA5MDAsaV9YcmxJb0p1VEdYc1VWeGlxeF9kLDg4MiwzNXw0MTQ1NzU1MTE5"
    limit: 50
  ) {
    cursor
    items {
      id
      name
    }
  }
}

Argumenty

Argument	Typ	Opis	Akceptowane wartości
board_id	`ID!`	Identyfikator tablicy, z której mają zostać zwrócone elementy.
columns	`[ItemsPageByColumnValuesQuery!]`	Jedna lub więcej kolumn i ich wartości, według których ma odbywać się wyszukiwanie. Nie można używać `columns` i `cursor` w tym samym żądaniu. Zalecamy używać `columns` w pierwszym żądaniu, a `cursor` w kolejnych żądaniach stronicowanych.
cursor	`String`	Nieprzejrzysty token określający pozycję w zestawie wyników, od której należy wznowić pobieranie elementów. Użyj go, aby stronicować duże zestawy wyników. Nie można używać `columns` i `cursor` w tym samym żądaniu. Zalecamy używać `columns` w pierwszym żądaniu, a `cursor` w kolejnych żądaniach stronicowanych.
hierarchy_scope_config	`String`	Określa sposób uwzględniania hierarchii elementów podczas filtrowania wyników. Użyj `parentItems` (wartość domyślna), aby uwzględnić elementy nadrzędne powiązane z wynikiem, albo `allItems`, aby zwrócić tylko elementy, które bezpośrednio pasują do filtra.	`allItems` `parentItems`
limit	`Int!`	Liczba elementów do zwrócenia. Wartość domyślna to 25, a maksymalna to 500.

Pola

Pole	Typ	Opis
cursor	`String`	Nieprzejrzysty kursor wskazujący pozycję na liście po ostatnim zwróconym elemencie. Podczas stronicowania elementów użyj tego kursora, aby pobrać następną partię. Jeśli kursor ma wartość `null`, nie ma już elementów do pobrania.
items	`[Item!]!`	Elementy powiązane z kursorem.

Obsługiwane i nieobsługiwane kolumny

Ten obiekt obsługuje określone typy kolumn, a w przypadku niektórych obsługa jest ograniczona.

Obsługiwane kolumny

Poniższe kolumny są obsługiwane w zapytaniach items_page_by_column_values. Jeśli poniżej nie określono inaczej, w przypadku większości kolumn możesz przekazać wartość "" lub null, aby zwrócić elementy z pustymi wartościami w kolumnach.

Typ kolumny	Uwagi
Pole wyboru	Przekaż wartość true (np. `["1", "t", "true"]`) lub false (np. `["false", "f", null]`) jako ciąg znaków. Jeśli przekażesz kilka wartości w zapytaniu, wyniki zostaną zwrócone tylko dla ostatniej wartości. Na przykład:* `column_id: "check", column_values: ["1", "false", "f", "t"]` zwróci tylko wartości true.
Kraj	Przekaż pełną nazwę kraju w postaci ciągu znaków, taką jak wyświetlana w interfejsie. Możesz też użyć kodu kraju zapisanego wielkimi literami. Na przykład:* `{column_id: "country", column_values: [null, "United States", "IL"]}`
Data	Przekaż tylko jedną wartość w postaci ciągu znaków w formacie ISO-2 (RRRR-MM-DD), z godziną lub bez. Pamiętaj, że wyszukiwanie według godziny nie jest obsługiwane. Na przykład:* `{column_id: "date", column_values: ["2023-08-01"]}`
Lista rozwijana	Przekaż tylko jedną częściową lub pełną wartość w postaci ciągu znaków, aby dopasować etykietę z listy rozwijanej. Na przykład:* `{column_id: "dropdown", column_values: ["y Labe"]}` lub `{column_id: "dropdown", column_values: ["My Label"]}`
E-mail	Przekaż wartości tekstu wyświetlanego (etykiety) jako ciągi znaków. Pamiętaj, że ta kolumna dokładnie dopasowuje całą wartość tekstową etykiety. Na przykład:* `{column_id: "email", column_values: ["test@gmail.com", "test@monday.com", null]}` lub `{column_id: "email", column_values: ["Home email", "Work email", ""]}`
Godzina	Przekaż godzinę w formacie 24-godzinnym, z dwukropkiem lub bez niego, albo jedną z poniższych predefiniowanych wartości w postaci ciągu znaków: `MORNING` (6:00-12:00) `AFTERNOON`(12:00-16:00) `EVENING`(16:00-20:00) `NIGHT`(20:00-6:00) Pamiętaj, że podanie dokładnej godziny służy wyłącznie do dopasowania jej do jednej z predefiniowanych wartości. Nie zwróci tylko wyników z tą konkretną godziną.Na przykład: `{column_id: "hour", column_values: ["12:30", "EVENING", "0500", null]}` (zwraca wszystkie elementy z godzinami z zakresu popołudniowego, wieczornego lub porannego, a także elementy z pustymi wartościami)
Łącze	Przekaż adres łącza lub jego etykietę w postaci ciągu znaków, tak jak są wyświetlane w interfejsie. Jeśli podano zarówno łącze, jak i etykietę, użyj wartości etykiety. Na przykład:* `{column_id: "link", column_values: ["https://www.google.com", "Link 1"}`
Długi tekst	Przekaż całą wartość tekstową jako ciąg znaków. Ta kolumna wyszukuje dokładne dopasowanie całej wartości tekstowej. Na przykład:* `{column_id: "long_text", column_values: ["", "This is the entire value of a long text column. :)"]}`
Liczby	Przekaż wartość liczbową jako ciąg znaków. Na przykład:* `{column_id: "numbers", column_values: ["", "-42"]}`
Osoby	Przekaż nazwę wyświetlaną użytkownika lub jego identyfikator jako ciąg znaków. Na przykład:* `{column_id: "people", column_values: ["565481", "Test user", null]}`
Telefon	Przekaż tablicę nazw krajów lub ich kodów jako ciągi znaków, aby zwrócić wszystkie prawidłowo sformatowane numery odpowiadające tym krajom. Możesz też przekazać jeden pełny lub częściowy numer bez żadnych znaków, aby zwrócić wszystkie elementy zawierające podaną wartość. Na przykład:* `{column_id: "phone", column_values: ["US", null, "Israel"]}` lub `{column_id: "phone", column_values: ["665"]}` (zwraca wszystkie elementy zawierające numer telefonu z ciągiem 665)
Status	Przekaż tekst etykiety jako ciąg znaków, dokładnie tak, jak jest wyświetlany w interfejsie. Na przykład:* `{column_id: "status", column_values: ["Done", "Working on it", null]}`
Tekst	Przekaż całą wartość tekstową jako ciąg znaków. Ta kolumna wyszukuje dokładne dopasowanie całej wartości tekstowej bez rozróżniania wielkości liter. Na przykład:* `{column_id: "text", column_values: ["This is a text column.", null]}`
Oś czasu	Przekaż tylko jedną wartość w postaci ciągu znaków w formacie ISO-2 (RRRR-MM-DD), aby dokładnie dopasować datę rozpoczęcia osi czasu. Na przykład:* `{column_id: "timeline", column_values: ["2023-07-01"]}` lub `{column_id: "timeline", column_values: [""]}`
Zegar światowy	Przekaż wartość etykiety jako ciąg znaków, tak jak jest wyświetlana w interfejsie. Na przykład:* `{column_id: "world_clock", column_values: ["", "Central"]}`

Nieobsługiwane kolumny

Poniższe kolumny nie są obsługiwane w zapytaniach items_page_by_column_values. Jeśli użyjesz w zapytaniu nieobsługiwanej kolumny, otrzymasz błąd.

Numer automatyczny
Wybór koloru
Połącz tablice
Dziennik utworzenia
Plik
Formuła
Identyfikator elementu
Ostatnia aktualizacja
Lokalizacja
Odbicie
Ocena
Tagi
Śledzenie czasu
Głosowanie

Mam problem z tym tematem Źródło: developer.monday.com