Obiekt items_page reprezentuje stronę z elementami. Możesz użyć go jako zapytania do filtrowania danych z tablicy. Jako typ obiektu reprezentuje zestaw elementów zwróconych przez nadrzędny resolver.

Na każdej tablicy są dostępne zaawansowane filtry, które pozwalają szybko pobierać elementy spełniające określone kryteria. Możesz odtworzyć to działanie w API, używając obiektu items_page i dostosowanych parametrów filtrowania wyników.

Wraz z rozwojem platformy monday.com zmienia się też przydzielony limit elementów na każdej tablicy. Filtry te to jedyny sposób na pobieranie elementów z większych tablic bez przekraczania limitów i unikania przekroczenia limitu czasu. Nie możesz bowiem wysłać zapytania o wszystkie elementy na tablicy.

Dodatkowo filtry te umożliwiają bardziej precyzyjne określanie kryteriów, więc nie musisz niepotrzebnie wykorzystywać limitu złożoności na pobieranie zbędnych danych.

Zapytania

Pobieranie strony elementów

• Zwraca obiekt zawierający metadane dotyczące kolekcji elementów przefiltrowanych według określonych kryteriów
• Nie można wysłać zapytania do tego obiektu bezpośrednio z poziomu głównego. Musi być zagnieżdżony w zapytaniu boards lub groups

query {
  boards(ids: 1234567890) {
    items_page(
      limit: 1
      query_params: {
        rules: [
          {
            column_id: "status"
            compare_value: [1]
          }
        ]
        operator: and
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}

Argumenty

Argument	Typ	Opis	Akceptowane wartości
cursor	String	Nieprzejrzysty token reprezentujący pozycję w zestawie wyników, od której mają być pobierane elementy. Użyj go do stronicowania dużych zestawów wyników. Pamiętaj: nie możesz użyć query_params i cursor w tym samym żądaniu. Zalecamy użycie query_params w pierwszym żądaniu, a cursor w kolejnych żądaniach stronicowanych.
hierarchy_scope_config	String	Określa sposób obsługi hierarchii elementów podczas filtrowania wyników. Użyj parentItems (wartość domyślna), aby uwzględnić elementy nadrzędne powiązane z dopasowaniem, lub allItems, aby zwrócić tylko elementy bezpośrednio spełniające kryteria filtra.	allItems parentItems
limit	Int!	Liczba elementów do zwrócenia. Wartość domyślna to 25, a maksymalna - 500.
query_params	ItemsQuery	Zestaw parametrów służących do filtrowania i sortowania oraz określania zakresu zapytania boards. Użyj ich, aby dostosować wyniki do konkretnych kryteriów. Pamiętaj: nie możesz użyć query_params i cursor w tym samym żądaniu. Zalecamy użycie query_params w pierwszym żądaniu, a cursor w kolejnych żądaniach stronicowanych.

Pola

Pole	Typ	Opis
cursor	String	Nieprzejrzysty kursor reprezentujący pozycję na liście za ostatnim zwróconym elementem. Użyj go do stronicowania i pobierania kolejnego zestawu elementów. Jeśli wartość kursora to null, nie ma więcej elementów do pobrania.
items	[Item!]!	Element odpowiadający kursorowi.

Stronicowanie oparte na kursorze za pomocą next_items_page

items_page korzysta ze stronicowania opartego na kursorze, aby zwracać mniejsze zestawy elementów z dużego zbioru danych. Podczas wysyłania zapytania do items_page możesz zwrócić argument cursor, który wskazuje następną stronę elementów.

Po zwróceniu kursora możesz kontynuować stronicowanie zbioru danych za pomocą obiektu next_items_page. Ten obiekt pozwala pobrać następną stronę elementów bez ponoszenia kosztu złożoności związanego z zagnieżdżeniem items_page w zapytaniu boards. Przyjmuje argument cursor, dzięki czemu możesz wskazać, od którego miejsca w zbiorze danych rozpocząć pobieranie.

Przykłady zastosowań

Przyjrzyjmy się kilku przykładom, które pokażą, jak i kiedy używać obiektu items_page do filtrowania i sortowania elementów.

Filtrowanie elementów według nazwy

Chcesz pobrać z tablicy 1234567890 tylko elementy o nazwie „New item”.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "name"
            compare_value: ["New item"]
          }
        ]
      }
    ) {
      cursor
      items {
        id
      }
    }
  }
}

Filtrowanie elementów przypisanych do Ciebie, które mają zaznaczone pole wyboru

Chcesz pobrać z tablicy 1234567890 tylko elementy przypisane do Ciebie, w których kolumna pola wyboru jest zaznaczona.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "people"
            compare_value: ["assigned_to_me"]
            operator: any_of
          }
          {
            column_id: "check"
            compare_value: null
            operator: is_not_empty
          }
        ]
        operator: and
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}

Filtrowanie elementów według określonych wartości kolumn statusu i osób

Chcesz pobrać tylko elementy przypisane do Osoby 1 (ID#76543210) lub Osoby 7 (ID#01234567). Potrzebujesz też tylko elementów oznaczonych jako Gotowe lub Usunięte w kolumnie statusu na tablicy 1234567890.

W przypadku kolumny osób możesz filtrować dane na dwa sposoby:

1. Przekaż imię lub imiona jako ciąg znaków z operatorem contains_text.
2. Użyj operatora any_of i przekaż identyfikatory jako ciąg znaków w następującym formacie: "person-XXXXXXXX".

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "people"
            compare_value: ["Person 1", "Person 2"]
            operator: contains_text
          }
          {
            column_id: "status"
            compare_value: [1, 0]
          }
        ]
        operator: and
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "people"
            compare_value: ["person-87654321", "person-12345678"]
            operator: any_of
          }
          {
            column_id: "status"
            compare_value: [1, 0]
          }
        ]
        operator: and
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}

Filtrowanie elementów według określonych wartości kolumny daty, w konkretnej grupie i nieprzypisanych do Ciebie

Chcesz pobrać elementy przypisane do wszystkich osób poza Tobą, z datą wydania przypadającą między 1 a 30 czerwca 2023 roku, które należą do grupy Finished na tablicy 1234567890.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: ["2023-06-01", "2023-06-30"]
            operator: between
          }
          {
            column_id: "group"
            compare_value: ["new_group12345"]
            operator: any_of
          }
          {
            column_id: "people"
            compare_value: ["assigned_to_me"]
            operator: not_any_of
          }
        ]
        operator: and
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}

Sortowanie elementów według typu kolumny

Możesz też użyć obiektu items_page, aby sortować elementy według typu kolumny.

Załóżmy, że chcesz pobrać elementy z tablicy i posortować je według kolumny z nazwą elementu. Poniższe zapytanie zwróci pierwsze 25 elementów na tablicy 1234567890 w kolejności rosnącej (alfabetycznie) w każdej grupie.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        order_by: [
          {
            column_id: "name"
          }
        ]
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}