BigQuery 데이터 가져오기

Amplitude의 BigQuery 연동을 통해 BigQuery 데이터를 Amplitude 프로젝트에 직접 수집할 수 있습니다.

사전 조건

BigQuery에서 가져오기를 시작하려면 다음 사전 요구 사항을 완료하십시오.

• 데이터를 가져올 BigQuery의 테이블(또는 여러 테이블)이 필요합니다.

• GCS 버킷을 생성합니다. Amplitude는 이 목적을 위해 전용 시스템을 권장합니다. BigQuery의 내보내기 옵션이 제한적이기 때문에 수집 프로세스는 이를 Amplitude에 수집하기 전에 데이터를 GCS 버킷으로 오프로드해야 합니다.

• 수집하려는 버킷과 테이블에 대해 부여된 권한 관리를 가진 서비스 계정을 생성한 다음 서비스 계정 키를 가져옵니다. 서비스 계정에 다음 역할을 부여하십시오.

  • BigQuery:
    • 프로젝트 수준의 BigQuery 작업 사용자입니다.
    • 데이터에 액세스하는 데 필요한 리소스 수준의 BigQuery 데이터 뷰어입니다. 데이터가 단일 테이블에 있는 경우 해당 테이블 리소스에 대한 BigQuery 데이터 뷰어 권한을 서비스 계정에 부여하세요. 쿼리에 여러 테이블 또는 데이터 세트가 필요한 경우 쿼리의 모든 테이블 또는 데이터 세트에 대해 BigQuery 데이터 뷰어를 허용하세요.
  • 클라우드 스토리지:
    • 수집에 사용 중인 GCS 버킷의 스토리지 관리자입니다.

• 회사의 네트워크 정책에 따라 Amplitude의 서버가 BigQuery 인스턴스에 액세스할 수 있도록 허용 목록에 다음 IP 주소를 추가해야 할 수도 있습니다.

  • Amplitude 미국 IP 주소:
    • 52.33.3.219
    • 35.162.216.242
    • 52.27.10.221
  • Amplitude EU IP 주소:
    • 3.124.22.25
    • 18.157.59.125
    • 18.192.47.195

BigQuery를 소스로 추가

Amplitude 프로젝트의 데이터 소스로 BigQuery를 추가하려면 다음 단계를 따르십시오.

1. Amplitude 데이터에서 카탈로그를 클릭하고 소스 탭을 선택합니다.
2. 웨어하우스 소스 섹션에서 BigQuery를 클릭합니다.
3. 서비스 계정 키를 추가하고 GCS 버킷 이름을 지정합니다.
4. 다음을 클릭하여 연결을 테스트합니다.
5. 자격 증명을 확인한 후 다음을 클릭하여 데이터를 선택합니다. 다음 구성 옵션 중에서 선택하십시오.
   • 데이터 유형: 이벤트 데이터, 사용자 속성 또는 그룹 속성 데이터 중 무엇을 수집하는지 Amplitude에 알려줍니다.
   • 가져오기 유형:
     • 전체 동기화: Amplitude는 데이터가 이미 가져와졌는지 여부에 관계없이 전체 데이터 세트를 주기적으로 가져옵니다. 이 방법은 시간별로 행 데이터가 변경되지만 어떤 행이 변경되었는지 쉽게 알 수 있는 방법이 없는 데이터 세트에 적합합니다. 그렇지 않은 경우에는 시간 기반 가져오기를 사용하는 것이 더 효율적인 옵션입니다. 이 옵션은 이벤트 데이터 수집을 지원하지 않습니다.
     • 시간 기반: Amplitude는 제공된 타임스탬프 열에 의해 결정된 대로 데이터의 가장 최근 행을 주기적으로 수집합니다. 첫 번째 가져오기는 사용 가능한 모든 데이터를 수집하며, 이후 가져오기는 가장 최근 가져오기 이후의 타임스탬프가 있는 전체 데이터를 수집합니다. 이 옵션을 사용하려면 SQL 문의 출력에 타임스탬프 열을 포함하십시오.
     • 미러 동기화(조기 액세스): Amplitude는 BigQuery의 변경 내역을 사용하여 BigQuery 테이블의 INSERT, UPDATE및 DELETE작업을 Amplitude에 이미 있는 이벤트 데이터에 적용합니다. 이 옵션을 사용하면 Amplitude를 신뢰할 수 있는 단일 소스(Source of Truth)와 동기화할 수 있습니다. 자세한 내용은 CDC(변경 데이터 캡처)와 미러 동기화를 참조하십시오.
   • 빈도: 5분에서 1개월까지 다양한 일정 옵션 중에서 선택할 수 있습니다. 매일 데이터 동기화는 하루 중 특정 시간에 실행될 수 있습니다. 주간 및 월간 데이터 동기화는 특정 요일과 시간에 실행될 수 있습니다.
   • SQL 쿼리: Amplitude가 올바른 데이터를 수집하는 데 사용하는 쿼리 코드입니다.
6. 구성 옵션을 설정한 후 Test SQL을 클릭하여 데이터가 BigQuery 인스턴스에서 어떻게 전달되는지 확인하세요. 모든 오류는 [SQL 테스트] 단추 아래에 나타납니다.
7. 오류가 없으면 완료를 클릭합니다. 새 BigQuery 소스를 확인하는 알림을 받게 됩니다. 그러면 Amplitude는 사용자를 소스 목록 페이지로 리디렉션하며, 여기서 새로운 BigQuery 소스를 볼 수 있습니다.

이 흐름을 따르는 동안 문제나 질문이 있으면 Amplitude 팀에 문의하십시오.

시간 기반 가져오기

Amplitude의 시간 기반 가져오기 옵션의 경우 모범 사례로 단조롭게 증가하는 타임스탬프 값을 사용하십시오. 이 값은 SQL 구성이 쿼리하는 소스 테이블에 레코드가 로드된 시점(종종 "서버 업로드 시간"이라고 함)을 나타내야 합니다. 웨어하우스 가져오기 도구는 이후의 가져오기마다 Import Config UI 첫 사용 후 타임스탬프 열 이름 입력에서 참조되는 열의 최대값을 지속적으로 업데이트함으로써 Amplitude로 데이터를 가져옵니다.

변경 데이터 캡처(CDC)를 통한 미러 동기화

미러 동기화는 Amplitude를 진실의 소스인 BigQuery 테이블과 동기화시켜 줍니다. Amplitude는 새 행을 추가하는 대신, INSERT, UPDATE, 및 DELETE 작업을 Amplitude에 이미 있는 이벤트 데이터에 적용합니다. Amplitude는 테이블의 변경 내역을 읽는 BigQuery의 CHANGES() 테이블 값 함수를 사용하여 변경 사항을 감지합니다.

미러 동기화는 진실의 소스를 미러링하므로 Amplitude는 이 소스에 대한 보강 서비스(ID 확인 및 사용자 병합, 속성 및 속성 동기화, 위치 확인, 택소노미 검증)를 비활성화하므로 데이터가 BigQuery에 있는 그대로 유지됩니다. 이는 Snowflake 및 Databricks 용 미러 동기화와 일치합니다. Amplitude 전체에 변형이 적용되는 방법에 대한 자세한 내용은 데이터 변형성을 참조하세요.

사전 조건

미러 동기화 소스를 생성하기 전에 BigQuery 테이블을 준비하세요.

• 소스 테이블 또는 질의가 읽는 모든 테이블에서 변경 내역을 활성화합니다.

  sql

  복사

  ALTER TABLE your_dataset.your_table
  SET OPTIONS (enable_change_history = TRUE);
  

  변경 기록을 활성화하지 않은 경우 연결 테스트가 실패하고 Change history is not enabled for table ...와 같은 오류가 발생합니다.

• 충분한 시간 여행 기록을 보관하십시오. CHANGES()는 테이블의 시간 여행 창 첫 사용 후 읽을 수만 있습니다(기본값은 7일이며, 2일에서 7일까지 구성 가능). Amplitude는 기본값을 7일로 설정할 것을 권장합니다. 미러 동기화 소스가 시간 여행 창보다 더 오래 연결이 끊긴 상태로 있거나 지연되는 경우, BigQuery는 더 이상 따라잡을 수 있는 기록을 가지고 있지 않으므로 소스를 다시 만들어야 합니다.

• 지원되는 테이블 유형을 사용하십시오. 미러 동기화는 표준 BigQuery 테이블에서 변경 내역을 읽습니다. 이는 뷰, 구체화된 뷰, 외부 또는 페더레이션된 테이블 또는 다중 명령문 트랜잭션으로 작성된 테이블을 지원하지 않습니다.

데이터 매핑

BigQuery의 다른 가져오기 전략과 마찬가지로 미러 동기화는 SQL SELECT 문을 사용하여 소스 열을 Amplitude가 예상하는 필드에 매핑합니다. 각 소스 열을 이벤트 데이터 유형의 목적지 필드 이름으로 별칭으로 지정합니다. 필수 데이터 필드를 참조하십시오.

예를 들면 다음과 같습니다.

SELECT
    source_row_id AS insert_id,
    user_id       AS user_id,
    event_name    AS event_type,
    event_time_ms AS time
FROM `your_project.your_dataset.your_table`

모든 이벤트에는 사용자 ID가 포함되어야 합니다. 미러 동기화는 가 없는 행을 삭제하므로 익명 이벤트를 지원하지 않습니다.

동기화할 작업 선택

미러 동기화의 데이터 가변성 설정을 통해 적용할 작업을 선택할 수 있습니다. INSERT은 항상 켜져 있습니다. BigQuery의 변경 사항이 Amplitude에 전파되기를 원하는 방법에 따라 UPDATE, DELETE, 또는 둘 다를 활성화하십시오.

동기화 예약

BigQuery의 CHANGES() 기능은 동기화당 최대 1일 동안 읽을 수 있으며, 변경 데이터는 짧은 지연(약 10분) 후에 사용할 수 있게 됩니다. 이러한 이유로 미러 동기화 소스는 하루에 한 번 이상 동기화되어야 합니다. Amplitude는 5분마다 시작하여 최대 12시간마다 동기화되는 빈도를 제공합니다. 시간 여행 창 첫 사용 후 내에서 빈도를 편안하게 선택하여 소스가 항상 따라잡을 수 있도록 하십시오.

문제 해결

BigQuery 내보내기 명령문 제한 사항

BigQuery 내보내기 문은 쿼리에서 메타 테이블을 참조할 수 없습니다. 여기에는 INFORMATION_SCHEMA뷰, 시스템 테이블 또는 와일드카드 테이블이 포함됩니다. 쿼리가 이러한 메타 테이블 중 하나를 참조하는 경우 Amplitude는 다음과 같은 오류를 보고합니다EXPORT DATA statement cannot reference meta tables in the queries.

이 제한을 피하려면 다음을 수행하십시오.

• SQL 쿼리가 표준 테이블과 뷰만 참조하는지 확인하십시오.
• INFORMATION_SCHEMA뷰에 대한 참조를 포함하지 마십시오.
• 질의에 시스템 테이블을 사용하지 마십시오.
• 가져오기 쿼리에서 와일드카드 테이블을 사용하지 마십시오.

BigQuery 내보내기 명령문 제한 사항에 대한 자세한 내용은 Google의 문서 Export statements in GoogleSQL을 참조하세요.

필수 데이터 필드

SQL 쿼리를 생성할 때 데이터 유형에 대한 필수 필드를 포함하십시오. 이 표에서는 각 데이터 유형에 대한 필수 필드와 선택적 필드를 간략하게 설명합니다. 이벤트에 대해 지원되는 기타 필드 목록은 HTTP V2 API 문서에서 확인하고 사용자 속성에 대해 지원되는 기타 필드 목록은 Identify API 문서에서 확인하십시오. 이러한 목록에 없는 열을 모두 event_properties또는 user_properties에 추가하십시오. 그렇지 않으면 Amplitude는 해당 열을 무시합니다.

이벤트

지원되는 다른 필드는 HTTP V2 API 문서에서 확인하십시오.

사용자 속성

지원되는 다른 필드는 Identify API 문서에서 확인하십시오.

그룹 속성

group_properties의 각 그룹 속성은 groups의 모든 그룹에 적용됩니다.

활성 가져오기 모니터링

수집(Ingestion) 작업 페이지는 BigQuery 가져오기를 활성 가져오기와 가져오기 기록으로 나눕니다. 각 활성 가져오기는 작업이 실행되는 동안 라이브로 업데이트되는 카드로 나타나므로 작업 세부 정보 서랍을 열지 않고도 진행 상황을 추적할 수 있습니다.

각 카드에는 다음이 표시됩니다.

• 작업 상태(상태 표시기와 레이블이 포함됨).
• 실행 간격 및 시작 시간(Started 뒤에 작업이 시작된 시간이 표시됨)입니다.
• 수집된 레코드와 예상된 레코드를 비교하는 진행 표시줄입니다. 이 막대는 업로드 단계 중이거나 Amplitude가 예상 레코드 수를 알기 전까지는 불확정 상태로 표시됩니다.
• 지금까지의 레코드와 Amplitude가 수집한 예상 레코드의 비율입니다.
• 작업이 실패한 경우 짧은 오류 텍스트입니다.

카드는 자동으로 새로 고쳐집니다. 처음 20초 동안 2초마다 새로 고쳐지고, 그 후에는 5초마다 새로 고쳐집니다. Amplitude 관리자는 카드에 있는 작업 ID도 볼 수 있습니다.

작업 세부 정보 보기

작업 세부 정보 드로어는 BigQuery 가져오기에만 사용할 수 있습니다.

작업 상태

각 작업은 다음 네 가지 상태 중 하나로 나타납니다.

파이프라인 단계

드로어는 다음 세 단계를 통해 작업 진행 상황을 시각화합니다.

1. 업로드: Amplitude는 BigQuery에서 데이터를 추출하여 이를 Cloud Storage로 오프로드합니다.
2. 처리: Amplitude는 수집을 위해 데이터를 준비하고 일괄 처리합니다.
3. 완료: Amplitude는 배치를 프로젝트에 수집합니다.

각 단계는 보류** 중, 실행 중, 완료됨 또는 실패함의 네 가지 상태 중 하나를 표시합니다. Amplitude는 활성 단계를 강조표시합니다. 작업 상태에 관계없이 세 단계 모두 항상 표시됩니다.

수집 통계

완료되었거나 부분적으로 완료된 작업의 경우 서랍에 다음이 표시됩니다.

• 업로드됨: BigQuery에서 추출된 총 레코드입니다.
• 수집됨: Amplitude가 프로젝트에 추가한 레코드입니다.
• 수집되지 않음: Amplitude가 수집하지 않은 레코드입니다.
• 중복: 레코드 Amplitude가 중복 제거되었습니다.
• 비준수: 검증에 실패한 레코드입니다.
• 수집된 %: 수집된 레코드와 업로드된 레코드의 비율입니다.

서랍에서 작업 탐색

서랍의 화살표 컨트롤을 사용하여 작업 간을 이동하거나 페이지 번호를 직접 입력하여 특정 페이지로 이동할 수 있습니다. 이 서랍은 작업 목록의 모든 페이지에서 Temporal 작업에 사용할 수 있습니다. 필터를 변경하거나 빈 작업 표시 옵션을 토글하면 페이지 매기기가 재설정됩니다.

BigQuery 서비스 계정 키 업데이트

BigQuery 소스에 사용된 서비스 계정을 업데이트하려면 데이터의 소스 섹션 첫 사용 후 기존 BigQuery 소스를 선택하고 톱니바퀴 아이콘을 클릭하세요. 모달에서 Amplitude가 앞으로 사용할 새 서비스 계정 키를 업로드하세요.

BigQuery SQL 도우미

속성 필드

많은 Amplitude 기능은 속성 키와 속성 값으로 구성된 "속성" 필드에 의존합니다. 이러한 속성 필드 중 가장 일반적인 필드는 event_properties및 user_properties입니다.

Amplitude가 이러한 키 및 값 세트를 올바르게 수집하려면 BigQuery가 이를 JSON 문자열이 아닌 원시 JSON으로 내보내야 합니다. BigQuery는 JSON을 잘 지원하지 않지만, 다음은 데이터를 BigQuery에서 내보내고 오류 없이 Amplitude로 가져오도록 하는 방법을 설명합니다.

속성 필드는 STRUCT 유형의 열에서 비롯됩니다. 구조체 유형은 키-값 구조를 나타내며 BigQuery에서 원시 JSON 형식으로 내보냅니다.

소스 테이블에 이벤트 또는 사용자 속성이 구조체 유형 열에 구성되어 있지 않은 경우 SELECT SQL에서 생성할 수 있습니다. 예를 들어, 이벤트 속성이 고유한 열로 병합되어 있는 경우 다음과 같은 구조체로 event_properties를 구성할 수 있습니다.

SELECT STRUCT(
    event_property_column_1 AS event_property_name_1,
    event_property_column_2 AS event_property_name_2
) as event_properties
FROM your_table;

레코드 유형 및 반복 모드 필드에서 이벤트 또는 사용자 속성을 재구성합니다.

RECORD 유형과 REPEATED 모드가 있는 event_properties또는 user_properties 필드가 있는 경우 Amplitude로 수집하기 전에 해당 필드를 유효한 형식으로 변환해야 할 수도 있습니다.

이러한 트랜스포메이션을 달성하기 위한 두 가지 접근 방식은 다음과 같습니다.

• PARSE_JSON을 사용하여 속성을 JSON 객체로 재구성하여 모든 값의 형식이 올바르게 지정되었는지 확인하십시오.

PARSE_JSON(CONCAT('{',
    (
      SELECT STRING_AGG(
          CONCAT('"', key, '":"',
            COALESCE(
              NULLIF(CODE_POINTS_TO_STRING(
                ARRAY((
                  SELECT * FROM UNNEST((
                    SELECT TO_CODE_POINTS(CAST(value.string_value AS STRING))
                  )) AS code_points
                  WHERE code_points > 31 AND code_points != 34 AND code_points != 92
                ))
              ), ''),
              NULLIF(CAST(value.int_value AS STRING), ''),
              NULLIF(CAST(value.float_value AS STRING), ''),
              NULLIF(CAST(value.double_value AS STRING), '')
            ),
            '"'
          )
      ) FROM UNNEST(event_properties)
    ),
    '}'
  )) AS event_properties

• 개별 키-값 쌍을 직접 추출합니다.

(SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'key1') AS key1,
(SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'key2') AS key2

이벤트 속성을 변환한 후에는 Amplitude가 수집할 수 있도록 해당 속성을 STRUCT로 포맷하세요:

STRUCT
(
  action AS action,
  field AS field
) AS event_properties

JSON 문자열 필드의 속성

이벤트 또는 사용자 속성이 문자열 필드에 JSON으로 형식화되어 있는 경우에도 여전히 select SQL의 속성 필드를 STRUCT로 재구성해야 합니다. BigQuery는 콘텐츠가 JSON이더라도 문자열 필드를 문자열로 내보냅니다. Amplitude의 이벤트 검증은 이러한 내용을 거부합니다.

JSON 문자열 필드에서 값을 추출하여 STRUCT 속성에 사용할 수 있습니다. JSON_EXTRACT_SCALAR 함수를 사용하여 다음과 같이 문자열의 값에 액세스합니다. 테이블의 EVENT_PROPERTIES 열에 다음과 같은 JSON 문자열이 포함되어 있는 경우

이는 BigQuery UI에 {"record count":"50","region":"eu-central-1"})와 같이 표시되며"{\"record count\":\"50\",\"region\":\"eu-central-1\"}", 그런 다음 다음과 같이 JSON 문자열에서 값을 추출할 수 있습니다:

SELECT STRUCT(
    JSON_EXTRACT_SCALAR(EVENT_PROPERTIES, "$.record count") AS record_count,
   JSON_EXTRACT_SCALAR(EVENT_PROPERTIES, "$.region") AS region
) as event_properties
FROM your_table;

문자열 리터럴

다른 데이터 웨어하우스 제품과 달리 BigQuery는 "큰따옴표로 묶인 문자열"을 문자열 리터럴로 취급합니다. 이러한 것들을 사용하여 열 이름이나 테이블 이름과 같은 식별자를 따옴표로 묶을 수 없으며, 그렇지 않으면 SQL이 BigQuery에서 실행되지 않습니다.