---

Lista poster

Frågan om att-göra tillåter dig att hämta poster från Blue med omfattande filtrering, sortering och pagineringsalternativ. Du kan fråga poster över företag, projekt eller filtrera efter specifika kriterier som tilldelade användare, taggar och datum.

Grundläggande exempel

Lista alla poster i ett företag med minimala parametrar:

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

Avancerat exempel

Fråga poster med omfattande filtrering, sortering och fältval:

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

Indata parametrar

TodosFilter

Parameter	Typ	Obligatorisk	Beskrivning
companyIds	[String!]!	✅ Ja	Företags-ID eller slugs att fråga från
projectIds	[String!]	Nej	Filtrera efter specifika projekt-ID eller slugs
todoIds	[String!]	Nej	Hämta specifika att-göra-poster efter deras ID
assigneeIds	[String!]	Nej	Filtrera efter tilldelade användar-ID
tagIds	[String!]	Nej	Filtrera efter tagg-ID
tagColors	[String!]	Nej	Filtrera efter taggfärger (hex-format)
tagTitles	[String!]	Nej	Filtrera efter taggtitlar
todoListIds	[String!]	Nej	Filtrera efter att-göra-lista-ID
todoListTitles	[String!]	Nej	Filtrera efter att-göra-lista titlar
done	Boolean	Nej	Filtrera efter slutförandestatus (föråldrad, använd showCompleted)
showCompleted	Boolean	Nej	Visa/dölj slutförda att-göra-poster (standard: true)
startedAt	DateTime	Nej	Filtrera efter startdatum
duedAt	DateTime	Nej	Filtrera efter exakt förfallodatum
dueStart	DateTime	Nej	Förfallodatumsintervall start (inklusive)
dueEnd	DateTime	Nej	Förfallodatumsintervall slut (inklusive)
search	String	Nej	Sök i titel och textinnehåll
q	String	Nej	Alternativt sökparameter (samma som sök)
excludeArchivedProjects	Boolean	Nej	Exkludera att-göra-poster från arkiverade projekt
coordinates	JSON	Nej	Geo-spatialt filter för kartvy (polygonkoordinater)
fields	JSON	Nej	Anpassade fältfilter (se avancerad filtrering)
op	FilterLogicalOperator	Nej	Logisk operator för fältfilter (OCH/ELLER)

Frågeparametrar

Parameter	Typ	Obligatorisk	Beskrivning
filter	TodosFilter!	✅ Ja	Filterkriterier för frågan
sort	[TodosSort!]	Nej	Sorteringsordning (standard: tom array)
limit	Int	Nej	Antal objekt per sida (standard: 20, max: 500)
skip	Int	Nej	Antal objekt att hoppa över för paginering (standard: 0)

TodosSort värden

Värde	Beskrivning
assignees_ASC	Sortera efter tilldelade användarnamn stigande
assignees_DESC	Sortera efter tilldelade användarnamn fallande
createdAt_ASC	Sortera efter skapelsedatum stigande (äldst först)
createdAt_DESC	Sortera efter skapelsedatum fallande (nyast först)
createdBy_ASC	Sortera efter skaparnamn stigande
createdBy_DESC	Sortera efter skaparnamn fallande
duedAt_ASC	Sortera efter förfallodatum stigande (tidigast först)
duedAt_DESC	Sortera efter förfallodatum fallande (senast först)
position_ASC	Sortera efter position stigande (standard lista ordning)
position_DESC	Sortera efter position fallande
startedAt_ASC	Sortera efter startdatum stigande
startedAt_DESC	Sortera efter startdatum fallande
title_ASC	Sortera efter titel alfabetiskt stigande
title_DESC	Sortera efter titel alfabetiskt fallande
todoListPosition_ASC	Sortera efter att-göra-lista position stigande
todoListPosition_DESC	Sortera efter att-göra-lista position fallande
todoListTitle_ASC	Sortera efter att-göra-lista titel stigande
todoListTitle_DESC	Sortera efter att-göra-lista titel fallande
todoTags_ASC	Sortera efter taggar stigande
todoTags_DESC	Sortera efter taggar fallande

FilterLogicalOperator värden

Värde	Beskrivning
AND	Alla villkor måste matcha
OR	Något villkor måste matcha

Filtrering av anpassade fält

Parametern fields stöder avancerad filtrering efter anpassade fält:

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

Struktur för anpassat fältfilter

Fält	Typ	Beskrivning
type	String	Måste vara "CUSTOM_FIELD"
customFieldId	String	ID för det anpassade fältet
customFieldType	String	Typ av det anpassade fältet
values	[String!]	Värden att filtrera efter
op	String	Jämförelseoperator (IN, NOT_IN, EQ, etc.)

Stödda typer av anpassade fält

• Textfält: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
• Numeriska fält: CURRENCY, NUMBER, FORMULA
• Urvals fält: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
• Referensfält: REFERENCE, LOOKUP
• Datumfält: DATE

Svarsfält

TodosResult

Fält	Typ	Beskrivning
items	[Todo!]!	Array av att-göra-poster
pageInfo	PageInfo!	Paginering metadata

PageInfo

Fält	Typ	Beskrivning
totalPages	Int	Totalt antal sidor tillgängliga
totalItems	Int	Totalt antal objekt över alla sidor
page	Int	Aktuellt sidnummer (beräknat från hoppa/limit)
perPage	Int	Antal objekt per sida
hasNextPage	Boolean!	Om det finns en nästa sida
hasPreviousPage	Boolean!	Om det finns en föregående sida

Todo-fält

Fält	Typ	Beskrivning
id	ID!	Unik identifierare
uid	String!	Användarvänlig unik identifierare
position	Float!	Position i listan
title	String!	Att-göra titel
text	String!	Ren textinnehåll
html	String!	HTML-formaterat innehåll
startedAt	DateTime	Startdatum/tid
duedAt	DateTime	Förfallodatum/tid
timezone	String	Tidszon för datum
color	String	Visuell färgindikator
cover	String	URL för omslagsbild
done	Boolean!	Slutförandestatus
archived	Boolean!	Arkiveringsstatus
createdAt	DateTime!	Skapelsestämpel
updatedAt	DateTime!	Senaste uppdateringsstämpel
commentCount	Int!	Antal kommentarer
checklistCount	Int!	Totalt antal checklistaposter
checklistCompletedCount	Int!	Slutförda checklistaposter
isRepeating	Boolean!	Om att-göra-posten är återkommande
isRead	Boolean	Läst status för aktuell användare
isSeen	Boolean	Sett status för aktuell användare
todoList	TodoList!	Föräldra att-göra-lista
users	[User!]!	Tilldelade användare
tags	[Tag!]!	Associerade taggar
checklists	[Checklist!]!	Associerade checklistor
createdBy	User	Användare som skapade att-göra-posten
customFields	[CustomField!]!	Värden för anpassade fält
dependOn	[Todo!]	Blockerande att-göra-poster (beroenden)
dependBy	[Todo!]	Beroende att-göra-poster (blockerade av detta)
timeTracking	TimeTracking	Tidsregistreringsdata

Obligatoriska behörigheter

Användare måste ha lämplig åtkomst för att fråga poster:

Åtkomsttyp	Krav
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

Speciella begränsningar:

• Användare med showOnlyAssignedTodos behörighet kan endast se att-göra-poster som tilldelats dem
• Dolda att-göra-listor (baserat på rollkonfiguration) utesluts automatiskt
• Taggbaserade behörigheter kan ytterligare filtrera resultat

Felrespons

Vanliga fel

Frågan hanterar fel på ett smidigt sätt och returnerar tomma resultat för:

• Ogiltiga företags-ID
• Otillgängliga projekt
• Behörighet nekad scenarier

För allvarliga fel kan GraphQL-fel returneras:

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

Viktiga anteckningar

Prestanda

• Standardgräns: 20 objekt per sida (automatiskt tillämpad om inte specificerad)
• Maximal gräns: 500 objekt per begäran (automatiskt begränsad)
• Optimering: Frågor använder optimerade joins med STRAIGHT_JOIN för bästa prestanda
• Indexering: Vanliga filterfält är indexerade för snabb frågning
• Anpassade fält: Omfattande stöd för filtrering av anpassade fält med minimal påverkan på prestanda
• Geografiska frågor: Stöder polygonbaserad koordinatfiltrering för kartvyer

Datumfiltrering

• Datumintervall är inkluderande
• Stöder överlappande datumintervall (att-göra-poster som börjar eller slutar inom intervallet)
• Null-datum hanteras smidigt (att-göra-poster utan förfallodatum matchar inte datumfilter)
• Alla datum bör vara i ISO 8601-format

Sökbeteende

• Sökningen är skiftlägesokänslig
• Söker i både titel och textinnehåll
• Delvis ordmatchning stöds
• Specialtecken hanteras på lämpligt sätt

Pagineringstrategi

• Använd skip och limit för offset-baserad paginering
• Beräkna aktuell sida: page = Math.floor(skip / limit) + 1
• För stora dataset, överväg att använda filter för att minska resultatstorleken
• Kontrollera alltid hasNextPage innan du ökar hoppa

Relaterade slutpunkter

• Skapa post: Använd createTodo mutation för att skapa nya poster
• Uppdatera post: Använd updateTodo mutation för att modifiera poster
• Ta bort post: Använd deleteTodo mutation för att ta bort poster
• Lista anpassade fält: Fråga tillgängliga anpassade fält för filtrering
• Lista projekt: Fråga tillgängliga projekt för filtrering