코딩 에이전트와 함께 이 문서를 사용하세요.

Claude Code, Codex, Cursor 또는 다른 코딩 에이전트에 대한 집중 프롬프트 팩을 연 다음 여기에서 다루는 워크플로에 맞게 조정하세요.

이 페이지에서

언제 사용하나요?
가장 유용한 열을 먼저 배치하세요.
가지치기를 활성화하는 필터
피해야 할 것
출시 워크플로
API를 통해 구성

파티션 열 선택

파티션 열은 Telemetry가 요청된 값을 포함할 수 없는 부분을 건너뛸 수 있도록 하여 선택적 쿼리를 훨씬 더 빠르게 만들 수 있습니다. 이는 대규모 테이블에서 하나의 고객, 서비스, 환경, 추적 또는 이벤트 유형을 반복적으로 조사하는 에이전트 및 자동화된 워크플로에 특히 유용합니다.

SQL PARTITION BY와 동일하지 않으며 쿼리 결과를 변경하지 않습니다. Telemetry는 데이터를 쓸 때 구성된 값을 해시하고 각 부분과 함께 해당 파티션 정보를 기록합니다. 쿼리 시 호환되는 필터는 동일한 방식으로 해시되므로 관련되지 않은 부분은 해당 데이터를 읽기 전에 제외할 수 있습니다.

언제 사용하나요?

다음 사항이 모두 충족되면 테이블을 분할합니다.

테이블에 충분한 데이터나 부분이 있어서 스캔하는 것이 중요한 작업입니다.
중요한 쿼리는 동일한 필드를 반복적으로 필터링합니다.
이러한 필터는 일반적으로 테이블의 작은 부분을 선택합니다.
필드가 문자열, 부울 또는 숫자형 스칼라인 경우

좋은 후보로는 account_id, workspace_id, service, environment, event 및 request.region와 같은 안정적인 중첩 필드가 있습니다.

계정별로 사건을 조사하는 에이전트의 경우 account_id가 강력한 첫 번째 열인 경우가 많습니다.

SELECT timestamp_utc, event, message
FROM app_events
WHERE account_id = 'acct_123'
  AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC

시간 조건자는 여전히 시간 창을 좁힙니다. 또한 계정 조건자를 사용하면 Telemetry가 해당 창 내부의 분할된 부분을 정리할 수 있습니다.

가장 유용한 열을 먼저 배치하세요.

열 순서는 선행 접두사 계층 구조를 정의합니다. 주어진:

{
  "partitionColumns": ["account_id", "event"]
}

Telemetry는 다음을 기준으로 필터링하는 쿼리에 파티션 정리를 사용할 수 있습니다.

account_id
account_id 및 event

첫 번째 열이 누락되었기 때문에 event로만 필터링하는 쿼리에는 이 레이아웃을 사용할 수 없습니다. 가장 광범위한 중요한 쿼리 집합에 대해 첫 번째 열을 선택한 다음 쿼리가 일반적으로 두 가지를 모두 기준으로 필터링하는 경우에만 다른 열을 추가하세요.

하나의 열로 시작하세요. 개선된 쿼리 패턴을 설명할 수 있는 후에만 1초를 추가하세요. 긴 열 목록은 점점 더 좁은 쓰기 및 압축 그룹을 생성하는 반면, 이후 열은 더 적은 쿼리에 도움이 됩니다.

가지치기를 활성화하는 필터

Telemetry는 현재 리터럴 동등성, 양수 IN 및 AND와 결합된 IS NULL 조건자에서 파티션 가지치기를 파생합니다.

WHERE account_id = 'acct_123'

WHERE account_id IN ('acct_123', 'acct_456')

WHERE account_id = 'acct_123'
  AND event IN ('request_failed', 'request_retried')

WHERE account_id IS NULL

범위 술어, 부정 및 모호한 OR 표현식은 파티션 가지치기를 생성하지 않습니다. 예를 들어, duration_ms에서의 파티셔닝은 duration_ms > 1000에 도움이 되지 않습니다. 쿼리는 여전히 정확합니다. 그들은 최적화 없이 단순히 스캔합니다.

중첩된 스칼라 경로도 작동합니다.

{
  "partitionColumns": ["request.region"]
}

SELECT count(*)
FROM app_events
WHERE request.region = 'us-west-2'

목록, 개체 및 타임스탬프는 파티션 열로 지원되지 않습니다. 타임스탬프 필터링에는 이미 자체 정리 경로가 있으며 일반적으로 쿼리 시간 범위로 더 잘 표현됩니다.

피해야 할 것

단지 모든 이벤트에 존재한다는 이유만으로 필드를 선택하지 마십시오. 유용한 파티션 열은 빈번하고 선택적인 쿼리를 반영합니다.

다음 사항에 주의하세요.

거의 모든 쿼리가 무시하는 필드
주로 범위, LIKE 또는 부정으로 쿼리되는 필드
쿼리가 거의 반복되지 않는 경우 값이 빠르게 변하거나 제한되지 않음
선행 접두사가 실제 쿼리 패턴과 일치하지 않는 여러 열

낮은 카디널리티 필드는 테이블의 많은 부분을 제거할 때 여전히 유용할 수 있습니다(예: environment = 'production'). 높은 카디널리티 식별자는 포인트 조사에 탁월할 수 있지만 쓰기 및 압축이 조각화될 수 있습니다. 단순히 가장 고유한 값이 있는 필드보다는 실제로 관심 있는 쿼리에서 가장 많은 데이터를 제거하는 필드를 선호하세요.

출시 워크플로

사람, 대시보드, 알림 및 에이전트가 실행하는 쿼리를 검사합니다. 가장 비용이 많이 드는 선택 쿼리가 공유하는 같음 필터를 식별합니다.
GET /tables/<table>/schema로 필드와 유형을 확인합니다.
테이블 설정 UI 또는 테이블 API를 통해 하나의 파티션 열을 구성합니다.
중요한 쿼리의 시간 필터를 유지하세요. 파티션 가지치기는 시간 가지치기를 대체하는 것이 아니라 보완합니다.
기존 데이터를 다시 쓸 시간이 지나면 대표 쿼리를 다시 실행하세요. 단 한 번의 웜 캐시 실행이 아닌 스캔된 작업과 대기 시간을 비교하세요.
일반 쿼리가 첫 번째 열과 두 번째 열을 함께 필터링하는 경우에만 두 번째 열을 추가합니다.

새로운 데이터는 변경된 파티션 사양을 즉시 사용합니다. 기존 부분은 백그라운드에서 다시 작성되고 다시 작성되지 않은 부분은 쿼리 가능한 상태로 유지되므로 마이그레이션 중에도 결과가 완전한 상태로 유지됩니다. 더 많은 테이블이 새로운 레이아웃을 채택함에 따라 성능이 점진적으로 향상됩니다.

API를 통해 구성

curl -X PATCH https://api.telemetry.sh/tables/app_events/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": ["account_id", "event"]
  }'

순서를 변경하려면 원하는 목록 전체를 보내십시오. 파티셔닝을 끄려면 null 또는 빈 배열을 보내십시오.

curl -X PATCH https://api.telemetry.sh/tables/app_events/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{"partitionColumns": null}'

API는 테이블의 현재 스키마에 대해 필드의 유효성을 검사합니다. 정확한 요청 및 응답 계약은 테이블 API 참조를 참조하세요.

소유권 및 기술 참조

이 설명은 Telemetry 편집팀의 소유입니다. 제품 팀은 동작, 예시, 경계를 검토합니다.

편집 기준 검토