회원가입
문의 로그인 회원가입
시스템 상태

강력한 검색 및 페이지 매김 옵션을 사용하여 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!]! ✅ 예 쿼리할 회사 ID 또는 슬러그
projectIds [String!] 아니요 특정 프로젝트 ID 또는 슬러그로 필터링
todoIds [String!] 아니요 ID로 특정 할 일을 검색
assigneeIds [String!] 아니요 할당된 사용자 ID로 필터링
tagIds [String!] 아니요 태그 ID로 필터링
tagColors [String!] 아니요 태그 색상으로 필터링 (16진수 형식)
tagTitles [String!] 아니요 태그 제목으로 필터링
todoListIds [String!] 아니요 할 일 목록 ID로 필터링
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 사용자 정의 필드의 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!]! 할 일 레코드의 배열
pageInfo PageInfo! 페이지 매김 메타데이터

PageInfo

필드 유형 설명
totalPages Int 사용 가능한 총 페이지 수
totalItems Int 모든 페이지의 총 항목 수
page Int 현재 페이지 번호 (건너뛰기/제한에서 계산됨)
perPage Int 페이지당 항목 수
hasNextPage Boolean! 다음 페이지가 있는지 여부
hasPreviousPage Boolean! 이전 페이지가 있는지 여부

할 일 필드

필드 유형 설명
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 권한이 있는 사용자는 자신에게 할당된 할 일만 볼 수 있습니다.
  • 숨겨진 할 일 목록 (역할 구성에 따라) 자동으로 제외됩니다.
  • 태그 기반 권한이 결과를 추가로 필터링할 수 있습니다.

오류 응답

일반 오류

쿼리는 오류를 우아하게 처리하고 다음에 대해 빈 결과를 반환합니다:

  • 잘못된 회사 ID
  • 접근할 수 없는 프로젝트
  • 권한 거부 시나리오

심각한 오류의 경우 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를 확인하십시오.

관련 엔드포인트

  • 레코드 생성: createTodo 변이를 사용하여 새 레코드를 생성합니다.
  • 레코드 업데이트: updateTodo 변이를 사용하여 레코드를 수정합니다.
  • 레코드 삭제: deleteTodo 변이를 사용하여 레코드를 제거합니다.
  • 사용자 정의 필드 목록: 필터링을 위해 사용 가능한 사용자 정의 필드를 쿼리합니다.
  • 프로젝트 목록: 필터링을 위해 사용 가능한 프로젝트를 쿼리합니다.
© Blue | 사랑으로 디자인 ❤ 전체에 걸쳐

AI 어시스턴트

응답은 AI를 사용하여 생성되며 오류가 포함될 수 있습니다.

어떻게 도와드릴까요?

Blue 또는 이 문서에 대해 궁금한 점이 있으면 무엇이든 물어보세요.

전송하려면 Enter • 새 줄을 추가하려면 Shift+Enter • ⌘I를 눌러 열기