중첩된 JSON 쿼리하기

Telemetry는 중첩된 JSON 개체를 쿼리 가능한 점으로 구분된 필드 경로로 변환합니다. 이는 수집 시 관련 컨텍스트를 함께 유지하는 동시에 SQL에서 개별 값을 계속 사용할 수 있도록 합니다.

이 가이드에서는 이벤트 계약부터 필터, 집계, 스키마 변경 및 문제 해결까지의 전체 경로를 다룹니다. 쿼리를 복사하기 전에 테이블 스키마를 검사하세요. 정확한 식별자 철자와 유형은 보낸 이벤트에서 가져옵니다.

안정적인 중첩 이벤트 디자인

필드가 하나의 지속성 개념을 형성하는 경우 중첩된 개체를 사용합니다. 값을 입력된 상태로 유지하고, 민감한 페이로드를 생략하고, 자주 변경되는 구조를 배열에 배치하지 마세요.

{
  "event_name": "tool_call_completed",
  "event_id": "evt_7f31",
  "account_id": "acct_8f31",
  "release": "2026.07.3",
  "workflow": {
    "name": "answer_question",
    "version": "v2"
  },
  "tool": {
    "name": "inventory_lookup",
    "outcome": "success",
    "duration_ms": 184,
    "usage": {
      "input_units": 820,
      "output_units": 244
    }
  }
}

행 그레인은 하나의 완료된 도구 호출입니다. tool.duration_ms는 항상 숫자이고, tool.outcome는 제어된 세트에서 나오며 식별자는 가명입니다. 요청 인수, 모델 프롬프트, 생성된 콘텐츠, 자격 증명 및 원시 오류 메시지는 의도적으로 없습니다.

SDK를 통해 객체를 보냅니다.

await telemetry.log("tool_call_completed", event);

로그 API는 쿼리에 사용되는 관리 이벤트 시간을 추가하고 null 값, 빈 개체 및 빈 배열을 반복적으로 제거합니다. 빈 값을 비즈니스 상태로 사용하기 전에 이벤트 데이터 유형 및 null 허용 여부를 읽어보세요.

집계하기 전에 검사하세요.

제한된 샘플로 시작하십시오. 테이블 스키마에 따라 중첩 경로는 복합 식별자로 표시되거나 큰따옴표로 묶인 점으로 구분된 식별자 하나가 필요할 수 있습니다.

SELECT
  timestamp_utc,
  event_id,
  workflow.name,
  tool.name,
  tool.outcome,
  tool.duration_ms
FROM tool_call_completed
WHERE timestamp_utc >= now() - INTERVAL '1 hour'
ORDER BY timestamp_utc DESC
LIMIT 50;

스키마가 리터럴 점으로 구분된 열 이름을 노출하는 경우 전체 경로를 인용하십시오.

SELECT
  "workflow.name",
  "tool.name",
  "tool.duration_ms"
FROM tool_call_completed
LIMIT 50;

추측으로 인용된 형식과 인용되지 않은 형식 사이를 전환하지 마십시오. 테이블 스키마를 확인하고, 작은 샘플을 실행하고, 저장된 필드와 일치하는 양식을 사용하세요.

중첩된 필드 필터링 및 집계

중첩된 필드는 필터, 그룹, 계산 및 순서 지정에서 작동합니다. 이 쿼리는 제한된 전체 창에 걸쳐 도구 볼륨, 오류 및 p95 기간을 비교합니다.

SELECT
  tool.name AS tool_name,
  COUNT(*) AS calls,
  SUM(CASE WHEN tool.outcome = 'error' THEN 1 ELSE 0 END) AS errors,
  100.0 * SUM(CASE WHEN tool.outcome = 'error' THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS error_rate_pct,
  approx_percentile_cont(tool.duration_ms, 0.95) AS p95_duration_ms
FROM tool_call_completed
WHERE timestamp_utc >= now() - INTERVAL '7 days'
  AND workflow.name = 'answer_question'
GROUP BY tool.name
HAVING COUNT(*) >= 20
ORDER BY error_rate_pct DESC, calls DESC;

테이블이 따옴표로 묶인 점 식별자를 사용하는 경우 동일한 쿼리에서 각 전체 경로를 인용하십시오.

SELECT
  "tool.name" AS tool_name,
  approx_percentile_cont("tool.duration_ms", 0.95) AS p95_duration_ms
FROM tool_call_completed
WHERE "workflow.name" = 'answer_question'
GROUP BY "tool.name";

누락된 경로를 의도적으로 처리

tool.usage.output_units가 도입되기 전에 생성된 이전 행에는 해당 필드가 없습니다. null, 빈 개체 또는 빈 배열 값이 있는 새 이벤트도 정규화 후 해당 경로에 대한 값을 저장하지 않습니다.

새로운 필드에 의존하기 전에 IS NULL를 사용하여 적용 범위를 측정하십시오.

SELECT
  release,
  COUNT(*) AS calls,
  SUM(CASE WHEN tool.usage.output_units IS NULL THEN 1 ELSE 0 END)
    AS missing_output_units,
  100.0 * SUM(CASE WHEN tool.usage.output_units IS NULL THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS missing_rate_pct
FROM tool_call_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY release
ORDER BY release;

0이 올바른 비즈니스 의미가 아닌 한 누락된 숫자를 0으로 바꾸지 마십시오. "보고되지 않음", "해당 없음" 및 실제 측정된 영점은 서로 다른 상태입니다.

중첩된 경로를 안전하게 발전시키세요

각 점선 경로를 스키마 계약으로 처리합니다.

모든 깊이에서 동일한 의미와 유형을 유지하십시오. 선택적 중첩 필드를 추가하는 것은 일반적으로 호환됩니다. 경로 유형을 변경하거나 새로운 의미로 재사용하는 것은 아닙니다.

언제 평탄화할지 결정

중첩된 개체는 tool, workflow 또는 billing와 같은 안정적인 네임스페이스에 유용합니다. 거의 모든 쿼리나 대시보드에서 플랫 필드를 사용하면 더 좋을 수 있습니다.

다음과 같은 경우에는 평평하거나 별도로 방출되는 필드를 선호합니다.

• 값은 행 단위 또는 기본 이벤트 결과를 정의합니다.
• 운영자는 거의 모든 조사에서 이를 스캔해야 합니다.
• 여러 프로듀서가 하나의 중첩 구조에 동의할 수 없습니다.
• 배열은 실제로 여러 개의 독립적인 결과를 나타냅니다.

나중에 중첩에서 평면으로 변경하는 것은 스키마 마이그레이션입니다. 페이로드 미학이 아닌 질문과 소유권 경계를 기준으로 선택하세요.

중첩 필드 쿼리 문제 해결

쿼리가 중첩된 경로를 찾을 수 없는 경우:

1. LIMIT 50를 사용하여 최근 원시 샘플을 쿼리합니다.
2. 정확한 점으로 구분된 이름과 유형을 확인하려면 테이블 스키마를 검사하세요.
3. 다른 SQL 방언에서 JSON 추출 구문을 추가하는 대신 스키마의 인용 식별자 형식을 사용해 보세요.
4. 프로듀서가 실제로 null이 아니고 비어 있지 않은 값을 보냈는지 확인하세요.
5. release 또는 프로듀서 버전별로 누락된 값을 그룹화합니다.
6. 이전 프로듀서와 새 프로듀서 간의 유형 변경을 확인하세요.
7. 조인 또는 집계를 복원하기 전에 쿼리를 하나의 필드와 하나의 최근 기간으로 줄입니다.

Telemetry는 DataFusion SQL을 사용하므로 다른 시스템에서 복사한 PostgreSQL, BigQuery, Snowflake 또는 MySQL JSON 기능은 적용되지 않을 수 있습니다. DataFusion SQL 참조에서 연습된 구문을 사용합니다.

프로덕션 체크리스트

• 모든 중첩된 개체에 하나의 지속 가능한 의미와 소유자를 부여합니다.
• 모든 경로의 유형, 단위 및 제어된 값을 안정적으로 유지합니다.
• 비밀, 사용자 콘텐츠, 원시 페이로드, 무제한 오류 텍스트를 제외합니다.
• 성공, 실패, 누락 필드 및 이전 버전 픽스처를 테스트합니다.
• 대시보드나 알림이 이에 의존하도록 만들기 전에 새로운 필드 채택을 측정하세요.
• 행 단위, 보존 요구 사항 및 마이그레이션 계획을 문서화합니다.

이벤트 스키마 설계, 스키마 진화 및 필수 필드 null 비율 레시피를 계속 진행하세요.