Lister les enregistrements

Interrogez et filtrez les enregistrements (tâches) dans Blue avec des options de recherche et de pagination puissantes.

Lister les enregistrements

La requête todos vous permet de récupérer des enregistrements de Blue avec des options de filtrage, de tri et de pagination complètes. Vous pouvez interroger des enregistrements à travers des entreprises, des projets, ou filtrer par des critères spécifiques tels que les assignés, les étiquettes et les dates.

Exemple de base

Lister tous les enregistrements dans une entreprise avec des paramètres minimaux :

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

Exemple avancé

Interroger des enregistrements avec un filtrage, un tri et une sélection de champs complets :

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

Paramètres d'entrée

TodosFilter

Paramètre	Type	Requis	Description
`companyIds`	[String!]!	✅ Oui	IDs ou slugs d'entreprise à interroger
`projectIds`	[String!]	Non	Filtrer par IDs ou slugs de projet spécifiques
`todoIds`	[String!]	Non	Récupérer des todos spécifiques par leurs IDs
`assigneeIds`	[String!]	Non	Filtrer par IDs d'utilisateur assigné
`tagIds`	[String!]	Non	Filtrer par IDs d'étiquettes
`tagColors`	[String!]	Non	Filtrer par couleurs d'étiquettes (format hex)
`tagTitles`	[String!]	Non	Filtrer par titres d'étiquettes
`todoListIds`	[String!]	Non	Filtrer par IDs de listes de tâches
`todoListTitles`	[String!]	Non	Filtrer par titres de listes de tâches
`done`	Boolean	Non	Filtrer par statut d'achèvement (déprécié, utiliser showCompleted)
`showCompleted`	Boolean	Non	Afficher/masquer les todos complétés (par défaut : vrai)
`startedAt`	DateTime	Non	Filtrer par date de début
`duedAt`	DateTime	Non	Filtrer par date d'échéance exacte
`dueStart`	DateTime	Non	Début de la plage de dates d'échéance (inclusif)
`dueEnd`	DateTime	Non	Fin de la plage de dates d'échéance (inclusif)
`search`	String	Non	Rechercher dans le titre et le contenu textuel
`q`	String	Non	Paramètre de recherche alternatif (identique à search)
`excludeArchivedProjects`	Boolean	Non	Exclure les todos des projets archivés
`coordinates`	JSON	Non	Filtre géospatial pour la vue carte (coordonnées polygonales)
`fields`	JSON	Non	Filtres de champs personnalisés (voir filtrage avancé)
`op`	FilterLogicalOperator	Non	Opérateur logique pour les filtres de champs (ET/OU)

Paramètres de requête

Paramètre	Type	Requis	Description
`filter`	TodosFilter!	✅ Oui	Critères de filtrage pour la requête
`sort`	[TodosSort!]	Non	Ordre de tri (par défaut : tableau vide)
`limit`	Int	Non	Nombre d'éléments par page (par défaut : 20, max : 500)
`skip`	Int	Non	Nombre d'éléments à ignorer pour la pagination (par défaut : 0)

Valeurs de tri des todos

Valeur	Description
`assignees_ASC`	Trier par noms d'assignés par ordre croissant
`assignees_DESC`	Trier par noms d'assignés par ordre décroissant
`createdAt_ASC`	Trier par date de création par ordre croissant (le plus ancien en premier)
`createdAt_DESC`	Trier par date de création par ordre décroissant (le plus récent en premier)
`createdBy_ASC`	Trier par nom de créateur par ordre croissant
`createdBy_DESC`	Trier par nom de créateur par ordre décroissant
`duedAt_ASC`	Trier par date d'échéance par ordre croissant (la plus proche en premier)
`duedAt_DESC`	Trier par date d'échéance par ordre décroissant (la plus éloignée en premier)
`position_ASC`	Trier par position par ordre croissant (ordre de liste par défaut)
`position_DESC`	Trier par position par ordre décroissant
`startedAt_ASC`	Trier par date de début par ordre croissant
`startedAt_DESC`	Trier par date de début par ordre décroissant
`title_ASC`	Trier par titre par ordre alphabétique croissant
`title_DESC`	Trier par titre par ordre alphabétique décroissant
`todoListPosition_ASC`	Trier par position de la liste de tâches par ordre croissant
`todoListPosition_DESC`	Trier par position de la liste de tâches par ordre décroissant
`todoListTitle_ASC`	Trier par titre de la liste de tâches par ordre croissant
`todoListTitle_DESC`	Trier par titre de la liste de tâches par ordre décroissant
`todoTags_ASC`	Trier par étiquettes par ordre croissant
`todoTags_DESC`	Trier par étiquettes par ordre décroissant

Valeurs de l'opérateur logique de filtre

Valeur	Description
`AND`	Toutes les conditions doivent correspondre
`OR`	Toute condition doit correspondre

Filtrage par champ personnalisé

Le paramètre fields prend en charge le filtrage avancé par champs personnalisés :

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

Structure du filtre de champ personnalisé

Champ	Type	Description
`type`	String	Doit être "CUSTOM_FIELD"
`customFieldId`	String	ID du champ personnalisé
`customFieldType`	String	Type du champ personnalisé
`values`	[String!]	Valeurs à filtrer
`op`	String	Opérateur de comparaison (IN, NOT_IN, EQ, etc.)

Types de champs personnalisés pris en charge

Champs texte : TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
Champs numériques : CURRENCY, NUMBER, FORMULA
Champs de sélection : SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
Champs de référence : REFERENCE, LOOKUP
Champs de date : DATE

Champs de réponse

TodosResult

Champ	Type	Description
`items`	[Todo!]!	Tableau d'enregistrements de tâches
`pageInfo`	PageInfo!	Métadonnées de pagination

PageInfo

Champ	Type	Description
`totalPages`	Int	Nombre total de pages disponibles
`totalItems`	Int	Nombre total d'éléments sur toutes les pages
`page`	Int	Numéro de la page actuelle (calculé à partir de skip/limit)
`perPage`	Int	Nombre d'éléments par page
`hasNextPage`	Boolean!	S'il y a une page suivante
`hasPreviousPage`	Boolean!	S'il y a une page précédente

Champs Todo

Champ	Type	Description
`id`	ID!	Identifiant unique
`uid`	String!	Identifiant unique convivial
`position`	Float!	Position dans la liste
`title`	String!	Titre de la tâche
`text`	String!	Contenu en texte brut
`html`	String!	Contenu formaté en HTML
`startedAt`	DateTime	Date/heure de début
`duedAt`	DateTime	Date/heure d'échéance
`timezone`	String	Fuseau horaire pour les dates
`color`	String	Indicateur de couleur visuel
`cover`	String	URL de l'image de couverture
`done`	Boolean!	Statut d'achèvement
`archived`	Boolean!	Statut d'archive
`createdAt`	DateTime!	Horodatage de création
`updatedAt`	DateTime!	Horodatage de dernière mise à jour
`commentCount`	Int!	Nombre de commentaires
`checklistCount`	Int!	Nombre total d'éléments de la liste de contrôle
`checklistCompletedCount`	Int!	Éléments de la liste de contrôle complétés
`isRepeating`	Boolean!	Si la tâche est récurrente
`isRead`	Boolean	Statut de lecture pour l'utilisateur actuel
`isSeen`	Boolean	Statut vu pour l'utilisateur actuel
`todoList`	TodoList!	Liste de tâches parent
`users`	[User!]!	Utilisateurs assignés
`tags`	[Tag!]!	Étiquettes associées
`checklists`	[Checklist!]!	Listes de contrôle associées
`createdBy`	User	Utilisateur qui a créé la tâche
`customFields`	[CustomField!]!	Valeurs de champs personnalisés
`dependOn`	[Todo!]	Todos bloquants (dépendances)
`dependBy`	[Todo!]	Todos dépendants (bloqués par celui-ci)
`timeTracking`	TimeTracking	Données de suivi du temps

Permissions requises

Les utilisateurs doivent avoir un accès approprié pour interroger des enregistrements :

Type d'accès	Exigences
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

Restrictions spéciales :

Les utilisateurs avec la permission showOnlyAssignedTodos ne peuvent voir que les tâches qui leur sont assignées
Les listes de tâches cachées (en fonction de la configuration des rôles) sont automatiquement exclues
Les permissions basées sur les étiquettes peuvent également filtrer les résultats

Réponses d'erreur

Erreurs courantes

La requête gère les erreurs avec élégance et renvoie des résultats vides pour :

IDs d'entreprise invalides
Projets inaccessibles
Scénarios de permission refusée

Pour des erreurs graves, des erreurs GraphQL peuvent être renvoyées :

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

Notes importantes

Performance

Limite par défaut : 20 éléments par page (appliquée automatiquement si non spécifiée)
Limite maximale : 500 éléments par requête (automatiquement plafonnée)
Optimisation : Les requêtes utilisent des jointures optimisées avec STRAIGHT_JOIN pour de meilleures performances
Indexation : Les champs de filtrage courants sont indexés pour des requêtes rapides
Champs personnalisés : Prise en charge étendue du filtrage par champs personnalisés avec un impact minimal sur les performances
Requêtes géographiques : Prend en charge le filtrage par coordonnées polygonales pour les vues cartographiques

Filtrage par date

Les plages de dates sont inclusives
Prend en charge les plages de dates qui se chevauchent (tâches qui commencent ou se terminent dans la plage)
Les dates nulles sont gérées avec élégance (les tâches sans dates d'échéance ne correspondront pas aux filtres de date)
Toutes les dates doivent être au format ISO 8601

Comportement de recherche

La recherche est insensible à la casse
Recherche dans le titre et le contenu textuel
La correspondance partielle de mots est prise en charge
Les caractères spéciaux sont gérés de manière appropriée

Stratégie de pagination

Utilisez skip et limit pour la pagination basée sur l'offset
Calculez la page actuelle : page = Math.floor(skip / limit) + 1
Pour de grands ensembles de données, envisagez d'utiliser des filtres pour réduire la taille des résultats
Vérifiez toujours hasNextPage avant d'incrémenter skip

Points de terminaison associés

Créer un enregistrement : Utilisez la mutation createTodo pour créer de nouveaux enregistrements
Mettre à jour un enregistrement : Utilisez la mutation updateTodo pour modifier des enregistrements
Supprimer un enregistrement : Utilisez la mutation deleteTodo pour supprimer des enregistrements
Lister les champs personnalisés : Interrogez les champs personnalisés disponibles pour le filtrage
Lister les projets : Interrogez les projets disponibles pour le filtrage