サインアップ
お問い合わせ ログイン サインアップ
システム状態

強力な検索とページネーションオプションを使用して、Blueのレコード（todo）をクエリおよびフィルタリングします。

レコードのリスト

todosクエリを使用すると、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!]! ✅ はい クエリする企業のIDまたはスラグ
projectIds [String!] いいえ 特定のプロジェクトのIDまたはスラグでフィルタリング
todoIds [String!] いいえ 特定のtodoをIDで取得
assigneeIds [String!] いいえ 割り当てられたユーザーのIDでフィルタリング
tagIds [String!] いいえ タグのIDでフィルタリング
tagColors [String!] いいえ タグの色でフィルタリング（16進数形式）
tagTitles [String!] いいえ タイトルでフィルタリング
todoListIds [String!] いいえ todoリストのIDでフィルタリング
todoListTitles [String!] いいえ todoリストのタイトルでフィルタリング
done Boolean いいえ 完了ステータスでフィルタリング（非推奨、showCompletedを使用）
showCompleted Boolean いいえ 完了したtodoを表示/非表示（デフォルト：true）
startedAt DateTime いいえ 開始日でフィルタリング
duedAt DateTime いいえ 正確な期限日でフィルタリング
dueStart DateTime いいえ 期限日範囲の開始（含む）
dueEnd DateTime いいえ 期限日範囲の終了（含む）
search String いいえ タイトルとテキストコンテンツで検索
q String いいえ 代替検索パラメータ（検索と同じ）
excludeArchivedProjects Boolean いいえ アーカイブされたプロジェクトからのtodoを除外
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 todoリストの位置で昇順にソート
todoListPosition_DESC todoリストの位置で降順にソート
todoListTitle_ASC todoリストのタイトルで昇順にソート
todoListTitle_DESC todoリストのタイトルで降順にソート
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 カスタムフィールドのID
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!]! todoレコードの配列
pageInfo PageInfo! ページネーションメタデータ

PageInfo

フィールド 型 説明
totalPages Int 利用可能なページの総数
totalItems Int すべてのページのアイテムの総数
page Int 現在のページ番号（スキップ/制限から計算）
perPage Int ページごとのアイテム数
hasNextPage Boolean! 次のページがあるかどうか
hasPreviousPage Boolean! 前のページがあるかどうか

Todoフィールド

フィールド 型 説明
id ID! 一意の識別子
uid String! ユーザーフレンドリーな一意の識別子
position Float! リスト内の位置
title String! todoのタイトル
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! todoが繰り返されるかどうか
isRead Boolean 現在のユーザーの読み取りステータス
isSeen Boolean 現在のユーザーの表示ステータス
todoList TodoList! 親todoリスト
users [User!]! 割り当てられたユーザー
tags [Tag!]! 関連するタグ
checklists [Checklist!]! 関連するチェックリスト
createdBy User todoを作成したユーザー
customFields [CustomField!]! カスタムフィールドの値
dependOn [Todo!] ブロックしているtodo（依存関係）
dependBy [Todo!] このtodoによってブロックされている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権限を持つユーザーは、自分に割り当てられたtodoのみを見ることができます
  • 隠されたtodoリスト（役割設定に基づく）は自動的に除外されます
  • タグベースの権限が結果をさらにフィルタリングする場合があります

エラーレスポンス

一般的なエラー

クエリはエラーを優雅に処理し、次のような場合に空の結果を返します：

  • 無効な企業ID
  • アクセスできないプロジェクト
  • 権限が拒否されたシナリオ

重大なエラーの場合、GraphQLエラーが返されることがあります：

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

重要な注意事項

パフォーマンス

  • デフォルト制限: ページごとに20アイテム（指定されていない場合は自動的に適用）
  • 最大制限: リクエストごとに500アイテム（自動的に制限）
  • 最適化: クエリは最良のパフォーマンスのためにSTRAIGHT_JOINを使用した最適化された結合を使用
  • インデックス作成: 一般的なフィルタフィールドは高速クエリのためにインデックスされています
  • カスタムフィールド: 最小限のパフォーマンス影響で広範なカスタムフィールドフィルタリングをサポート
  • 地理的クエリ: マップビュー用のポリゴンベースの座標フィルタリングをサポート

日付フィルタリング

  • 日付範囲は含まれます
  • 重複する日付範囲をサポート（範囲内で開始または終了するtodo）
  • Nullの日付は優雅に処理されます（期限日がないtodoは日付フィルタに一致しません）
  • すべての日付はISO 8601形式である必要があります

検索動作

  • 検索は大文字と小文字を区別しません
  • タイトルとテキストコンテンツの両方で検索します
  • 部分的な単語一致がサポートされています
  • 特殊文字は適切に処理されます

ページネーション戦略

  • オフセットベースのページネーションにはskipとlimitを使用
  • 現在のページを計算する：page = Math.floor(skip / limit) + 1
  • 大規模データセットの場合、結果サイズを減らすためにフィルタを使用することを検討してください
  • スキップを増加させる前に常にhasNextPageを確認してください

関連エンドポイント

  • レコードの作成: createTodoミューテーションを使用して新しいレコードを作成
  • レコードの更新: updateTodoミューテーションを使用してレコードを修正
  • レコードの削除: deleteTodoミューテーションを使用してレコードを削除
  • カスタムフィールドのリスト: フィルタリング用の利用可能なカスタムフィールドをクエリ
  • プロジェクトのリスト: フィルタリング用の利用可能なプロジェクトをクエリ
© Blue | 愛を込めて設計 ❤ 全体にわたって

AIアシスタント

回答はAIを使用して生成されており、間違いが含まれる可能性があります。

どのようにお手伝いできますか？

Blueやこのドキュメントについて何でも聞いてください。

送信するにはEnterを押してください • 新しい行を作成するにはShift+Enterを押してください • ⌘Iで開く