Daftar
Kontak Masuk Daftar
Status Sistem

Kuery dan filter rekaman (todos) di Blue dengan opsi pencarian dan paginasi yang kuat.

Daftar Rekaman

Kuery todos memungkinkan Anda untuk mengambil rekaman dari Blue dengan opsi penyaringan, pengurutan, dan paginasi yang komprehensif. Anda dapat mengkueri rekaman di seluruh perusahaan, proyek, atau memfilter berdasarkan kriteria tertentu seperti penugasan, tag, dan tanggal.

Contoh Dasar

Daftar semua rekaman di sebuah perusahaan dengan parameter minimal:

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

Contoh Lanjutan

Kuery rekaman dengan penyaringan, pengurutan, dan pemilihan bidang yang komprehensif:

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

Parameter Masukan

TodosFilter

Parameter Tipe Diperlukan Deskripsi
companyIds [String!]! ✅ Ya ID perusahaan atau slug untuk dikueri
projectIds [String!] Tidak Filter berdasarkan ID proyek tertentu atau slug
todoIds [String!] Tidak Ambil todos tertentu berdasarkan ID mereka
assigneeIds [String!] Tidak Filter berdasarkan ID pengguna yang ditugaskan
tagIds [String!] Tidak Filter berdasarkan ID tag
tagColors [String!] Tidak Filter berdasarkan warna tag (format hex)
tagTitles [String!] Tidak Filter berdasarkan judul tag
todoListIds [String!] Tidak Filter berdasarkan ID daftar todo
todoListTitles [String!] Tidak Filter berdasarkan judul daftar todo
done Boolean Tidak Filter berdasarkan status penyelesaian (tidak lagi digunakan, gunakan showCompleted)
showCompleted Boolean Tidak Tampilkan/sembunyikan todos yang telah selesai (default: true)
startedAt DateTime Tidak Filter berdasarkan tanggal mulai
duedAt DateTime Tidak Filter berdasarkan tanggal jatuh tempo yang tepat
dueStart DateTime Tidak Rentang tanggal jatuh tempo mulai (inklusif)
dueEnd DateTime Tidak Rentang tanggal jatuh tempo akhir (inklusif)
search String Tidak Cari di judul dan konten teks
q String Tidak Parameter pencarian alternatif (sama dengan pencarian)
excludeArchivedProjects Boolean Tidak Kecualikan todos dari proyek yang diarsipkan
coordinates JSON Tidak Filter geo-spasial untuk tampilan peta (koordinat poligon)
fields JSON Tidak Filter bidang kustom (lihat penyaringan lanjutan)
op FilterLogicalOperator Tidak Operator logis untuk filter bidang (AND/OR)

Parameter Kuery

Parameter Tipe Diperlukan Deskripsi
filter TodosFilter! ✅ Ya Kriteria filter untuk kuery
sort [TodosSort!] Tidak Urutan pengurutan (default: array kosong)
limit Int Tidak Jumlah item per halaman (default: 20, max: 500)
skip Int Tidak Jumlah item yang dilewati untuk paginasi (default: 0)

Nilai TodosSort

Nilai Deskripsi
assignees_ASC Urutkan berdasarkan nama penugasan secara ascending
assignees_DESC Urutkan berdasarkan nama penugasan secara descending
createdAt_ASC Urutkan berdasarkan tanggal pembuatan secara ascending (terlama terlebih dahulu)
createdAt_DESC Urutkan berdasarkan tanggal pembuatan secara descending (terbaru terlebih dahulu)
createdBy_ASC Urutkan berdasarkan nama pembuat secara ascending
createdBy_DESC Urutkan berdasarkan nama pembuat secara descending
duedAt_ASC Urutkan berdasarkan tanggal jatuh tempo secara ascending (terawal terlebih dahulu)
duedAt_DESC Urutkan berdasarkan tanggal jatuh tempo secara descending (terakhir terlebih dahulu)
position_ASC Urutkan berdasarkan posisi secara ascending (urutan daftar default)
position_DESC Urutkan berdasarkan posisi secara descending
startedAt_ASC Urutkan berdasarkan tanggal mulai secara ascending
startedAt_DESC Urutkan berdasarkan tanggal mulai secara descending
title_ASC Urutkan berdasarkan judul secara alfabetis ascending
title_DESC Urutkan berdasarkan judul secara alfabetis descending
todoListPosition_ASC Urutkan berdasarkan posisi daftar todo secara ascending
todoListPosition_DESC Urutkan berdasarkan posisi daftar todo secara descending
todoListTitle_ASC Urutkan berdasarkan judul daftar todo secara ascending
todoListTitle_DESC Urutkan berdasarkan judul daftar todo secara descending
todoTags_ASC Urutkan berdasarkan tag secara ascending
todoTags_DESC Urutkan berdasarkan tag secara descending

Nilai FilterLogicalOperator

Nilai Deskripsi
AND Semua kondisi harus cocok
OR Setiap kondisi harus cocok

Penyaringan Bidang Kustom

Parameter fields mendukung penyaringan lanjutan berdasarkan bidang kustom:

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

Struktur Filter Bidang Kustom

Bidang Tipe Deskripsi
type String Harus "CUSTOM_FIELD"
customFieldId String ID bidang kustom
customFieldType String Tipe bidang kustom
values [String!] Nilai untuk disaring
op String Operator perbandingan (IN, NOT_IN, EQ, dll.)

Tipe Bidang Kustom yang Didukung

  • Bidang teks: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
  • Bidang numerik: CURRENCY, NUMBER, FORMULA
  • Bidang pilihan: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
  • Bidang referensi: REFERENCE, LOOKUP
  • Bidang tanggal: DATE

Bidang Respon

TodosResult

Bidang Tipe Deskripsi
items [Todo!]! Array dari rekaman todo
pageInfo PageInfo! Metadata paginasi

PageInfo

Bidang Tipe Deskripsi
totalPages Int Total jumlah halaman yang tersedia
totalItems Int Total jumlah item di semua halaman
page Int Nomor halaman saat ini (dihitung dari skip/limit)
perPage Int Jumlah item per halaman
hasNextPage Boolean! Apakah ada halaman berikutnya
hasPreviousPage Boolean! Apakah ada halaman sebelumnya

Bidang Todo

Bidang Tipe Deskripsi
id ID! Pengidentifikasi unik
uid String! Pengidentifikasi unik yang ramah pengguna
position Float! Posisi dalam daftar
title String! Judul todo
text String! Konten teks biasa
html String! Konten terformat HTML
startedAt DateTime Tanggal/waktu mulai
duedAt DateTime Tanggal/waktu jatuh tempo
timezone String Zona waktu untuk tanggal
color String Indikator warna visual
cover String URL gambar sampul
done Boolean! Status penyelesaian
archived Boolean! Status arsip
createdAt DateTime! Timestamp pembuatan
updatedAt DateTime! Timestamp pembaruan terakhir
commentCount Int! Jumlah komentar
checklistCount Int! Total item checklist
checklistCompletedCount Int! Item checklist yang telah selesai
isRepeating Boolean! Apakah todo berulang
isRead Boolean Status baca untuk pengguna saat ini
isSeen Boolean Status terlihat untuk pengguna saat ini
todoList TodoList! Daftar todo induk
users [User!]! Pengguna yang ditugaskan
tags [Tag!]! Tag yang terkait
checklists [Checklist!]! Checklist yang terkait
createdBy User Pengguna yang membuat todo
customFields [CustomField!]! Nilai bidang kustom
dependOn [Todo!] Todos yang memblokir (ketergantungan)
dependBy [Todo!] Todos yang tergantung (diblokir oleh ini)
timeTracking TimeTracking Data pelacakan waktu

Izin yang Diperlukan

Pengguna harus memiliki akses yang sesuai untuk mengkueri rekaman:

Tipe Akses Persyaratan
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

Pembatasan Khusus:

  • Pengguna dengan izin showOnlyAssignedTodos hanya dapat melihat todos yang ditugaskan kepada mereka
  • Daftar todo yang tersembunyi (berdasarkan konfigurasi peran) secara otomatis dikecualikan
  • Izin berbasis tag dapat lebih menyaring hasil

Respon Kesalahan

Kesalahan Umum

Kuery menangani kesalahan dengan baik dan mengembalikan hasil kosong untuk:

  • ID perusahaan yang tidak valid
  • Proyek yang tidak dapat diakses
  • Skenario izin ditolak

Untuk kesalahan yang parah, kesalahan GraphQL mungkin dikembalikan:

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

Catatan Penting

Kinerja

  • Batas default: 20 item per halaman (secara otomatis diterapkan jika tidak ditentukan)
  • Batas maksimum: 500 item per permintaan (secara otomatis dibatasi)
  • Optimisasi: Kuery menggunakan gabungan yang dioptimalkan dengan STRAIGHT_JOIN untuk kinerja terbaik
  • Pengindeksan: Bidang filter umum diindeks untuk kueri cepat
  • Bidang kustom: Dukungan penyaringan bidang kustom yang luas dengan dampak kinerja minimal
  • Kuery geografis: Mendukung penyaringan koordinat berbasis poligon untuk tampilan peta

Penyaringan Tanggal

  • Rentang tanggal bersifat inklusif
  • Mendukung rentang tanggal yang tumpang tindih (todos yang mulai atau berakhir dalam rentang)
  • Tanggal null ditangani dengan baik (todos tanpa tanggal jatuh tempo tidak akan cocok dengan filter tanggal)
  • Semua tanggal harus dalam format ISO 8601

Perilaku Pencarian

  • Pencarian tidak peka huruf besar/kecil
  • Mencari di judul dan konten teks
  • Pencocokan kata sebagian didukung
  • Karakter khusus ditangani dengan tepat

Strategi Paginasi

  • Gunakan skip dan limit untuk paginasi berbasis offset
  • Hitung halaman saat ini: page = Math.floor(skip / limit) + 1
  • Untuk dataset besar, pertimbangkan untuk menggunakan filter untuk mengurangi ukuran hasil
  • Selalu periksa hasNextPage sebelum meningkatkan skip

Endpoint Terkait

  • Buat Rekaman: Gunakan mutasi createTodo untuk membuat rekaman baru
  • Perbarui Rekaman: Gunakan mutasi updateTodo untuk memodifikasi rekaman
  • Hapus Rekaman: Gunakan mutasi deleteTodo untuk menghapus rekaman
  • Daftar Bidang Kustom: Kuery bidang kustom yang tersedia untuk penyaringan
  • Daftar Proyek: Kuery proyek yang tersedia untuk penyaringan
© Blue | Dirancang dengan ❤ di seluruh

Asisten AI

Respon dihasilkan menggunakan AI dan mungkin mengandung kesalahan.

Bagaimana saya bisa membantu Anda?

Tanyakan apa saja tentang Blue atau dokumentasi ini.

Masukkan untuk mengirim • Shift+Masukkan untuk baris baru • ⌘I untuk membuka