---

Lista rekordów

Zapytanie todos pozwala na pobranie rekordów z Blue z kompleksowymi opcjami filtrowania, sortowania i paginacji. Możesz zapytać o rekordy w różnych firmach, projektach lub filtrować według konkretnych kryteriów, takich jak przypisani użytkownicy, tagi i daty.

Podstawowy przykład

Lista wszystkich rekordów w firmie z minimalnymi parametrami:

query ListRecords {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
      }
    ) {
      items {
        id
        title
        done
        duedAt
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

Zaawansowany przykład

Zapytanie o rekordy z kompleksowym filtrowaniem, sortowaniem i wyborem pól:

query ListRecordsAdvanced {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
        projectIds: ["project_456", "project_789"]
        assigneeIds: ["user_123"]
        tagIds: ["tag_priority", "tag_urgent"]
        showCompleted: false
        dueStart: "2025-01-01T00:00:00Z"
        dueEnd: "2025-12-31T23:59:59Z"
        search: "product launch"
        excludeArchivedProjects: true
        fields: [
          {
            type: "CUSTOM_FIELD"
            customFieldId: "cf_status_123"
            customFieldType: "SELECT_SINGLE"
            values: ["In Progress", "Review"]
            op: "IN"
          }
        ]
        op: "AND"
      }
      sort: [duedAt_ASC, position_ASC]
      limit: 50
      skip: 0
    ) {
      items {
        id
        uid
        position
        title
        text
        html
        startedAt
        duedAt
        timezone
        color
        cover
        done
        archived
        createdAt
        updatedAt
        commentCount
        checklistCount
        checklistCompletedCount
        isRepeating
        todoList {
          id
          title
        }
        users {
          id
          name
          email
        }
        tags {
          id
          title
          color
        }
        customFields {
          id
          title
          type
          value
        }
        createdBy {
          id
          name
        }
      }
      pageInfo {
        totalPages
        totalItems
        page
        perPage
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

Parametry wejściowe

TodosFilter

Parametr	Typ	Wymagany	Opis
companyIds	[String!]!	✅ Tak	Identyfikatory firm lub slug do zapytania
projectIds	[String!]	Nie	Filtruj według konkretnych identyfikatorów projektów lub slugów
todoIds	[String!]	Nie	Pobierz konkretne zadania według ich identyfikatorów
assigneeIds	[String!]	Nie	Filtruj według identyfikatorów przypisanych użytkowników
tagIds	[String!]	Nie	Filtruj według identyfikatorów tagów
tagColors	[String!]	Nie	Filtruj według kolorów tagów (format hex)
tagTitles	[String!]	Nie	Filtruj według tytułów tagów
todoListIds	[String!]	Nie	Filtruj według identyfikatorów list zadań
todoListTitles	[String!]	Nie	Filtruj według tytułów list zadań
done	Boolean	Nie	Filtruj według statusu ukończenia (przestarzałe, użyj showCompleted)
showCompleted	Boolean	Nie	Pokaż/ukryj ukończone zadania (domyślnie: prawda)
startedAt	DateTime	Nie	Filtruj według daty rozpoczęcia
duedAt	DateTime	Nie	Filtruj według dokładnej daty wykonania
dueStart	DateTime	Nie	Początek zakresu daty wykonania (włącznie)
dueEnd	DateTime	Nie	Koniec zakresu daty wykonania (włącznie)
search	String	Nie	Wyszukiwanie w tytule i treści tekstu
q	String	Nie	Alternatywny parametr wyszukiwania (taki sam jak search)
excludeArchivedProjects	Boolean	Nie	Wyklucz zadania z archiwalnych projektów
coordinates	JSON	Nie	Filtr geograficzny dla widoku mapy (współrzędne wielokąta)
fields	JSON	Nie	Filtry pól niestandardowych (zobacz zaawansowane filtrowanie)
op	FilterLogicalOperator	Nie	Operator logiczny dla filtrów pól (AND/OR)

Parametry zapytania

Parametr	Typ	Wymagany	Opis
filter	TodosFilter!	✅ Tak	Kryteria filtrowania dla zapytania
sort	[TodosSort!]	Nie	Kolejność sortowania (domyślnie: pusta tablica)
limit	Int	Nie	Liczba elementów na stronę (domyślnie: 20, maks: 500)
skip	Int	Nie	Liczba elementów do pominięcia dla paginacji (domyślnie: 0)

Wartości TodosSort

Wartość	Opis
assignees_ASC	Sortuj według nazw przypisanych użytkowników rosnąco
assignees_DESC	Sortuj według nazw przypisanych użytkowników malejąco
createdAt_ASC	Sortuj według daty utworzenia rosnąco (najstarsze pierwsze)
createdAt_DESC	Sortuj według daty utworzenia malejąco (najświeższe pierwsze)
createdBy_ASC	Sortuj według nazwiska twórcy rosnąco
createdBy_DESC	Sortuj według nazwiska twórcy malejąco
duedAt_ASC	Sortuj według daty wykonania rosnąco (najwcześniejsze pierwsze)
duedAt_DESC	Sortuj według daty wykonania malejąco (najpóźniejsze pierwsze)
position_ASC	Sortuj według pozycji rosnąco (domyślna kolejność listy)
position_DESC	Sortuj według pozycji malejąco
startedAt_ASC	Sortuj według daty rozpoczęcia rosnąco
startedAt_DESC	Sortuj według daty rozpoczęcia malejąco
title_ASC	Sortuj według tytułu alfabetycznie rosnąco
title_DESC	Sortuj według tytułu alfabetycznie malejąco
todoListPosition_ASC	Sortuj według pozycji listy zadań rosnąco
todoListPosition_DESC	Sortuj według pozycji listy zadań malejąco
todoListTitle_ASC	Sortuj według tytułu listy zadań rosnąco
todoListTitle_DESC	Sortuj według tytułu listy zadań malejąco
todoTags_ASC	Sortuj według tagów rosnąco
todoTags_DESC	Sortuj według tagów malejąco

Wartości FilterLogicalOperator

Wartość	Opis
AND	Wszystkie warunki muszą być spełnione
OR	Jakikolwiek warunek musi być spełniony

Filtrowanie pól niestandardowych

Parametr fields wspiera zaawansowane filtrowanie według pól niestandardowych:

{
  "fields": [
    {
      "type": "CUSTOM_FIELD",
      "customFieldId": "cf_123",
      "customFieldType": "SELECT_SINGLE",
      "values": ["Option1", "Option2"],
      "op": "IN"
    }
  ]
}

Struktura filtru pola niestandardowego

Pole	Typ	Opis
type	String	Musi być "CUSTOM_FIELD"
customFieldId	String	ID pola niestandardowego
customFieldType	String	Typ pola niestandardowego
values	[String!]	Wartości do filtrowania
op	String	Operator porównania (IN, NOT_IN, EQ, itd.)

Obsługiwane typy pól niestandardowych

• Pola tekstowe: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
• Pola numeryczne: CURRENCY, NUMBER, FORMULA
• Pola wyboru: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
• Pola referencyjne: REFERENCE, LOOKUP
• Pola daty: DATE

Pola odpowiedzi

TodosResult

Pole	Typ	Opis
items	[Todo!]!	Tablica rekordów zadań
pageInfo	PageInfo!	Metadane paginacji

PageInfo

Pole	Typ	Opis
totalPages	Int	Całkowita liczba dostępnych stron
totalItems	Int	Całkowita liczba elementów na wszystkich stronach
page	Int	Numer bieżącej strony (obliczany na podstawie skip/limit)
perPage	Int	Liczba elementów na stronę
hasNextPage	Boolean!	Czy jest następna strona
hasPreviousPage	Boolean!	Czy jest poprzednia strona

Pola zadania

Pole	Typ	Opis
id	ID!	Unikalny identyfikator
uid	String!	Przyjazny dla użytkownika unikalny identyfikator
position	Float!	Pozycja na liście
title	String!	Tytuł zadania
text	String!	Treść w formacie tekstowym
html	String!	Treść w formacie HTML
startedAt	DateTime	Data/godzina rozpoczęcia
duedAt	DateTime	Data/godzina wykonania
timezone	String	Strefa czasowa dla dat
color	String	Wskaźnik koloru wizualnego
cover	String	URL do obrazu okładki
done	Boolean!	Status ukończenia
archived	Boolean!	Status archiwizacji
createdAt	DateTime!	Znacznik czasu utworzenia
updatedAt	DateTime!	Znacznik czasu ostatniej aktualizacji
commentCount	Int!	Liczba komentarzy
checklistCount	Int!	Całkowita liczba elementów listy kontrolnej
checklistCompletedCount	Int!	Ukończone elementy listy kontrolnej
isRepeating	Boolean!	Czy zadanie jest cykliczne
isRead	Boolean	Status przeczytania dla bieżącego użytkownika
isSeen	Boolean	Status widzenia dla bieżącego użytkownika
todoList	TodoList!	Lista nadrzędna zadań
users	[User!]!	Przypisani użytkownicy
tags	[Tag!]!	Powiązane tagi
checklists	[Checklist!]!	Powiązane listy kontrolne
createdBy	User	Użytkownik, który utworzył zadanie
customFields	[CustomField!]!	Wartości pól niestandardowych
dependOn	[Todo!]	Zadania blokujące (zależności)
dependBy	[Todo!]	Zadania zależne (blokowane przez to)
timeTracking	TimeTracking	Dane śledzenia czasu

Wymagane uprawnienia

Użytkownicy muszą mieć odpowiedni dostęp do zapytania o rekordy:

Typ dostępu	Wymagania
Company Access	User must be a member of the company
Project Access	User must have access to specific projects (if filtering by project)
Todo Visibility	Depends on user's role and permissions:
- VIEW_ONLY	Can view all accessible todos
- COMMENT_ONLY	Can view all accessible todos
- CLIENT	May be restricted to assigned todos only
- MEMBER	Can view all project todos
- ADMIN	Can view all project todos
- OWNER	Can view all company todos

Specjalne ograniczenia:

• Użytkownicy z uprawnieniem showOnlyAssignedTodos mogą widzieć tylko zadania przypisane do nich
• Ukryte listy zadań (na podstawie konfiguracji roli) są automatycznie wykluczane
• Uprawnienia oparte na tagach mogą dodatkowo filtrować wyniki

Odpowiedzi na błędy

Typowe błędy

Zapytanie obsługuje błędy w sposób elegancki i zwraca puste wyniki dla:

• Nieprawidłowych identyfikatorów firm
• Niedostępnych projektów
• Scenariuszy odmowy dostępu

W przypadku poważnych błędów mogą być zwracane błędy GraphQL:

{
  "errors": [{
    "message": "Query timeout exceeded",
    "extensions": {
      "code": "QUERY_TIMEOUT"
    }
  }]
}

Ważne uwagi

Wydajność

• Domyślny limit: 20 elementów na stronę (automatycznie stosowane, jeśli nie określono)
• Maksymalny limit: 500 elementów na żądanie (automatycznie ograniczone)
• Optymalizacja: Zapytania używają zoptymalizowanych złączeń z STRAIGHT_JOIN dla najlepszej wydajności
• Indeksowanie: Powszechnie używane pola filtrów są indeksowane dla szybkiego zapytania
• Pola niestandardowe: Rozbudowane wsparcie dla filtrowania pól niestandardowych z minimalnym wpływem na wydajność
• Zapytania geograficzne: Obsługuje filtrowanie współrzędnych opartych na wielokącie dla widoków map

Filtrowanie dat

• Zakresy dat są włącznie
• Obsługuje nakładające się zakresy dat (zadania, które zaczynają się lub kończą w tym zakresie)
• Daty null są obsługiwane w sposób elegancki (zadania bez dat wykonania nie będą pasować do filtrów dat)
• Wszystkie daty powinny być w formacie ISO 8601

Zachowanie wyszukiwania

• Wyszukiwanie jest nieczułe na wielkość liter
• Wyszukuje zarówno w tytule, jak i w treści tekstu
• Obsługuje częściowe dopasowanie słów
• Specjalne znaki są obsługiwane odpowiednio

Strategia paginacji

• Użyj skip i limit dla paginacji opartej na przesunięciu
• Oblicz bieżącą stronę: page = Math.floor(skip / limit) + 1
• Dla dużych zbiorów danych rozważ użycie filtrów, aby zmniejszyć rozmiar wyników
• Zawsze sprawdzaj hasNextPage przed zwiększeniem skip

Powiązane punkty końcowe

• Utwórz rekord: Użyj mutacji createTodo, aby utworzyć nowe rekordy
• Zaktualizuj rekord: Użyj mutacji updateTodo, aby zmodyfikować rekordy
• Usuń rekord: Użyj mutacji deleteTodo, aby usunąć rekordy
• Lista pól niestandardowych: Zapytaj dostępne pola niestandardowe do filtrowania
• Lista projektów: Zapytaj dostępne projekty do filtrowania