---

Lijst Records

De todo's-query stelt je in staat om records uit Blue op te halen met uitgebreide filter-, sorteervarianten en paginatie-opties. Je kunt records opvragen over bedrijven, projecten of filteren op specifieke criteria zoals toegewezen gebruikers, tags en data.

Basisvoorbeeld

Lijst alle records in een bedrijf met minimale parameters:

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

Geavanceerd Voorbeeld

Vraag records op met uitgebreide filter-, sorteervarianten en veldselectie:

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

Invoervariabelen

TodosFilter

Parameter	Type	Vereist	Beschrijving
companyIds	[String!]!	✅ Ja	Bedrijfs-ID's of slugs om op te vragen
projectIds	[String!]	Nee	Filter op specifieke project-ID's of slugs
todoIds	[String!]	Nee	Haal specifieke todo's op aan de hand van hun ID's
assigneeIds	[String!]	Nee	Filter op toegewezen gebruikers-ID's
tagIds	[String!]	Nee	Filter op tag-ID's
tagColors	[String!]	Nee	Filter op tagkleuren (hex-formaat)
tagTitles	[String!]	Nee	Filter op tagtitels
todoListIds	[String!]	Nee	Filter op todo-lijst-ID's
todoListTitles	[String!]	Nee	Filter op todo-lijsttitels
done	Boolean	Nee	Filter op voltooiingsstatus (verouderd, gebruik showCompleted)
showCompleted	Boolean	Nee	Toon/verberg voltooide todo's (standaard: waar)
startedAt	DateTime	Nee	Filter op startdatum
duedAt	DateTime	Nee	Filter op exacte vervaldatum
dueStart	DateTime	Nee	Vervaldatum bereik start (inclusief)
dueEnd	DateTime	Nee	Vervaldatum bereik einde (inclusief)
search	String	Nee	Zoek in titel en tekstinhoud
q	String	Nee	Alternatieve zoekparameter (zelfde als zoekopdracht)
excludeArchivedProjects	Boolean	Nee	Sluit todo's uit van gearchiveerde projecten
coordinates	JSON	Nee	Geo-spatiale filter voor kaartweergave (polygon coördinaten)
fields	JSON	Nee	Aangepaste veldfilters (zie geavanceerde filtering)
op	FilterLogicalOperator	Nee	Logische operator voor veldfilters (EN/OF)

Queryparameters

Parameter	Type	Vereist	Beschrijving
filter	TodosFilter!	✅ Ja	Filtercriteria voor de query
sort	[TodosSort!]	Nee	Sorteervolgorde (standaard: lege array)
limit	Int	Nee	Aantal items per pagina (standaard: 20, max: 500)
skip	Int	Nee	Aantal items om over te slaan voor paginatie (standaard: 0)

TodosSort Waarden

Waarde	Beschrijving
assignees_ASC	Sorteer op toegewezen gebruikersnamen oplopend
assignees_DESC	Sorteer op toegewezen gebruikersnamen aflopend
createdAt_ASC	Sorteer op aanmaakdatum oplopend (oudste eerst)
createdAt_DESC	Sorteer op aanmaakdatum aflopend (nieuwste eerst)
createdBy_ASC	Sorteer op naam van de maker oplopend
createdBy_DESC	Sorteer op naam van de maker aflopend
duedAt_ASC	Sorteer op vervaldatum oplopend (eerste eerst)
duedAt_DESC	Sorteer op vervaldatum aflopend (laatste eerst)
position_ASC	Sorteer op positie oplopend (standaard lijstvolgorde)
position_DESC	Sorteer op positie aflopend
startedAt_ASC	Sorteer op startdatum oplopend
startedAt_DESC	Sorteer op startdatum aflopend
title_ASC	Sorteer op titel alfabetisch oplopend
title_DESC	Sorteer op titel alfabetisch aflopend
todoListPosition_ASC	Sorteer op positie van todo-lijst oplopend
todoListPosition_DESC	Sorteer op positie van todo-lijst aflopend
todoListTitle_ASC	Sorteer op titel van todo-lijst oplopend
todoListTitle_DESC	Sorteer op titel van todo-lijst aflopend
todoTags_ASC	Sorteer op tags oplopend
todoTags_DESC	Sorteer op tags aflopend

FilterLogicalOperator Waarden

Waarde	Beschrijving
AND	Alle voorwaarden moeten overeenkomen
OR	Elke voorwaarde moet overeenkomen

Aangepaste Veldfiltering

De fields parameter ondersteunt geavanceerde filtering op basis van aangepaste velden:

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

Structuur van Aangepaste Veldfilter

Veld	Type	Beschrijving
type	String	Moet "CUSTOM_FIELD" zijn
customFieldId	String	ID van het aangepaste veld
customFieldType	String	Type van het aangepaste veld
values	[String!]	Waarden om op te filteren
op	String	Vergelijkingsoperator (IN, NOT_IN, EQ, enz.)

Ondersteunde Aangepaste Veldtypes

• Tekstvelden: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
• Numerieke velden: CURRENCY, NUMBER, FORMULA
• Selectievelden: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
• Referentievelden: REFERENCE, LOOKUP
• Datumvelden: DATE

Antwoordvelden

TodosResult

Veld	Type	Beschrijving
items	[Todo!]!	Array van todo-records
pageInfo	PageInfo!	Paginatie metadata

PageInfo

Veld	Type	Beschrijving
totalPages	Int	Totaal aantal beschikbare pagina's
totalItems	Int	Totaal aantal items over alle pagina's
page	Int	Huidig paginanummer (berekend vanuit overslaan/beperking)
perPage	Int	Aantal items per pagina
hasNextPage	Boolean!	Of er een volgende pagina is
hasPreviousPage	Boolean!	Of er een vorige pagina is

Todo Velden

Veld	Type	Beschrijving
id	ID!	Unieke identificatie
uid	String!	Gebruiksvriendelijke unieke identificatie
position	Float!	Positie in de lijst
title	String!	Todo-titel
text	String!	Gewone tekstinhoud
html	String!	HTML-geformatteerde inhoud
startedAt	DateTime	Startdatum/tijd
duedAt	DateTime	Vervaldatum/tijd
timezone	String	Tijdzone voor data
color	String	Visuele kleurindicator
cover	String	URL van de omslagafbeelding
done	Boolean!	Voltooiingsstatus
archived	Boolean!	Archiveringsstatus
createdAt	DateTime!	Aanmaak-timestamp
updatedAt	DateTime!	Laatste update-timestamp
commentCount	Int!	Aantal opmerkingen
checklistCount	Int!	Totaal aantal checklistitems
checklistCompletedCount	Int!	Voltooide checklistitems
isRepeating	Boolean!	Of todo terugkerend is
isRead	Boolean	Leesstatus voor huidige gebruiker
isSeen	Boolean	Gezien status voor huidige gebruiker
todoList	TodoList!	Ouder todo-lijst
users	[User!]!	Toegewezen gebruikers
tags	[Tag!]!	Geassocieerde tags
checklists	[Checklist!]!	Geassocieerde checklists
createdBy	User	Gebruiker die de todo heeft aangemaakt
customFields	[CustomField!]!	Waarden van aangepaste velden
dependOn	[Todo!]	Blokkerende todo's (afhankelijkheden)
dependBy	[Todo!]	Afhankelijke todo's (geblokkeerd door deze)
timeTracking	TimeTracking	Tijdregistratiegegevens

Vereiste Machtigingen

Gebruikers moeten de juiste toegang hebben om records op te vragen:

Toegangstype	Vereisten
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

Speciale Beperkingen:

• Gebruikers met showOnlyAssignedTodos machtiging kunnen alleen todo's zien die aan hen zijn toegewezen
• Verborgen todo-lijsten (op basis van rolconfiguratie) worden automatisch uitgesloten
• Tag-gebaseerde machtigingen kunnen de resultaten verder filteren

Foutreacties

Veelvoorkomende Fouten

De query behandelt fouten soepel en retourneert lege resultaten voor:

• Ongeldige bedrijfs-ID's
• Onbereikbare projecten
• Toegangsweigering scenario's

Voor ernstige fouten kunnen GraphQL-fouten worden geretourneerd:

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

Belangrijke Notities

Prestatie

• Standaardlimiet: 20 items per pagina (automatisch toegepast als niet gespecificeerd)
• Maximale limiet: 500 items per verzoek (automatisch begrensd)
• Optimalisatie: Queries gebruiken geoptimaliseerde joins met STRAIGHT_JOIN voor de beste prestaties
• Indexering: Veelvoorkomende filtervelden zijn geïndexeerd voor snelle queries
• Aangepaste velden: Uitgebreide ondersteuning voor filtering van aangepaste velden met minimale prestatie-impact
• Geografische queries: Ondersteunt polygon-gebaseerde coördinatenfiltering voor kaartweergaven

Datumfiltering

• Datumbereiken zijn inclusief
• Ondersteunt overlappende datumbereiken (todo's die binnen het bereik beginnen of eindigen)
• Null-datums worden soepel behandeld (todo's zonder vervaldatums zullen niet overeenkomen met datumfilters)
• Alle datums moeten in ISO 8601-formaat zijn

Zoekgedrag

• Zoekopdrachten zijn niet hoofdlettergevoelig
• Zoekt in zowel titel als tekstinhoud
• Deeltijdwoordovereenkomsten worden ondersteund
• Speciale tekens worden op de juiste manier behandeld

Paginatiestrategie

• Gebruik skip en limit voor offset-gebaseerde paginatie
• Bereken de huidige pagina: page = Math.floor(skip / limit) + 1
• Voor grote datasets, overweeg om filters te gebruiken om de resultaatgrootte te verminderen
• Controleer altijd hasNextPage voordat je overslaan verhoogt

Gerelateerde Eindpunten

• Record Aanmaken: Gebruik de createTodo-mutatie om nieuwe records aan te maken
• Record Bijwerken: Gebruik de updateTodo-mutatie om records te wijzigen
• Record Verwijderen: Gebruik de deleteTodo-mutatie om records te verwijderen
• Lijst Aangepaste Velden: Vraag beschikbare aangepaste velden op voor filtering
• Lijst Projecten: Vraag beschikbare projecten op voor filtering