Datensätze auflisten

Abfragen und Filtern von Datensätzen (To-dos) in Blue mit leistungsstarken Such- und Paginierungsoptionen.

Datensätze auflisten

Die To-dos-Abfrage ermöglicht es Ihnen, Datensätze aus Blue mit umfassenden Filter-, Sortier- und Paginierungsoptionen abzurufen. Sie können Datensätze über Unternehmen, Projekte abfragen oder nach spezifischen Kriterien wie Zuweisungen, Tags und Daten filtern.

Einfaches Beispiel

Listen Sie alle Datensätze in einem Unternehmen mit minimalen Parametern auf:

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

Fortgeschrittenes Beispiel

Abfragen von Datensätzen mit umfassenden Filter-, Sortier- und Feldauswahlmöglichkeiten:

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
      }
    }
  }
}

Eingabeparameter

TodosFilter

Parameter	Typ	Erforderlich	Beschreibung
`companyIds`	[String!]!	✅ Ja	Unternehmens-IDs oder Slugs, von denen abgefragt werden soll
`projectIds`	[String!]	Nein	Filtern nach spezifischen Projekt-IDs oder Slugs
`todoIds`	[String!]	Nein	Abrufen spezifischer To-dos nach ihren IDs
`assigneeIds`	[String!]	Nein	Filtern nach zugewiesenen Benutzer-IDs
`tagIds`	[String!]	Nein	Filtern nach Tag-IDs
`tagColors`	[String!]	Nein	Filtern nach Tagfarben (Hex-Format)
`tagTitles`	[String!]	Nein	Filtern nach Tagtiteln
`todoListIds`	[String!]	Nein	Filtern nach To-do-Listen-IDs
`todoListTitles`	[String!]	Nein	Filtern nach To-do-Listen-Titeln
`done`	Boolean	Nein	Filtern nach Abschlussstatus (veraltet, verwenden Sie showCompleted)
`showCompleted`	Boolean	Nein	Abgeschlossene To-dos anzeigen/ausblenden (Standard: true)
`startedAt`	DateTime	Nein	Filtern nach Startdatum
`duedAt`	DateTime	Nein	Filtern nach genauem Fälligkeitsdatum
`dueStart`	DateTime	Nein	Beginn des Fälligkeitsdatumsbereichs (einschließlich)
`dueEnd`	DateTime	Nein	Ende des Fälligkeitsdatumsbereichs (einschließlich)
`search`	String	Nein	Suche im Titel und im Textinhalt
`q`	String	Nein	Alternativer Suchparameter (gleich wie Suche)
`excludeArchivedProjects`	Boolean	Nein	To-dos aus archivierten Projekten ausschließen
`coordinates`	JSON	Nein	Geo-räumlicher Filter für die Kartenansicht (Polygonkoordinaten)
`fields`	JSON	Nein	Benutzerdefinierte Feldfilter (siehe erweiterte Filterung)
`op`	FilterLogicalOperator	Nein	Logischer Operator für Feldfilter (UND/ODER)

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
`filter`	TodosFilter!	✅ Ja	Filterkriterien für die Abfrage
`sort`	[TodosSort!]	Nein	Sortierreihenfolge (Standard: leeres Array)
`limit`	Int	Nein	Anzahl der Elemente pro Seite (Standard: 20, max: 500)
`skip`	Int	Nein	Anzahl der Elemente, die für die Paginierung übersprungen werden sollen (Standard: 0)

TodosSort-Werte

Wert	Beschreibung
`assignees_ASC`	Nach den Namen der Zuweisenden aufsteigend sortieren
`assignees_DESC`	Nach den Namen der Zuweisenden absteigend sortieren
`createdAt_ASC`	Nach dem Erstellungsdatum aufsteigend sortieren (älteste zuerst)
`createdAt_DESC`	Nach dem Erstellungsdatum absteigend sortieren (neueste zuerst)
`createdBy_ASC`	Nach dem Namen des Erstellers aufsteigend sortieren
`createdBy_DESC`	Nach dem Namen des Erstellers absteigend sortieren
`duedAt_ASC`	Nach dem Fälligkeitsdatum aufsteigend sortieren (früheste zuerst)
`duedAt_DESC`	Nach dem Fälligkeitsdatum absteigend sortieren (späteste zuerst)
`position_ASC`	Nach der Position aufsteigend sortieren (Standardlistenreihenfolge)
`position_DESC`	Nach der Position absteigend sortieren
`startedAt_ASC`	Nach dem Startdatum aufsteigend sortieren
`startedAt_DESC`	Nach dem Startdatum absteigend sortieren
`title_ASC`	Nach dem Titel alphabetisch aufsteigend sortieren
`title_DESC`	Nach dem Titel alphabetisch absteigend sortieren
`todoListPosition_ASC`	Nach der Position der To-do-Liste aufsteigend sortieren
`todoListPosition_DESC`	Nach der Position der To-do-Liste absteigend sortieren
`todoListTitle_ASC`	Nach dem Titel der To-do-Liste aufsteigend sortieren
`todoListTitle_DESC`	Nach dem Titel der To-do-Liste absteigend sortieren
`todoTags_ASC`	Nach Tags aufsteigend sortieren
`todoTags_DESC`	Nach Tags absteigend sortieren

FilterLogicalOperator-Werte

Wert	Beschreibung
`AND`	Alle Bedingungen müssen übereinstimmen
`OR`	Eine beliebige Bedingung muss übereinstimmen

Benutzerdefinierte Feldfilterung

Der fields Parameter unterstützt erweiterte Filterung nach benutzerdefinierten Feldern:

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

Struktur des benutzerdefinierten Feldfilters

Feld	Typ	Beschreibung
`type`	String	Muss "CUSTOM_FIELD" sein
`customFieldId`	String	ID des benutzerdefinierten Feldes
`customFieldType`	String	Typ des benutzerdefinierten Feldes
`values`	[String!]	Werte, nach denen gefiltert werden soll
`op`	String	Vergleichsoperator (IN, NOT_IN, EQ usw.)

Unterstützte benutzerdefinierte Feldtypen

Textfelder: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
Numerische Felder: CURRENCY, NUMBER, FORMULA
Auswahlfelder: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
Referenzfelder: REFERENCE, LOOKUP
Datumsfelder: DATE

Antwortfelder

TodosResult

Feld	Typ	Beschreibung
`items`	[Todo!]!	Array von To-do-Datensätzen
`pageInfo`	PageInfo!	Paginierungsmetadaten

PageInfo

Feld	Typ	Beschreibung
`totalPages`	Int	Gesamtanzahl der verfügbaren Seiten
`totalItems`	Int	Gesamtanzahl der Elemente über alle Seiten
`page`	Int	Aktuelle Seitennummer (berechnet aus skip/limit)
`perPage`	Int	Anzahl der Elemente pro Seite
`hasNextPage`	Boolean!	Ob es eine nächste Seite gibt
`hasPreviousPage`	Boolean!	Ob es eine vorherige Seite gibt

To-do-Felder

Feld	Typ	Beschreibung
`id`	ID!	Eindeutiger Bezeichner
`uid`	String!	Benutzerfreundlicher eindeutiger Bezeichner
`position`	Float!	Position in der Liste
`title`	String!	To-do-Titel
`text`	String!	Klartextinhalt
`html`	String!	HTML-formatierter Inhalt
`startedAt`	DateTime	Startdatum/-uhrzeit
`duedAt`	DateTime	Fälligkeitsdatum/-uhrzeit
`timezone`	String	Zeitzone für Daten
`color`	String	Visueller Farbindikator
`cover`	String	URL des Titelbildes
`done`	Boolean!	Abschlussstatus
`archived`	Boolean!	Archivstatus
`createdAt`	DateTime!	Erstellungszeitstempel
`updatedAt`	DateTime!	Zeitstempel der letzten Aktualisierung
`commentCount`	Int!	Anzahl der Kommentare
`checklistCount`	Int!	Gesamtanzahl der Checklistenpunkte
`checklistCompletedCount`	Int!	Abgeschlossene Checklistenpunkte
`isRepeating`	Boolean!	Ob das To-do wiederkehrend ist
`isRead`	Boolean	Lesestatus für den aktuellen Benutzer
`isSeen`	Boolean	Gesehen-Status für den aktuellen Benutzer
`todoList`	TodoList!	Übergeordnete To-do-Liste
`users`	[User!]!	Zugewiesene Benutzer
`tags`	[Tag!]!	Zugeordnete Tags
`checklists`	[Checklist!]!	Zugeordnete Checklisten
`createdBy`	User	Benutzer, der das To-do erstellt hat
`customFields`	[CustomField!]!	Werte der benutzerdefinierten Felder
`dependOn`	[Todo!]	Blockierende To-dos (Abhängigkeiten)
`dependBy`	[Todo!]	Abhängige To-dos (von diesem blockiert)
`timeTracking`	TimeTracking	Zeitverfolgungsdaten

Erforderliche Berechtigungen

Benutzer müssen über die entsprechenden Zugriffsrechte verfügen, um Datensätze abzufragen:

Zugriffstyp	Anforderungen
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

Besondere Einschränkungen:

Benutzer mit showOnlyAssignedTodos Berechtigung können nur To-dos sehen, die ihnen zugewiesen sind
Versteckte To-do-Listen (basierend auf der Rollenkonfiguration) werden automatisch ausgeschlossen
Berechtigungen auf Tag-Basis können die Ergebnisse weiter filtern

Fehlermeldungen

Häufige Fehler

Die Abfrage behandelt Fehler elegant und gibt leere Ergebnisse zurück für:

Ungültige Unternehmens-IDs
Unzugängliche Projekte
Szenarien mit verweigertem Zugriff

Bei schwerwiegenden Fehlern können GraphQL-Fehler zurückgegeben werden:

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

Wichtige Hinweise

Leistung

Standardlimit: 20 Elemente pro Seite (automatisch angewendet, wenn nicht angegeben)
Maximales Limit: 500 Elemente pro Anfrage (automatisch begrenzt)
Optimierung: Abfragen verwenden optimierte Joins mit STRAIGHT_JOIN für die beste Leistung
Indizierung: Häufige Filterfelder sind indiziert für schnelles Abfragen
Benutzerdefinierte Felder: Umfassende Unterstützung für die Filterung benutzerdefinierter Felder mit minimalem Leistungsaufwand
Geografische Abfragen: Unterstützt polygonbasierte Koordinatenfilterung für Kartenansichten

Datumsfilterung

Datumsbereiche sind einschließlich
Unterstützt überlappende Datumsbereiche (To-dos, die innerhalb des Bereichs beginnen oder enden)
Null-Daten werden elegant behandelt (To-dos ohne Fälligkeitsdaten entsprechen nicht den Datumsfiltern)
Alle Daten sollten im ISO 8601-Format vorliegen

Suchverhalten

Die Suche ist nicht groß-/kleinschreibungsempfindlich
Sucht sowohl im Titel als auch im Textinhalt
Teilweise Wortübereinstimmungen werden unterstützt
Sonderzeichen werden angemessen behandelt

Paginierungsstrategie

Verwenden Sie skip und limit für offset-basierte Paginierung
Berechnen Sie die aktuelle Seite: page = Math.floor(skip / limit) + 1
Bei großen Datensätzen sollten Sie Filter verwenden, um die Ergebnisgröße zu reduzieren
Überprüfen Sie immer hasNextPage, bevor Sie skip erhöhen