Список записей

Запрашивайте и фильтруйте записи (дела) в Blue с мощными возможностями поиска и пагинации.

Список записей

Запрос дел позволяет вам извлекать записи из Blue с комплексными параметрами фильтрации, сортировки и пагинации. Вы можете запрашивать записи по компаниям, проектам или фильтровать по конкретным критериям, таким как назначенные пользователи, теги и даты.

Простой пример

Список всех записей в компании с минимальными параметрами:

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

Расширенный пример

Запрос записей с комплексной фильтрацией, сортировкой и выбором полей:

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

Входные параметры

TodosFilter

Параметр	Тип	Обязательный	Описание
`companyIds`	[String!]!	✅ Да	Идентификаторы или слаги компаний для запроса
`projectIds`	[String!]	Нет	Фильтровать по конкретным идентификаторам проектов или слагам
`todoIds`	[String!]	Нет	Извлечь конкретные дела по их идентификаторам
`assigneeIds`	[String!]	Нет	Фильтровать по идентификаторам назначенных пользователей
`tagIds`	[String!]	Нет	Фильтровать по идентификаторам тегов
`tagColors`	[String!]	Нет	Фильтровать по цветам тегов (в формате hex)
`tagTitles`	[String!]	Нет	Фильтровать по названиям тегов
`todoListIds`	[String!]	Нет	Фильтровать по идентификаторам списков дел
`todoListTitles`	[String!]	Нет	Фильтровать по названиям списков дел
`done`	Boolean	Нет	Фильтровать по статусу завершения (устарело, используйте showCompleted)
`showCompleted`	Boolean	Нет	Показать/скрыть завершенные дела (по умолчанию: true)
`startedAt`	DateTime	Нет	Фильтровать по дате начала
`duedAt`	DateTime	Нет	Фильтровать по точной дате завершения
`dueStart`	DateTime	Нет	Начало диапазона даты завершения (включительно)
`dueEnd`	DateTime	Нет	Конец диапазона даты завершения (включительно)
`search`	String	Нет	Поиск в заголовке и текстовом содержимом
`q`	String	Нет	Альтернативный параметр поиска (такой же, как поиск)
`excludeArchivedProjects`	Boolean	Нет	Исключить дела из архивированных проектов
`coordinates`	JSON	Нет	Геопространственный фильтр для карты (координаты полигона)
`fields`	JSON	Нет	Фильтры пользовательских полей (см. расширенную фильтрацию)
`op`	FilterLogicalOperator	Нет	Логический оператор для фильтров полей (AND/OR)

Параметры запроса

Параметр	Тип	Обязательный	Описание
`filter`	TodosFilter!	✅ Да	Критерии фильтрации для запроса
`sort`	[TodosSort!]	Нет	Порядок сортировки (по умолчанию: пустой массив)
`limit`	Int	Нет	Количество элементов на странице (по умолчанию: 20, максимум: 500)
`skip`	Int	Нет	Количество элементов, которые нужно пропустить для пагинации (по умолчанию: 0)

Значения сортировки TodosSort

Значение	Описание
`assignees_ASC`	Сортировать по именам назначенных пользователей по возрастанию
`assignees_DESC`	Сортировать по именам назначенных пользователей по убыванию
`createdAt_ASC`	Сортировать по дате создания по возрастанию (сначала старые)
`createdAt_DESC`	Сортировать по дате создания по убыванию (сначала новые)
`createdBy_ASC`	Сортировать по имени создателя по возрастанию
`createdBy_DESC`	Сортировать по имени создателя по убыванию
`duedAt_ASC`	Сортировать по дате завершения по возрастанию (сначала ближайшие)
`duedAt_DESC`	Сортировать по дате завершения по убыванию (сначала самые поздние)
`position_ASC`	Сортировать по позиции по возрастанию (порядок по умолчанию)
`position_DESC`	Сортировать по позиции по убыванию
`startedAt_ASC`	Сортировать по дате начала по возрастанию
`startedAt_DESC`	Сортировать по дате начала по убыванию
`title_ASC`	Сортировать по заголовку в алфавитном порядке по возрастанию
`title_DESC`	Сортировать по заголовку в алфавитном порядке по убыванию
`todoListPosition_ASC`	Сортировать по позиции списка дел по возрастанию
`todoListPosition_DESC`	Сортировать по позиции списка дел по убыванию
`todoListTitle_ASC`	Сортировать по заголовку списка дел по возрастанию
`todoListTitle_DESC`	Сортировать по заголовку списка дел по убыванию
`todoTags_ASC`	Сортировать по тегам по возрастанию
`todoTags_DESC`	Сортировать по тегам по убыванию

Значения FilterLogicalOperator

Значение	Описание
`AND`	Все условия должны совпадать
`OR`	Любое условие должно совпадать

Фильтрация пользовательских полей

Параметр fields поддерживает расширенную фильтрацию по пользовательским полям:

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

Структура фильтра пользовательского поля

Поле	Тип	Описание
`type`	String	Должно быть "CUSTOM_FIELD"
`customFieldId`	String	Идентификатор пользовательского поля
`customFieldType`	String	Тип пользовательского поля
`values`	[String!]	Значения для фильтрации
`op`	String	Оператор сравнения (IN, NOT_IN, EQ и т.д.)

Поддерживаемые типы пользовательских полей

Текстовые поля: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
Числовые поля: CURRENCY, NUMBER, FORMULA
Поля выбора: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
Поля ссылок: REFERENCE, LOOKUP
Датные поля: DATE

Поля ответа

TodosResult

Поле	Тип	Описание
`items`	[Todo!]!	Массив записей дел
`pageInfo`	PageInfo!	Метаданные пагинации

PageInfo

Поле	Тип	Описание
`totalPages`	Int	Общее количество доступных страниц
`totalItems`	Int	Общее количество элементов на всех страницах
`page`	Int	Номер текущей страницы (рассчитывается из skip/limit)
`perPage`	Int	Количество элементов на странице
`hasNextPage`	Boolean!	Есть ли следующая страница
`hasPreviousPage`	Boolean!	Есть ли предыдущая страница

Поля Todo

Поле	Тип	Описание
`id`	ID!	Уникальный идентификатор
`uid`	String!	Удобный для пользователя уникальный идентификатор
`position`	Float!	Позиция в списке
`title`	String!	Заголовок дела
`text`	String!	Обычное текстовое содержимое
`html`	String!	Содержимое в формате HTML
`startedAt`	DateTime	Дата/время начала
`duedAt`	DateTime	Дата/время завершения
`timezone`	String	Часовой пояс для дат
`color`	String	Визуальный цветовой индикатор
`cover`	String	URL изображения обложки
`done`	Boolean!	Статус завершения
`archived`	Boolean!	Статус архива
`createdAt`	DateTime!	Временная метка создания
`updatedAt`	DateTime!	Временная метка последнего обновления
`commentCount`	Int!	Количество комментариев
`checklistCount`	Int!	Общее количество элементов в контрольном списке
`checklistCompletedCount`	Int!	Завершенные элементы контрольного списка
`isRepeating`	Boolean!	Является ли дело повторяющимся
`isRead`	Boolean	Статус прочтения для текущего пользователя
`isSeen`	Boolean	Статус просмотра для текущего пользователя
`todoList`	TodoList!	Родительский список дел
`users`	[User!]!	Назначенные пользователи
`tags`	[Tag!]!	Связанные теги
`checklists`	[Checklist!]!	Связанные контрольные списки
`createdBy`	User	Пользователь, создавший дело
`customFields`	[CustomField!]!	Значения пользовательских полей
`dependOn`	[Todo!]	Блокирующие дела (зависимости)
`dependBy`	[Todo!]	Зависимые дела (заблокированные этим)
`timeTracking`	TimeTracking	Данные отслеживания времени

Обязательные разрешения

Пользователи должны иметь соответствующий доступ для запроса записей:

Тип доступа	Требования
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

Специальные ограничения:

Пользователи с разрешением showOnlyAssignedTodos могут видеть только дела, назначенные им
Скрытые списки дел (в зависимости от конфигурации ролей) автоматически исключаются
Разрешения на основе тегов могут дополнительно фильтровать результаты

Ответы на ошибки

Общие ошибки

Запрос обрабатывает ошибки корректно и возвращает пустые результаты для:

Неверных идентификаторов компаний
Недоступных проектов
Сценариев отказа в доступе

Для серьезных ошибок могут быть возвращены ошибки GraphQL:

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

Важные заметки

Производительность

Предел по умолчанию: 20 элементов на странице (автоматически применяется, если не указано)
Максимальный предел: 500 элементов на запрос (автоматически ограничено)
Оптимизация: Запросы используют оптимизированные соединения с STRAIGHT_JOIN для лучшей производительности
Индексация: Общие поля фильтрации индексируются для быстрого запроса
Пользовательские поля: Поддержка обширной фильтрации пользовательских полей с минимальным влиянием на производительность
Географические запросы: Поддерживает фильтрацию по координатам на основе полигона для карт

Фильтрация по датам

Диапазоны дат включают границы
Поддерживает перекрывающиеся диапазоны дат (дела, которые начинаются или заканчиваются в диапазоне)
Нулевые даты обрабатываются корректно (дела без дат завершения не будут соответствовать фильтрам по датам)
Все даты должны быть в формате ISO 8601

Поведение поиска

Поиск нечувствителен к регистру
Поиск осуществляется как в заголовке, так и в текстовом содержимом
Поддерживается частичное совпадение слов
Специальные символы обрабатываются соответствующим образом

Стратегия пагинации

Используйте skip и limit для пагинации на основе смещения
Рассчитайте текущую страницу: page = Math.floor(skip / limit) + 1
Для больших наборов данных рассмотрите возможность использования фильтров для уменьшения размера результата
Всегда проверяйте hasNextPage перед увеличением skip

Связанные конечные точки

Создать запись: Используйте мутацию createTodo для создания новых записей
Обновить запись: Используйте мутацию updateTodo для изменения записей
Удалить запись: Используйте мутацию deleteTodo для удаления записей
Список пользовательских полей: Запрашивайте доступные пользовательские поля для фильтрации
Список проектов: Запрашивайте доступные проекты для фильтрации