데이터 엔지니어링 에이전트를 사용하여 데이터 파이프라인 빌드 및 수정

데이터 엔지니어링 에이전트를 사용하면 BigQuery의 Gemini를 사용하여 데이터 파이프라인을 빌드, 수정, 관리하여 BigQuery에서 데이터를 로드하고 처리할 수 있습니다. 데이터 엔지니어링 에이전트를 사용하면 자연어 프롬프트를 사용하여 다양한 데이터 소스에서 데이터 파이프라인을 생성하거나 데이터 엔지니어링 요구사항에 맞게 기존 데이터 파이프라인을 조정할 수 있습니다. 데이터 엔지니어링 에이전트에는 다음과 같은 기능이 있습니다.

파이프라인 생성을 위한 자연어: 에이전트는 Gemini를 사용하여 데이터를 이해하고 일반 언어 요청 사항을 해석합니다. 일반 언어 요청 사항을 사용하여 데이터 엔지니어링 에이전트가 데이터 파이프라인을 빌드하거나 수정하도록 할 수 있습니다.
Dataform 통합: 에이전트는 필요한 파이프라인 코드를 생성하고 Dataform 저장소 내의 SQLX 파일로 구성합니다. 에이전트는 Dataform 작업공간에서 작동하므로 Dataform 파이프라인을 에이전트에서 자동으로 사용할 수 있습니다.
커스텀 에이전트 요청 사항: 일반 언어로 에이전트 요청 사항을 만들어 데이터 엔지니어링 에이전트의 커스텀 규칙을 정의합니다. 에이전트 요청 사항은 조직 전체에서 지속되며 명명 규칙 또는 스타일 가이드와 같은 조직 전체 규칙을 적용하는 데 유용할 수 있습니다.
파이프라인 유효성 검사: 에이전트는 생성된 코드를 검증하여 데이터 파이프라인이 작동하는지 확인합니다.

데이터 엔지니어링 에이전트와 함께 자연어 프롬프트를 사용하여 테이블, 뷰, 어설션, 선언, 작업 SQLX 파일을 만들 수 있습니다. 예를 들어 데이터 엔지니어링 에이전트를 사용하여 다음 작업을 실행할 수 있습니다.

CSV, AVRO, PARQUET과 같은 다양한 형식으로 Cloud Storage와 같은 외부 데이터 소스에서 데이터를 로드합니다.
기존 BigQuery 루틴 (UDF)을 만들거나 사용하여 데이터에 대한 커스텀 분석 및 변환을 실행합니다.
자연어로 에이전트의 재사용 가능한 가이드라인을 정의합니다.

데이터 엔지니어링 에이전트와 함께 사용할 수 있는 프롬프트의 추가 예시는 샘플 프롬프트를 참조하세요.

제한사항

데이터 엔지니어링 에이전트에는 다음과 같은 제한사항이 있습니다.

데이터 엔지니어링 에이전트는 GA 이전 제공 서비스이며 프로덕션용이 아닙니다.
데이터 엔지니어링 에이전트는 다음 파일 유형에 대한 자연어 명령어를 지원하지 않습니다.
- Notebooks
- 데이터 준비
- SQLx 내의 JavaScript
데이터 엔지니어링 에이전트는 파이프라인을 실행할 수 없습니다. 사용자는 파이프라인을 검토하고 실행하거나 예약해야 합니다.
데이터 엔지니어링 에이전트는 전체 파이프라인 호출(사용자 트리거) 없이 존재하지 않는 중간 리소스에 종속된 SQL을 검증할 수 없습니다.
데이터 엔지니어링 에이전트는 요청 사항 또는 직접 프롬프트를 통해 제공된 웹 링크 또는 URL을 검색할 수 없습니다.
에이전트 요청 사항 파일에서 파일을 가져올 때 가져오기 구문은 ./, / 또는 문자로 시작하는 경로만 지원합니다.@
데이터 미리보기 기능은 플래그가 hasOutput로 설정된 테이블, 선언 또는 쿼리에만 지원됩니다.true

지원되는 리전

BigQuery의 Gemini는 다음 리전에서 제공됩니다.

미주

아이오와 (us-central1)

유럽

핀란드 (europe-north1)
프랑크푸르트 (europe-west3)

처리 리전 변경

다음 옵션 중 하나를 사용하여 데이터 엔지니어링 에이전트의 처리 리전을 변경할 수 있습니다.

BigQuery 파이프라인

BigQuery 파이프라인을 사용하는 경우 코드 애셋의 기본 리전을 설정하여 처리 리전을 업데이트할 수 있습니다. 자세한 내용은 코드 애셋의 기본 리전 설정을 참조하세요.

기본 리전이 설정되지 않은 경우 데이터 엔지니어링 에이전트는 데이터를 전역적으로 처리합니다.

Dataform

Dataform을 사용하는 경우 Dataform 워크플로 설정 파일 또는 workflow_settings.yaml에서 defaultLocation 값을 변경하여 처리 리전을 업데이트할 수 있습니다. 자세한 내용은 Dataform 워크플로 설정 구성을 참조하세요.

defaultLocation 값이 설정되지 않은 경우 데이터 엔지니어링 에이전트는 데이터를 전역적으로 처리합니다.

데이터 엔지니어링 에이전트가 데이터를 사용하는 방식

더 높은 품질의 에이전트 응답을 생성하기 위해 데이터 엔지니어링 에이전트는 BigQuery 테이블의 샘플 행과 Dataplex Universal Catalog에서 생성된 데이터 스캔 프로필을 비롯한 BigQuery 및 Dataplex Universal Catalog에서 추가 데이터와 메타데이터를 가져올 수 있습니다. 이 데이터는 데이터 엔지니어링 에이전트를 학습하는 데 사용되지 않으며 에이전트의 응답을 알리는 추가 컨텍스트로 에이전트 대화 중에만 사용됩니다.

시작하기 전에

프로젝트에 BigQuery의 Gemini가 사용 설정되어 있는지 확인합니다. Google Cloud 자세한 내용은 BigQuery의 Gemini 설정을 참조하세요.

Gemini 데이터 분석 API도 사용 설정해야 합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

API 사용 설정

필요한 역할

데이터 엔지니어링 에이전트를 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

Dataform 코드 편집기 (roles/dataform.codeEditor)
BigQuery 작업 사용자 (roles/bigquery.jobuser)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

데이터 엔지니어링 에이전트로 데이터 파이프라인 생성

BigQuery에서 데이터 엔지니어링 에이전트를 사용하려면 다음 옵션 중 하나를 선택하세요.

BigQuery 파이프라인

다음 단계를 따라 BigQuery 파이프라인 인터페이스에서 데이터 엔지니어링 에이전트를 사용할 수 있습니다.

BigQuery 페이지로 이동합니다.

BigQuery로 이동
쿼리 편집기에서 arrow_drop_down 새로 만들기 > 파이프라인을 클릭합니다.
실행 사용자 인증 정보의 옵션을 선택하고 시작하기 를 클릭합니다. 이러한 사용자 인증 정보는 에이전트에서 사용하지 않지만 생성된 데이터 파이프라인을 실행하는 데 필요합니다.
데이터 파이프라인의 에이전트 환경 사용해 보기 를 클릭합니다.
에이전트에게 질문 필드에 자연어 프롬프트를 입력하여 데이터 파이프라인을 생성합니다. 예를 들면 다음과 같습니다.
```
  Create dimension tables for a taxi trips star schema from
  new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
  the descriptive attributes.
```
프롬프트를 입력한 후 보내기 를 클릭합니다.
데이터 엔지니어링 에이전트는 프롬프트를 기반으로 데이터 파이프라인을 생성합니다.

데이터 엔지니어링 에이전트가 생성한 데이터 파이프라인은 데이터 파이프라인의 제안된 초안입니다. 파이프라인 노드를 클릭하여 생성된 SQLX 쿼리를 검토할 수 있습니다. 에이전트에서 제안한 데이터 파이프라인을 적용하려면 적용 을 클릭합니다.

데이터 파이프라인에 데이터 엔지니어링 에이전트가 제안한 변경사항을 적용합니다.

Dataform

다음 단계를 따라 Dataform에서 데이터 엔지니어링 에이전트를 사용할 수 있습니다.

Dataform 페이지로 이동합니다.

Dataform으로 이동
저장소를 선택합니다.
개발 작업공간을 선택하거나 만듭니다.
작업공간에서 에이전트에게 질문 을 클릭합니다.
표시되는 에이전트에게 질문 프롬프트에 자연어 프롬프트를 입력하여 데이터 파이프라인을 생성합니다. 예를 들면 다음과 같습니다.
```
  Create dimension tables for a taxi trips star schema from
  new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
  the descriptive attributes.
```
프롬프트를 입력한 후 보내기 를 클릭합니다.

프롬프트가 전송되면 데이터 엔지니어링 에이전트는 프롬프트를 기반으로 데이터 파이프라인을 생성하고 Dataform SQLX 파일을 수정합니다. 에이전트는 이러한 변경사항을 작업공간 파일에 직접 적용합니다.

데이터 파이프라인 검토

데이터 엔지니어링 에이전트가 생성한 데이터 파이프라인에서 파이프라인 노드를 클릭하여 검토할 수 있습니다.

구성 탭에는 노드와 연결된 생성된 SQLX 쿼리가 표시됩니다.
데이터 미리보기 탭에는 파일의 입력 및 출력 테이블이 표시됩니다. 작업 실행 을 클릭하여 종속 항목이 있거나 없는 작업을 실행하면 이 노드를 통해 데이터 변환을 미리 볼 수 있습니다.

데이터 파이프라인 수정

에이전트에게 질문 을 클릭하고 데이터 파이프라인 변경을 제안하는 프롬프트를 입력하여 데이터 엔지니어링 에이전트를 사용하여 데이터 파이프라인을 수정할 수 있습니다.

데이터 파이프라인에서 데이터 엔지니어링 에이전트를 사용하려면 '상담사에게 요청'을 클릭합니다.

데이터 엔지니어링 에이전트에서 제안한 변경사항을 검토한 후 적용 을 클릭하여 변경사항을 적용합니다.

파이프라인 노드를 선택한 후 열기 를 클릭하여 SQLX 쿼리를 수동으로 수정할 수도 있습니다.

데이터 엔지니어링 에이전트의 에이전트 요청 사항 만들기

에이전트 요청 사항은 데이터 엔지니어링 에이전트의 자연어 요청 사항으로, 에이전트가 사전 정의된 커스텀 규칙 집합을 따르도록 지속적인 요청 사항을 저장할 수 있습니다. 명명 규칙 또는 스타일 가이드 적용과 같이 에이전트의 결과가 조직 전체에서 일관되도록 하려면 에이전트 요청 사항을 사용하세요.

데이터 엔지니어링 에이전트의 에이전트 요청 사항 파일로 GEMINI.MD 컨텍스트 파일 을 만들 수 있습니다. 로컬 작업공간에서 사용할 에이전트 요청 사항 파일을 만들거나 외부 저장소를 사용하여 여러 데이터 파이프라인에서 동일한 요청 사항 파일을 사용할 수 있습니다.

다음 단계를 따라 에이전트 요청 사항을 만듭니다.

에이전트에게 질문에서 파이프라인 요청 사항을 클릭합니다.
파이프라인 창의 요청 사항에서 요청 사항 파일 만들기를 클릭합니다.

표시되는 GEMINI.MD 파일에 자연어로 요청 사항을 입력합니다.

다음 예시에서는 여러 규칙이 있는 에이전트 요청 사항 파일을 보여줍니다.

  1. All event-specific tables MUST be prefixed with `cs_event_`.
  2. The primary key for any player activity table is a composite key of `player_id` and `event_timestamp_micros`.
  3. Filter out any player actions where `mana_spent` is greater than `max_mana_pool`. This is considered a data anomaly.

저장 을 클릭합니다.

에이전트 요청 사항 파일을 가장 잘 구성하는 방법에 대한 자세한 내용은 에이전트 요청 사항 파일 권장사항을 참조하세요.

외부 저장소에서 에이전트 요청 사항 로드

외부 저장소를 연결하여 여러 데이터 파이프라인에서 재사용할 에이전트 요청 사항 집합을 지정할 수 있습니다.

에이전트에게 질문에서 파이프라인 요청 사항을 클릭합니다.
외부 저장소에서 외부 저장소의 요청 사항 사용 을 선택합니다.
제공된 필드에서 데이터 파이프라인과 함께 사용할 에이전트 요청 사항이 포함된 저장소를 지정합니다.
저장 을 클릭합니다.

추가 로컬 파일을 에이전트 요청 사항으로 가져오기

@file.md 구문을 사용하여 데이터 엔지니어링 에이전트의 다른 요청 사항 파일을 GEMINI.md 파일로 가져올 수도 있습니다. 자세한 내용은 메모리 가져오기 프로세서를 참조하세요.

데이터 파이프라인 오류 문제 해결

데이터 파이프라인 생성 중에 오류가 발생하면 데이터 엔지니어링 에이전트를 실행하는 데 필요한 모든 사전 요구사항을 완료했는지 확인합니다. 자세한 내용은 시작하기 전에를 참조하세요.

생성된 데이터 파이프라인에 오류가 발생하면 다음 단계에 따라 데이터 엔지니어링 에이전트가 데이터 파이프라인 실패를 진단하고 문제 해결 권장사항을 제안하도록 할 수 있습니다.

파이프라인 또는 개발 작업공간에서 실행 탭을 클릭합니다.
실행 목록에서 실패한 데이터 파이프라인 실행을 찾습니다. 실행 실행의 상태 열에서 실패한 실행을 식별할 수 있습니다.
아이콘 위로 마우스를 가져간 다음 조사하기 를 클릭합니다. 데이터 엔지니어링 에이전트는 데이터 파이프라인 실행에 오류가 있는지 분석을 실행합니다.
분석이 완료되면 데이터 엔지니어링 에이전트는 관찰 및 가설 섹션에 보고서를 생성합니다. 이 보고서에는 다음이 포함됩니다.
- 데이터 파이프라인 실행 로그에서 추출된 관찰 및 데이터 포인트
- 실패의 가능한 원인
- 식별된 문제를 해결하기 위한 실행 가능한 단계 또는 권장사항 집합

데이터 엔지니어링 에이전트의 문제 해결 보고서를 사용하면 권장사항을 수동으로 구현할 수 있습니다. 다음 단계에 따라 데이터 엔지니어링 에이전트가 수정사항을 적용하도록 할 수도 있습니다.

문제 해결 보고서에서 제안사항을 복사합니다.
데이터 엔지니어링 에이전트로 돌아갑니다.
1. BigQuery 파이프라인을 사용하는 경우 파이프라인 페이지로 이동한 후 에이전트에게 질문 을 클릭합니다.
2. Dataform을 사용하는 경우 에이전트에게 질문 을 클릭합니다.
제안사항을 프롬프트에 붙여넣고 데이터 엔지니어링 에이전트가 데이터 파이프라인을 직접 수정하도록 요청합니다.
보내기 를 클릭합니다.

샘플 프롬프트

다음 섹션에서는 데이터 엔지니어링 에이전트와 함께 사용하여 데이터 파이프라인을 개발할 수 있는 몇 가지 샘플 프롬프트를 보여줍니다.

기존 데이터를 새 테이블로 집계

이 프롬프트에서 데이터 엔지니어링 에이전트는 스키마와 샘플을 사용하여 키별 데이터 그룹화를 추론합니다. 에이전트는 일반적으로 테이블 및 열 설명이 포함된 새 테이블 구성을 설정합니다.

  Create a daily sales report from the
  bigquery-public-data.thelook_ecommerce.order_items table into a
  reporting.daily_sales_aggregation table.

기존 테이블에 데이터 품질 검사 추가

이 프롬프트에서 에이전트는 스키마와 샘플을 기반으로 테이블에 적절한 품질 검사를 추론합니다. 프롬프트의 일부로 의견이 있는 어설션을 추가할 수도 있습니다.

  Add data quality checks for bigquery-public-data.thelook_ecommerce.users.

새 파생 열을 만들고 새 테이블에 데이터 품질 검사 추가

다음 프롬프트는 테이블과 열을 추가하고 테이블에 품질 검사를 동시에 지정하는 방법을 보여줍니다.

  Create a new table named staging.products from
  bigquery-public-data.thelook_ecommerce.products and add a calculated column
  named gross_profit, which is the retail_price minus the cost.


  Also, add the following assertions: ID must not be null and must be unique.
  The retail_price must be greater than or equal to the cost. The department
  column can only contain 'Men' or 'Women'.

모델 정의의 일부로 UDF 만들기

데이터 엔지니어링 에이전트는 사용자 정의 함수 (UDF)를 만드는 DDL을 설정할 수도 있습니다. 에이전트가 실제로 UDF를 만들지는 않지만 데이터 파이프라인을 실행하여 UDF를 만들 수 있습니다. 이러한 UDF는 데이터 파이프라인의 모델 정의에서 사용할 수 있습니다.

  Create a user-defined function (UDF) named get_age_group that takes an integer
  age as input and returns a string representing the age group ('Gen Z',
  'Millennial', 'Gen X', 'Baby Boomer').


  Use this UDF on the age column from the
  bigquery-public-data.thelook_ecommerce.users table to create a new view called
  reporting.user_age_demographics that includes user_id, age, and the calculated
  age_group.

권장사항

다음 섹션에서는 데이터 엔지니어링 에이전트 및 Dataform 작업에 대한 권장사항을 제안합니다.

데이터 엔지니어링 에이전트 권장사항

일반적인 요청에 에이전트 요청 사항을 활용합니다. 일반적으로 적용하는 기법이 있거나 에이전트에 동일한 수정을 자주 하는 경우 에이전트 요청 사항을 일반적인 요청 사항과 요청을 저장하는 중앙 위치로 사용합니다.

에이전트에 더 많은 컨텍스트를 제공합니다. BigQuery 테이블 및 열에 용어집 용어를 연결하고 데이터 프로필 스캔을 생성하여 Dataplex Universal Catalog에서 에이전트에 추가 컨텍스트를 제공할 수 있습니다. 용어집 용어는 특별 처리 요청 사항이 필요한 개인 식별 정보 (PII)가 포함된 열과 같이 추가 컨텍스트가 필요한 열에 태그를 지정하거나 테이블 간에 이름이 다른 일치하는 열을 식별하는 데 사용할 수 있습니다. 데이터 프로필 스캔은 에이전트가 테이블의 열 내에서 데이터 분포를 더 잘 이해할 수 있도록 하며 에이전트가 더 구체적인 데이터 품질 어설션을 만드는 데 도움이 될 수 있습니다. 자세한 내용은 데이터 프로파일링 정보를 참조하세요.

명확하게 작성합니다. 요청을 명확하게 서술하고 모호하게 표현하지 마세요. 가능한 경우 다음 예와 같이 프롬프트를 표시할 때 소스 및 대상 데이터 소스를 제공합니다.

  Extract data from the sales.customers table in the us_west_1 region, and load
  it into the reporting.dim_customers table in BigQuery. Match the schema of the
  destination table.

직접적이고 범위가 지정된 요청을 제공합니다. 한 번에 하나의 질문을 하고 프롬프트를 간결하게 유지합니다. 질문이 두 개 이상인 프롬프트의 경우 다음 예와 같이 질문의 각 고유한 부분을 항목화하여 명확성을 개선할 수 있습니다.

  1. Create a new table named staging.events_cleaned. Use raw.events as the
     source. This new table should filter out any records where the user_agent
     matches the pattern '%bot%'. All original columns should be included.

  2. Next, create a table named analytics.user_sessions. Use
     staging.events_cleaned as the source. This table should calculate the
     duration for each session by grouping by session_id and finding the
     difference between the MAX(event_timestamp) and MIN(event_timestamp).

명시적인 요청 사항을 제공하고 주요 용어를 강조합니다. 다음 예와 같이 프롬프트에서 주요 용어 또는 개념을 강조하고 특정 요구사항을 중요하다고 라벨링할 수 있습니다.

  When creating the staging.customers table, it is *VERY IMPORTANT* that you
  transform the email column from the source table bronze.raw_customers.
  Coalesce any NULL values in the email column to an empty string ''.

작업 순서를 지정합니다. 순서가 지정된 작업의 경우 다음 예와 같이 목록에서 프롬프트를 구성할 수 있습니다. 여기서 나열된 항목은 집중적으로 수행할 수 있는 작은 단계로 나뉩니다.

  Create a pipeline with the following steps:
  1. Extract data from the ecomm.orders table.
  2. Join the extracted data with the marts.customers table on customer_id
  3. Load the final result into the reporting.customer_orders table.

수정하고 반복하세요. 최상의 결과를 얻을 수 있는 다양한 문구와 접근 방식을 계속 시도해 보세요. 에이전트가 잘못된 SQL 또는 기타 실수를 생성하는 경우 예시 또는 공개 문서를 사용하여 에이전트를 안내합니다.

  The previous query was incorrect because it removed the timestamp. Please
  correct the SQL. Use the TIMESTAMP_TRUNC function to truncate the
  event_timestamp to the nearest hour, instead of casting it as a DATE. For
  example: TIMESTAMP_TRUNC(event_timestamp, HOUR).

에이전트 요청 사항 파일 권장사항

에이전트 요청 사항 파일을 만들어 데이터 엔지니어링 에이전트 를 요구사항에 맞게 맞춤설정합니다. 에이전트 요청 사항을 사용할 때는 다음을 실행하는 것이 좋습니다.

Dataform의 모든 파일 경로는 저장소의 루트를 기준으로 합니다. @file.md 구문에 상대 경로를 사용하여 요청 사항을 GEMINI.md로 올바르게 가져옵니다.
GEMINI.md에서 가져온 파일 자체에 가져오기가 포함되어 중첩된 구조를 만들 수 있습니다. 무한 재귀를 방지하기 위해 GEMINI.md의 최대 가져오기 깊이는 5단계입니다.
데이터 파이프라인 간에 요청 사항을 공유하려면 중앙 Dataform 저장소에 요청 사항을 저장하고 작업 Dataform 저장소에 연결합니다. 로컬 요청 사항을 사용하여 파이프라인별 동작에 대한 중앙 규칙을 재정의할 수 있습니다.
에이전트 요청 사항 파일에서 제목과 목록을 사용하면 데이터 엔지니어링 에이전트의 요청 사항을 구성하고 명확하게 하는 데 도움이 될 수 있습니다.
의미 있는 파일 이름을 지정하고 유사한 요청 사항을 파일에 함께 그룹화합니다. Markdown 제목을 사용하여 카테고리, 기능 또는 기능별로 규칙을 논리적으로 구성합니다.
충돌하는 요청 사항을 방지하려면 각 요청 사항이 적용되는 특정 조건을 명확하게 정의합니다.
프롬프트와 워크플로를 반복하고 미세 조정합니다. 에이전트 동작은 에이전트 출시 및 모델 업그레이드에 따라 시간이 지남에 따라 변경되므로 다양한 프롬프트로 규칙을 반복하여 개선이 필요할 수 있는 영역을 식별하는 것이 좋습니다. 규칙 파일을 데이터 파이프라인의 변경사항과 동기화합니다.

다음 예시에서는 데이터 엔지니어링 에이전트의 효과적인 사용을 위한 권장사항을 활용하는 GEMINI.md라는 에이전트 요청 사항 파일을 보여줍니다.

  ### Naming Conventions

  * Datasets: [business_domain]_[use_case] (e.g., ecommerce_sales)

  * Tables:
      - Raw/External: raw_[source_name]
      - Staging: stg_[business_entity]
      - Dimension: dim_[dimension_name]
      - Fact: fct_[fact_name]

  * Dataform Folders:
      - sources
      - staging
      - marts
      - dataProducts

  * Views: vw_[view_name]

  * Columns: snake_case (e.g., order_id, customer_name)

  ## Cloud Storage data load
  * When ingesting data from Cloud Storage, create external tables.

  ## Null handling
  * Filter out null id values

  ## String normalization
  * Standardize string columns by converting to lower case

  ## Data Cleaning Guidelines
  @./generic_cleaning.md