SQL 쿼리 문제 해결

SQL 쿼리는 실행에 실패하거나, 행을 반환하지 않거나, 그럴듯하지만 잘못된 결과를 생성할 수 있습니다. 그것들을 다른 문제로 취급하십시오. 테이블, 스키마, 시간 범위를 증명하는 가장 작은 읽기부터 시작한 다음 분석 논리를 한 번에 한 단계씩 복원합니다.

Telemetry는 Apache DataFusion SQL을 사용합니다. 분석 아이디어가 타당하더라도 PostgreSQL, BigQuery, Snowflake, MySQL 또는 다른 엔진에서 복사한 구문을 다시 작성해야 할 수도 있습니다.

1. 응답 클래스 읽기

동기 쿼리 API의 경우:

• 400는 일반적으로 잘못된 JSON, SQL 누락, 호환되지 않는 SQL, 테이블 또는 필드 누락 또는 유형 오류를 의미합니다.
• 401는 API 키가 누락되었거나 유효하지 않음을 의미합니다.
• 403는 키에 읽기 범위가 없음을 의미합니다.
• 429는 요청이 대기하고 제한된 백오프를 사용해야 함을 의미합니다.
• 5xx는 제한된 횟수만큼 재시도될 수 있습니다.

잘못된 SQL을 변경하지 않고 다시 시도하지 마세요. 안전한 오류 텍스트, 엔드포인트 및 요청 ID를 캡처하되 단순히 쿼리가 실패했다는 이유로 키를 기록하지 마십시오.

비동기 쿼리에서는 queued, running, completed, failed, cancelled를 구분하세요. 작은 JSON 결과는 result에서 직접 읽고, 큰 JSON 결과와 Parquet 파일은 download_url에서 다운로드하세요. 쿼리 결과 내보내기를 참조하세요.

2. 테이블과 시간 범위 증명

원래 쿼리를 제한된 샘플로 바꿉니다.

SELECT *
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC
LIMIT 10;

행이 반환되지 않는 경우:

1. 정규화된 테이블 이름 확인
2. UTC 시간 범위를 넓히세요
3. 선택적 필터 제거
4. 테이블 보기에서 최근 샘플 행과 스키마를 검사합니다.
5. 고유 식별자가 포함된 합성 이벤트 전송

합성 행도 누락된 경우 SQL을 추가로 편집하기 전에 이벤트 수집 문제 해결을 따르세요.

3. 필드 이름 및 유형 비교

애플리케이션 코드에서 열 이름을 유추하지 마세요. 중첩된 점 경로와 정확한 유형을 포함하여 테이블 스키마를 검사합니다.

일반적인 오류는 다음과 같습니다.

• 생성된 timestamp_utc 대신 timestamp를 쿼리합니다.
• 이벤트 계약이 duration_ms를 저장할 때 duration 사용
• 정수 상태 코드를 문자열과 비교
• 프로듀서가 유형을 변경한 후 숫자 식별자를 텍스트로 처리
• 저장된 스키마에 필요한 식별자 형식 없이 중첩 경로 참조
• 숫자가 아닌 필드 집계

간단한 SELECT의 정확한 필드부터 시작하세요. 그런 다음 비교, 함수 또는 집계를 추가합니다. 이는 문제가 열 해결인지 아니면 열에 적용된 작업인지 식별합니다.

4. 레이어별 쿼리 감소

여러 CTE, 조인 및 창이 포함된 쿼리의 경우:

1. 첫 번째 CTE를 단독으로 실행
2. 다음 CTE를 추가하고 행 그레인을 검사합니다.
3. 식별자와 행 개수를 표시하여 각 조인을 테스트합니다.
4. 조인된 행이 올바른 후에 집계를 추가하세요.
5. 창 계산을 마지막에 추가

COUNT(*) 및 COUNT(DISTINCT account_id)와 같은 임시 진단 열을 사용하여 행 곱셈을 검색합니다. 결과 그레인을 이해한 후에만 제거하십시오.

5. 지원되지 않는 방언 구문 번역

DataFusion SQL 참조 및 테스트된 레시피 라이브러리에 설명된 구문을 사용하세요. 특히:

• 조건부 카운트에는 SUM(CASE WHEN condition THEN 1 ELSE 0 END)를 사용하세요.
• 대략적인 p95에는 approx_percentile_cont(latency_ms, 0.95)를 사용하십시오.
• 시간 버킷에는 date_trunc('hour', timestamp_utc)를 사용하세요.
• now() - INTERVAL '24 hours'와 같은 간격 산술을 사용하십시오.
• NULLIF(denominator, 0)로 비율 보호
• 이전 버킷 비교를 위해 LAG(value) OVER (ORDER BY bucket)를 사용하세요.

함수 이름과 서명은 방언별로 다릅니다. 다른 데이터베이스에 있는 동일한 목적을 가진 함수는 DataFusion가 해당 철자를 허용한다는 증거가 아닙니다.

6. 빈 결과 진단

빈 결과는 누락된 데이터가 아닌 필터 상호작용인 경우가 많습니다. 한 번에 하나씩 조건자를 제거합니다.

SELECT
  environment,
  status,
  COUNT(*) AS events
FROM workflow_events
WHERE timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY environment, status
ORDER BY events DESC;

이렇게 하면 실제로 저장된 값이 노출됩니다. 좁은 술어를 복원하기 전에 대소문자, 공백, 널, 이름이 변경된 상태, 환경 경계 및 불완전한 최근 기간을 확인하십시오.

유입경로 및 집단의 경우 모든 마일스톤이 동일한 ID 단위를 사용하고 관찰 기간이 이후 단계가 발생할 수 있을 만큼 충분히 긴지 확인합니다.

7. 합계 전 조인 감사

한 줄이 각 변에 무엇을 나타내는지 적어보세요. 양쪽에 식별자당 여러 행이 포함된 경우 직접 조인을 통해 수익, 이벤트 수 또는 활성 사용자가 늘어날 수 있습니다.

각 측면을 의도한 그레인으로 사전 집계합니다.

WITH requests AS (
  SELECT
    request_id,
    MIN(timestamp_utc) AS requested_at
  FROM request_events
  GROUP BY request_id
),
outcomes AS (
  SELECT
    request_id,
    MAX(CASE WHEN status = 'success' THEN 1 ELSE 0 END) AS succeeded
  FROM outcome_events
  GROUP BY request_id
)
SELECT
  COUNT(*) AS requests,
  SUM(COALESCE(outcomes.succeeded, 0)) AS succeeded
FROM requests
LEFT JOIN outcomes ON requests.request_id = outcomes.request_id;

조인 전후의 고유 식별자를 비교합니다. 내부 조인을 통해 누락된 결과를 지우는 대신 의도적으로 일치하지 않는 행을 포함합니다.

8. 요율, 백분위수, 창 검증

비율에는 분자와 분모가 모두 필요합니다. 계산이 신뢰할 수 있을 때까지 백분율 옆에 반환하고 그룹 순위를 지정하기 전에 최소 의미 있는 볼륨을 설정합니다.

백분위수는 하나의 문서화된 단위가 포함된 숫자 필드를 사용해야 합니다. 전체 분포가 변경되었는지 아니면 꼬리만 변경되었는지 이해하려면 p50과 p95를 비교하세요.

롤링 윈도우에는 계열이 시작될 때 관측치가 더 적습니다. 최신 시간 버킷이 불완전할 수 있습니다. 롤링 기준선에 대해 알림하기 전에 두 조건 모두에 레이블을 지정하거나 제외합니다.

9. Fixtures를 사용하여 예상 결과 증명

답을 손으로 계산할 수 있는 작은 합성 고정 장치를 만듭니다.

• 한 번의 성공
• 한 번의 영구적인 실패
• 나중에 복구되는 하나의 실패
• 중복 식별자 1개
• 하나의 null 선택적 필드
• 정확히 시간 경계에 있는 하나의 사건

중간 CTE를 실행하고 최종 행을 예상 답변과 비교합니다. 계획을 통해 구문과 유형을 증명합니다. 고정 장치는 해석을 증명하는 데 도움이 됩니다.

쿼리 검토 체크리스트

• 정확한 테이블과 스키마 검사
• UTC 기간 및 버킷 완전성이 확인되었습니다.
• 필드 유형 및 단위가 작업과 일치합니다.
• 모든 조인 전에 행 그레인이 문서화됨
• 분자, 분모 및 최소 볼륨 표시
• 재시도, 중복, 지연 이벤트 및 null에는 명시적인 동작이 있습니다.
• 합성 경계 케이스가 예상 출력과 일치함
• 저장된 결과에는 정의, 소유자 및 응답이 포함됩니다.

Telemetry는 SQL 테스트 방법론에 엔진 버전과 자동 검사를 게시합니다. 알려진 호환 패턴이 필요할 때 API 신뢰성, 백그라운드 작업, 제품 분석 또는 데이터 품질의 레시피에서 시작하세요.