Listar Registros

Consultar e filtrar registros (todos) no Blue com opções poderosas de pesquisa e paginação.

Listar Registros

A consulta de todos permite recuperar registros do Blue com opções abrangentes de filtragem, ordenação e paginação. Você pode consultar registros entre empresas, projetos ou filtrar por critérios específicos, como responsáveis, tags e datas.

Exemplo Básico

Liste todos os registros em uma empresa com parâmetros mínimos:

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

Exemplo Avançado

Consulta registros com filtragem abrangente, ordenação e seleção de campos:

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

Parâmetros de Entrada

TodosFilter

Parâmetro	Tipo	Obrigatório	Descrição
`companyIds`	[String!]!	✅ Sim	IDs ou slugs de empresas para consultar
`projectIds`	[String!]	Não	Filtrar por IDs ou slugs de projetos específicos
`todoIds`	[String!]	Não	Recuperar todos específicos por seus IDs
`assigneeIds`	[String!]	Não	Filtrar por IDs de usuários atribuídos
`tagIds`	[String!]	Não	Filtrar por IDs de tags
`tagColors`	[String!]	Não	Filtrar por cores de tags (formato hex)
`tagTitles`	[String!]	Não	Filtrar por títulos de tags
`todoListIds`	[String!]	Não	Filtrar por IDs de listas de todos
`todoListTitles`	[String!]	Não	Filtrar por títulos de listas de todos
`done`	Boolean	Não	Filtrar por status de conclusão (obsoleto, use showCompleted)
`showCompleted`	Boolean	Não	Mostrar/ocultar todos concluídos (padrão: verdadeiro)
`startedAt`	DateTime	Não	Filtrar por data de início
`duedAt`	DateTime	Não	Filtrar por data de vencimento exata
`dueStart`	DateTime	Não	Início do intervalo da data de vencimento (inclusivo)
`dueEnd`	DateTime	Não	Fim do intervalo da data de vencimento (inclusivo)
`search`	String	Não	Pesquisar no título e no conteúdo do texto
`q`	String	Não	Parâmetro de pesquisa alternativo (igual a search)
`excludeArchivedProjects`	Boolean	Não	Excluir todos de projetos arquivados
`coordinates`	JSON	Não	Filtro geo-espacial para visualização no mapa (coordenadas do polígono)
`fields`	JSON	Não	Filtros de campos personalizados (veja filtragem avançada)
`op`	FilterLogicalOperator	Não	Operador lógico para filtros de campo (E/OU)

Parâmetros de Consulta

Parâmetro	Tipo	Obrigatório	Descrição
`filter`	TodosFilter!	✅ Sim	Critérios de filtragem para a consulta
`sort`	[TodosSort!]	Não	Ordem de classificação (padrão: array vazio)
`limit`	Int	Não	Número de itens por página (padrão: 20, máximo: 500)
`skip`	Int	Não	Número de itens a serem pulados para paginação (padrão: 0)

Valores de TodosSort

Valor	Descrição
`assignees_ASC`	Ordenar por nomes de responsáveis em ordem crescente
`assignees_DESC`	Ordenar por nomes de responsáveis em ordem decrescente
`createdAt_ASC`	Ordenar por data de criação em ordem crescente (mais antiga primeiro)
`createdAt_DESC`	Ordenar por data de criação em ordem decrescente (mais nova primeiro)
`createdBy_ASC`	Ordenar por nome do criador em ordem crescente
`createdBy_DESC`	Ordenar por nome do criador em ordem decrescente
`duedAt_ASC`	Ordenar por data de vencimento em ordem crescente (mais cedo primeiro)
`duedAt_DESC`	Ordenar por data de vencimento em ordem decrescente (mais tarde primeiro)
`position_ASC`	Ordenar por posição em ordem crescente (ordem padrão da lista)
`position_DESC`	Ordenar por posição em ordem decrescente
`startedAt_ASC`	Ordenar por data de início em ordem crescente
`startedAt_DESC`	Ordenar por data de início em ordem decrescente
`title_ASC`	Ordenar por título em ordem alfabética crescente
`title_DESC`	Ordenar por título em ordem alfabética decrescente
`todoListPosition_ASC`	Ordenar por posição da lista de todos em ordem crescente
`todoListPosition_DESC`	Ordenar por posição da lista de todos em ordem decrescente
`todoListTitle_ASC`	Ordenar por título da lista de todos em ordem crescente
`todoListTitle_DESC`	Ordenar por título da lista de todos em ordem decrescente
`todoTags_ASC`	Ordenar por tags em ordem crescente
`todoTags_DESC`	Ordenar por tags em ordem decrescente

Valores de FilterLogicalOperator

Valor	Descrição
`AND`	Todas as condições devem corresponder
`OR`	Qualquer condição deve corresponder

Filtragem de Campos Personalizados

O fields parâmetro suporta filtragem avançada por campos personalizados:

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

Estrutura do Filtro de Campo Personalizado

Campo	Tipo	Descrição
`type`	String	Deve ser "CUSTOM_FIELD"
`customFieldId`	String	ID do campo personalizado
`customFieldType`	String	Tipo do campo personalizado
`values`	[String!]	Valores para filtrar
`op`	String	Operador de comparação (IN, NOT_IN, EQ, etc.)

Tipos de Campos Personalizados Suportados

Campos de texto: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
Campos numéricos: CURRENCY, NUMBER, FORMULA
Campos de seleção: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
Campos de referência: REFERENCE, LOOKUP
Campos de data: DATE

Campos de Resposta

TodosResult

Campo	Tipo	Descrição
`items`	[Todo!]!	Array de registros de todos
`pageInfo`	PageInfo!	Metadados de paginação

PageInfo

Campo	Tipo	Descrição
`totalPages`	Int	Número total de páginas disponíveis
`totalItems`	Int	Número total de itens em todas as páginas
`page`	Int	Número da página atual (calculado a partir de skip/limit)
`perPage`	Int	Número de itens por página
`hasNextPage`	Boolean!	Se há uma próxima página
`hasPreviousPage`	Boolean!	Se há uma página anterior

Campos de Todo

Campo	Tipo	Descrição
`id`	ID!	Identificador único
`uid`	String!	Identificador único amigável
`position`	Float!	Posição na lista
`title`	String!	Título do todo
`text`	String!	Conteúdo em texto simples
`html`	String!	Conteúdo formatado em HTML
`startedAt`	DateTime	Data/hora de início
`duedAt`	DateTime	Data/hora de vencimento
`timezone`	String	Fuso horário para datas
`color`	String	Indicador visual de cor
`cover`	String	URL da imagem de capa
`done`	Boolean!	Status de conclusão
`archived`	Boolean!	Status de arquivamento
`createdAt`	DateTime!	Timestamp de criação
`updatedAt`	DateTime!	Timestamp da última atualização
`commentCount`	Int!	Número de comentários
`checklistCount`	Int!	Total de itens da checklist
`checklistCompletedCount`	Int!	Itens da checklist concluídos
`isRepeating`	Boolean!	Se o todo é recorrente
`isRead`	Boolean	Status de leitura para o usuário atual
`isSeen`	Boolean	Status visto para o usuário atual
`todoList`	TodoList!	Lista de todos pai
`users`	[User!]!	Usuários atribuídos
`tags`	[Tag!]!	Tags associadas
`checklists`	[Checklist!]!	Checklists associados
`createdBy`	User	Usuário que criou o todo
`customFields`	[CustomField!]!	Valores de campos personalizados
`dependOn`	[Todo!]	Todos bloqueadores (dependências)
`dependBy`	[Todo!]	Todos dependentes (bloqueados por este)
`timeTracking`	TimeTracking	Dados de rastreamento de tempo

Permissões Necessárias

Os usuários devem ter acesso apropriado para consultar registros:

Tipo de Acesso	Requisitos
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

Restrições Especiais:

Usuários com permissão showOnlyAssignedTodos podem ver apenas todos atribuídos a eles
Listas de todos ocultas (com base na configuração de função) são automaticamente excluídas
Permissões baseadas em tags podem filtrar ainda mais os resultados

Respostas de Erro

Erros Comuns

A consulta lida com erros de forma elegante e retorna resultados vazios para:

IDs de empresas inválidos
Projetos inacessíveis
Cenários de permissão negada

Para erros graves, erros do GraphQL podem ser retornados:

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

Notas Importantes

Desempenho

Limite padrão: 20 itens por página (aplicado automaticamente se não especificado)
Limite máximo: 500 itens por solicitação (automaticamente limitado)
Otimização: Consultas usam junções otimizadas com STRAIGHT_JOIN para melhor desempenho
Indexação: Campos de filtragem comuns são indexados para consultas rápidas
Campos personalizados: Suporte extensivo para filtragem de campos personalizados com impacto mínimo no desempenho
Consultas geográficas: Suporta filtragem de coordenadas baseadas em polígonos para visualizações de mapa

Filtragem de Data

Intervalos de datas são inclusivos
Suporta intervalos de datas sobrepostos (todos que começam ou terminam dentro do intervalo)
Datas nulas são tratadas de forma elegante (todos sem datas de vencimento não corresponderão aos filtros de data)
Todas as datas devem estar no formato ISO 8601

Comportamento de Pesquisa

A pesquisa não diferencia maiúsculas de minúsculas
Pesquisa em título e conteúdo do texto
Correspondência parcial de palavras é suportada
Caracteres especiais são tratados adequadamente

Estratégia de Paginação

Use skip e limit para paginação baseada em offset
Calcule a página atual: page = Math.floor(skip / limit) + 1
Para grandes conjuntos de dados, considere usar filtros para reduzir o tamanho do resultado
Sempre verifique hasNextPage antes de incrementar o skip

Endpoints Relacionados

Criar Registro: Use a mutação createTodo para criar novos registros
Atualizar Registro: Use a mutação updateTodo para modificar registros
Excluir Registro: Use a mutação deleteTodo para remover registros
Listar Campos Personalizados: Consulte os campos personalizados disponíveis para filtragem
Listar Projetos: Consulte os projetos disponíveis para filtragem