말로 주문한 파이프라인, 리뷰어는 무엇을 봐야 할까: BigQuery Data Engineering Agent

파이프라인을 말로 만드는 시대

Next '26의 데이터 실무 도구 발표 중 가장 많이 회자된 건 BigQuery의 Data Engineering Agent였습니다.

자연어로 요청하면 Dataform 파이프라인을 만들어 줍니다. 기존 파이프라인을 고치는 것도 됩니다. 파이프라인이 실패하면 실행 로그를 읽고 원인과 수정안을 제시합니다.

같이 발표된 Data Agent Kit은 이 능력을 BigQuery 콘솔 밖으로 꺼냅니다. VS Code와 Gemini CLI에서 쓸 수 있는 스킬, MCP 도구, 플러그인 묶음입니다. 노트북 안에서는 Data Science Agent가 비슷한 역할을 합니다.

데모는 매끄러웠습니다. 문제는 데모가 끝난 다음입니다.

그럴듯한 코드가 가장 위험하다

에이전트에게 이런 요청을 한다고 해 봅시다.

"위키 문서 스테이징 테이블에서 매일 변경된 문서만 본 테이블에 반영하는 파이프라인 만들어 줘."

에이전트는 몇 초 만에 SQLX 파일을 만들어 냅니다. 읽어 보면 문법도 깔끔하고, 주석도 친절합니다. 첫 실행도 성공합니다.

그런데 이 요청에는 말하지 않은 조건이 숨어 있습니다. 같은 날 배치를 두 번 돌리면 어떻게 되는가. 늦게 도착한 어제 문서는 어떻게 되는가. 문서 ID가 비어 있는 행이 들어오면 어떻게 되는가.

앞선 Cloud Run 글에서 Staging 테이블과 MERGE를 쓴 이유가 바로 이것이었습니다. 언제 몇 번을 다시 돌려도 결과가 같아야 한다는 것. 사람이 쓴 코드에서도 자주 빠지는 조건인데, 요청에 적지 않았다면 에이전트가 알아서 챙겨 줄 거라고 기대하기 어렵습니다.

리뷰에서 가장 먼저 보는 네 가지

그래서 에이전트가 만든 Dataform 코드를 볼 때 확인할 순서를 정해 두었습니다. 문법이나 스타일은 뒤로 미룹니다.

1. 증분인가, 전체 갱신인가. type: "table"이면 매번 테이블을 통째로 다시 만듭니다. 작은 테이블에는 괜찮지만, 문서 수만 건짜리 테이블이라면 비용이 매일 쌓입니다.

2. 증분이라면 uniqueKey가 있는가. 이게 없으면 Dataform은 새 행을 그냥 덧붙입니다. 같은 날 두 번 돌리면 데이터가 두 벌이 됩니다. uniqueKey가 있어야 MERGE로 동작합니다.

3. 증분 조건이 늦게 온 데이터를 놓치지 않는가. MAX(updated_at) 이후만 가져오는 조건은 흔하지만, 원본 시스템의 타임스탬프가 뒤섞여 들어오면 일부를 영영 놓칩니다.

4. 품질 검사(assertion)가 있는가. 키가 비었거나 중복된 행이 들어왔을 때 파이프라인이 멈추는지 확인합니다.

이 네 가지를 반영하면 코드는 대략 이런 모양이 됩니다.

config {
  type: "incremental",
  uniqueKey: ["doc_id"],
  bigqueryOptions: {
    partitionBy: "DATE(updated_at)",
    clusterBy: ["doc_id"]
  },
  assertions: {
    nonNull: ["doc_id", "title"],
    uniqueKey: ["doc_id"]
  }
}

SELECT doc_id, title, content, version, updated_at
FROM ${ref("documents_staging")}
${ when(incremental(),
  `WHERE updated_at > (
     SELECT TIMESTAMP_SUB(MAX(updated_at), INTERVAL 2 DAY) FROM ${self()}
   )`) }
QUALIFY ROW_NUMBER() OVER (PARTITION BY doc_id ORDER BY version DESC) = 1

증분 조건에서 이틀을 겹쳐 읽는 부분이 핵심입니다. 늦게 도착한 데이터를 다시 훑고, 중복은 uniqueKey와 QUALIFY가 걸러 냅니다. 조금 더 읽는 비용으로 놓치는 문서를 없애는 거래입니다.

요청을 바꾸면 결과가 바뀐다

흥미로운 건, 이 체크리스트를 요청문에 그대로 넣으면 에이전트가 처음부터 꽤 비슷한 코드를 만든다는 점입니다.

"doc_id 기준 멱등하게, 늦게 도착하는 데이터를 2일까지 허용하고, doc_id null·중복이면 실패하도록."

결국 리뷰 체크리스트가 곧 좋은 요청서였습니다. 이걸 팀 공용 템플릿으로 만들어 두면 리뷰 부담이 눈에 띄게 줄어듭니다. Data Agent Kit이 "스킬"이라는 형태로 이런 지침을 재사용할 수 있게 한 것도 같은 맥락으로 읽힙니다.

장애 분석은 맡기되, 수정은 리뷰를 거치게

로그를 읽고 원인을 짚어 주는 기능은 정말 반갑습니다. 새벽에 파이프라인이 실패했을 때, 로그 수백 줄을 직접 뒤지는 시간이 줄어드니까요.

다만 원인 분석과 수정 적용은 분리하는 게 좋다고 봅니다. 에이전트가 "스키마 불일치로 실패했으니 컬럼 타입을 STRING으로 바꾸겠습니다"라고 제안한다고 해 봅시다. 기술적으로는 맞는 수정입니다. 그런데 그 결정 하나로 하위 대시보드의 숫자 집계가 전부 깨질 수 있습니다.

Next '26에서 데이터 품질 규칙 재사용, 구조화된 승인 워크플로, 컬럼 단위 리니지가 함께 발표된 것도 우연은 아닐 겁니다. 코드를 만드는 속도가 빨라질수록, 그 코드가 무엇을 건드리는지 보여주는 장치가 더 필요해집니다.

에이전트는 파이프라인을 빨리 쓰게 해줍니다. 하지만 "완료"의 기준을 정하는 건 여전히 우리입니다. 그 기준을 글로 적어 두는 팀이 에이전트의 덕을 가장 많이 볼 거라고 생각합니다.