Google Cloud Storage에서 Avro 데이터 로드

Cloud Storage에서 Avro 파일 로드

Avro는 직렬화된 데이터를 같은 파일에서 데이터 스키마와 함께 묶는 오픈소스 데이터 형식입니다.

Cloud Storage에서 Avro 데이터를 로드할 때 새 테이블 또는 파티션에 데이터를 로드하거나 기존 테이블 또는 파티션에 추가하거나 덮어쓸 수 있습니다. BigQuery에 로드한 데이터는 Capacitor용 열 형식(BigQuery의 저장소 형식)으로 변환됩니다.

Cloud Storage에서 BigQuery 테이블로 데이터를 로드할 때 테이블을 포함하는 데이터세트는 Cloud Storage 버킷과 같은 지역이나 다중 지역 위치에 있어야 합니다.

로컬 파일에서 Avro 데이터를 로드하는 자세한 내용은 로컬 데이터 소스에서 BigQuery로 데이터 로드를 참조하세요.

Avro의 장점

Avro는 BigQuery로 데이터를 로드할 때 권장되는 형식입니다. Avro 파일을 로드하면 CSV 및 JSON(줄바꿈으로 구분됨)에 비해 다음과 같은 이점이 있습니다.

Avro 바이너리 형식:
- 로드가 빠릅니다. 데이터 블록이 압축된 경우에도 데이터를 병렬로 읽을 수 있습니다.
- 유형 설정이나 직렬화가 필요 없습니다.
- ASCII와 같은 다른 형식에서 인코딩 문제가 없으므로 파싱이 간편합니다.
Avro 파일을 BigQuery로 로드하면 테이블 스키마는 자기 기술 소스 데이터에서 자동으로 검색됩니다.

필수 권한

BigQuery로 데이터를 로드할 때는 데이터를 신규 또는 기존 BigQuery 테이블과 파티션에 로드할 수 있는 프로젝트 또는 데이터세트 수준의 권한이 있어야 합니다. Cloud Storage에서 데이터를 로드하는 경우에는 데이터가 포함된 버킷에 대한 액세스 권한도 필요합니다.

BigQuery 권한

Cloud Storage에서 BigQuery로 데이터를 로드할 때는 프로젝트 수준이나 데이터세트 수준에서 bigquery.dataOwner 또는 bigquery.dataEditor 역할을 부여 받아야 합니다. 두 역할 모두 사용자와 그룹에게 데이터를 새로운 테이블에 로드하거나 기존 테이블에 추가 또는 덮어쓸 수 있는 권한을 부여합니다.

사용자나 그룹이 프로젝트 수준의 역할을 부여 받으면 프로젝트 내의 모든 데이터세트에 있는 테이블에 데이터를 로드할 수 있는 권한이 제공됩니다. 사용자나 그룹이 데이터세트 수준의 역할을 부여 받으면 데이터를 해당 데이터세트의 테이블에만 로드할 수 있습니다.

데이터세트 액세스 구성에 대한 자세한 내용은 데이터세트에 액세스 제어 할당을 참조하세요. BigQuery의 IAM 역할에 대한 자세한 내용은 액세스 제어를 참조하세요.

Cloud Storage 권한

Cloud Storage 버킷에서 데이터를 로드하려면 프로젝트 수준이나 개별 버킷에서 storage.objects.get 권한을 부여 받아야 합니다. URI 와일드 카드를 사용하려면 storage.objects.list 권한도 있어야 합니다.

사전 정의된 IAM 역할 storage.objectViewer를 부여받으면 storage.objects.get 및 storage.objects.list 권한을 제공할 수 있습니다.

Avro 스키마

Avro 파일을 BigQuery로 로드하면 테이블 스키마가 소스 데이터에서 자동으로 검색됩니다. BigQuery가 소스 데이터에서 스키마를 검색할 때는 알파벳순으로 마지막 파일이 사용됩니다.

예를 들어, Cloud Storage에 다음과 같은 Avro 파일이 있습니다.

gs://mybucket/00/
  a.avro
  z.avro
gs://mybucket/01/
  b.avro

이 명령어는 단일 CLI 명령어로 모든 파일을 로드하며(쉼표로 구분된 목록 사용), 스키마는 mybucket/01/b.avro에서 추출됩니다.

bq --location=US load --source_format=AVRO [DATASET].[TABLE_NAME] "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

Avro 스키마가 서로 다른 여러 Avro 파일을 가져오는 경우, 모든 스키마는 Avro의 스키마 해상도와 호환되어야 합니다.

BigQuery가 스키마를 감지하면 일부 Avro 데이터 유형은 BigQuery SQL 구문과 호환되도록 BigQuery 데이터 유형으로 변환됩니다. 자세한 내용은 Avro 변환을 참조하세요.

Avro 압축

압축된 Avro 파일은 지원되지 않지만 압축된 데이터 블록은 지원됩니다. BigQuery는 DEFLATE 및 Snappy 코덱을 지원합니다.

새 테이블에 Avro 데이터 로드

Google Cloud Storage에서 새로운 BigQuery 테이블로 Avro 데이터를 로드하려면 다음 단계를 따르세요.

웹 UI

BigQuery 웹 UI로 이동합니다.
BigQuery 웹 UI로 이동
탐색창에서 데이터세트로 마우스를 가져간 다음, 아래쪽 화살표 아이콘 을 클릭하고 새 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 생성하는 프로세스와 동일합니다.
테이블 만들기 페이지의 소스 데이터 섹션에서 다음을 수행합니다.
- 위치에 Google Cloud Storage를 선택하고 소스 필드에는 Cloud Storage URI를 입력합니다. BigQuery 웹 UI는 URI를 여러 개 포함할 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 생성 중인 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다.
- 파일 형식으로 Avro를 선택합니다.
테이블 만들기 페이지의 대상 테이블 섹션에서 다음을 수행합니다.
- Table name(테이블 이름)으로 적절한 데이터세트를 선택하고 테이블 이름 필드에 BigQuery에서 만들 테이블의 이름을 입력합니다.
- 테이블 유형이 네이티브 테이블로 설정되어 있는지 확인합니다.
스키마 섹션에는 필요한 작업이 없습니다. 스키마는 Avro 파일에서 추론됩니다.
테이블 만들기를 클릭합니다.

명령줄

bq load 명령어를 사용하여 AVRO를 source_format으로 지정하고 Cloud Storage URI를 포함합니다. 단일 URI, 쉼표로 구분된 URI 목록, 와일드 카드가 포함된 URI를 포함할 수 있습니다.

--location 플래그를 지정하고 값을 사용자 위치로 설정합니다.

bq --location=[LOCATION] load --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE]

각 항목의 의미는 다음과 같습니다.

[LOCATION]은 사용자의 위치입니다. 데이터가 US 또는 EU 다중 지역 위치에 있다면 --location 플래그는 선택사항입니다. 예를 들어, 도쿄 지역에서 BigQuery를 사용하는 경우 플래그 값을 asia-northeast1로 설정합니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
[FORMAT]은 AVRO입니다.
[DATASET]는 기존 데이터세트입니다.
[TABLE]은 데이터를 로드하는 테이블의 이름입니다.
[PATH_TO_SOURCE]는 정규화된 Cloud Storage URI 또는 쉼표로 구분된 URI 목록입니다. 와일드 카드도 지원됩니다.

예:

다음 명령어는 gs://mybucket/mydata.avro의 mydataset에 있는 mytable이라는 테이블로 데이터를 로드합니다. mybucket 및 mydataset는 US 다중 지역 위치에서 생성되었습니다.
```
bq --location=US load --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
```
다음 명령어는 gs://mybucket/에 있는 여러 파일에서 mydataset에 있는 mytable이라는 테이블로 데이터를 로드합니다. Cloud Storage URI는 와일드 카드를 사용합니다. mybucket과 mydataset는 US 다중 지역 위치에서 생성되었습니다.
```
bq --location=US load --source_format=AVRO mydataset.mytable gs://mybucket/mydata*.avro
```
다음 명령어는 gs://mybucket/에 있는 여러 파일에서 mydataset에 있는 mytable이라는 테이블로 데이터를 로드합니다. 명령어에는 와일드 카드와 함께 쉼표로 구분된 Cloud Storage URI 목록이 포함됩니다. mybucket과 mydataset는 asia-northeast1 지역에서 생성되었습니다.
```
bq --location=asia-northeast1 load --autodetect --source_format=AVRO mydataset.mytable "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"
```

API

API를 사용하여 Avro 데이터를 로드하려면 다음 속성을 설정합니다.

Google Cloud Storage의 소스 데이터를 가리키는 로드 작업을 만듭니다.
작업 리소스의 jobReference 섹션에 있는 location 속성에 사용자의 위치를 지정합니다.
소스 URI는 gs://[BUCKET]/[OBJECT] 형식으로 정규화되어야 합니다. 각 URI에는 '*' 와일드 카드 문자 하나를 포함할 수 있습니다.
configuration.load.sourceFormat 속성을 AVRO로 설정하여 Avro 데이터 형식을 지정합니다.
작업 상태를 확인하려면 jobs.get([JOB_ID]*)를 호출합니다. 여기서, [JOB_ID]는 초기 요청에서 반환된 작업의 ID입니다.
- status.state = DONE이면 작업이 성공적으로 완료된 것입니다.
- status.errorResult 속성이 있는 경우 요청은 실패한 것이며, 해당 객체에 문제의 원인을 설명하는 정보가 포함됩니다. 요청이 실패하면 테이블이 생성되지 않고 데이터가 추가되지 않습니다.
- status.errorResult가 없으면 작업은 성공적으로 끝났지만 일부 행을 올바르게 가져오지 못하는 등의 치명적이지 않은 오류가 존재할 수도 있습니다. 치명적이지 않은 오류는 반환된 작업 객체의 status.errors 속성에 나열됩니다.

API 참고 사항:

로드 작업은 원자 수준으로 이루어지며 일관성을 가집니다. 로드 작업이 실패하면 어떤 데이터도 사용할 수 없으며, 로드 작업이 성공하면 모든 데이터를 사용할 수 있습니다.
권장사항은 jobs.insert()를 호출하여 로드 작업을 만들 때 고유 ID를 만들어 jobReference.jobId로 전달하는 것입니다. 이 방법은 클라이언트가 알려진 작업 ID로 폴링하거나 다시 시도할 수 있으므로, 네트워크 결함 시에도 더욱 안정적입니다.
특정한 작업 ID에 대한 jobs.insert() 호출은 멱등성을 지닙니다. 즉, 같은 작업 ID로 원하는 만큼 다시 시도할 수 있으며 최대 한 번만 성공합니다.

테이블에 Avro 데이터 추가 또는 덮어쓰기

소스 파일에서 또는 쿼리 결과 추가를 통해 추가 데이터를 테이블에 로드할 수 있습니다.

BigQuery 웹 UI의 쓰기 환경설정 옵션을 사용하여 소스 파일이나 쿼리 결과에서 데이터를 로드할 때 수행할 작업을 지정합니다. CLI와 API는 다음 옵션을 제공합니다.

웹 UI 옵션	CLI 플래그	BigQuery API 속성	설명
비어 있으면 쓰기	없음	WRITE_EMPTY	테이블이 비어 있는 경우에만 데이터를 씁니다.
테이블에 추가	`--noreplace` 또는 `--replace=false`. `--[no]replace`를 지정하지 않으면 기본값은 추가입니다.	WRITE_APPEND	(기본값) 데이터를 테이블 끝에 추가합니다.
테이블 덮어쓰기	`--replace` 또는 `--replace=true`	WRITE_TRUNCATE	새 데이터를 쓰기 전에 테이블의 기존 데이터를 모두 지웁니다.

Google Cloud Storage에서 Avro 데이터를 로드하고 BigQuery 테이블에 추가하거나 덮어쓰려면 다음 단계를 따르세요.

웹 UI

BigQuery 웹 UI로 이동합니다.
BigQuery 웹 UI로 이동
탐색창에서 데이터세트로 마우스를 가져간 다음, 아래쪽 화살표 아이콘 을 클릭하고 새 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 생성하는 프로세스와 동일합니다.
테이블 만들기 페이지의 소스 데이터 섹션에서 다음을 수행합니다.
- 위치에 Google Cloud Storage를 선택하고 소스 필드에는 Cloud Storage URI를 입력합니다. UI에는 URI를 여러 개 포함할 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 추가하거나 덮어쓰는 테이블이 포함된 데이터세트와 같은 위치에 있어야 합니다.
- 파일 형식으로 Avro를 선택합니다.
테이블 만들기 페이지의 대상 테이블 섹션에서 다음을 수행합니다.
- Table name(테이블 이름)으로 적절한 데이터세트를 선택하고 테이블 이름 필드에 추가하거나 덮어쓰는 테이블의 이름을 입력합니다.
- 테이블 유형이 네이티브 테이블로 설정되어 있는지 확인합니다.
스키마 섹션에는 필요한 작업이 없습니다. 스키마 정보는 Avro 파일에서 추론됩니다.
옵션 섹션의 쓰기 환경설정에서 비어 있으면 쓰기, 테이블에 추가 또는 테이블 덮어쓰기를 선택합니다.
테이블 만들기를 클릭합니다.

명령줄

테이블을 덮어쓰려면 bq load 명령어를 --replace 플래그와 함께 입력합니다. --location 플래그를 지정하고 값을 사용자 위치로 설정합니다. --noreplace 플래그를 사용하여 데이터를 테이블에 추가합니다. 플래그를 지정하지 않으면 데이터 추가가 기본값입니다.

bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE]

각 항목의 의미는 다음과 같습니다.

[LOCATION]은 사용자의 위치입니다. 데이터가 US 또는 EU 다중 지역 위치에 있다면 --location 플래그는 선택사항입니다..bigqueryrc 파일을 사용하여 위치의 기본값을 설정할 수 있습니다.
[DATASET]는 기존 데이터세트입니다.
[TABLE]은 데이터를 로드하는 테이블의 이름입니다.
[PATH_TO_SOURCE]는 정규화된 Cloud Storage URI 또는 쉼표로 구분된 URI 목록입니다. 와일드 카드도 지원됩니다.

예:

다음 명령어는 gs://mybucket/mydata.avro에서 데이터를 로드하여 mydataset에 있는 mytable이라는 테이블을 덮어씁니다. mybucket 및 mydataset는 US 다중 지역 위치에서 생성되었습니다.
```
bq --location=US load --replace --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
```
다음 명령어는 gs://mybucket/mydata.avro에서 데이터를 로드하여 mydataset에 있는 mytable이라는 테이블에 추가합니다. mybucket 및 mydataset는 asia-northeast1 지역에서 생성되었습니다.
```
bq --location=asia-northeast1 load --noreplace --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
```

API

API를 사용하여 CSV 데이터를 로드하려면 다음 속성을 설정합니다.

Google Cloud Storage의 소스 데이터를 가리키는 로드 작업을 만듭니다.
작업 리소스의 jobReference 섹션에 있는 location 속성에 사용자의 위치를 지정합니다.
소스 URI는 gs://[BUCKET]/[OBJECT] 형식으로 정규화되어야 합니다. 여러 URI를 쉼표로 구분된 목록으로 포함할 수 있습니다. Google Cloud Storage에서 CSV 데이터를 로드할 때는 와일드 카드도 사용 가능합니다.
configuration.load.sourceFormat 속성을 AVRO로 설정하여 데이터 형식을 지정합니다.
configuration.load.writeDisposition 속성을 WRITE_TRUNCATE, WRITE_APPEND, WRITE_EMPTY로 설정하여 쓰기 환경설정을 지정합니다.

Avro 변환

BigQuery는 Avro 데이터 유형을 다음과 같은 BigQuery 데이터 유형으로 변환합니다.

기본 유형

Avro 데이터 유형	BigQuery 데이터 유형	참고
null	BigQuery는 이 값을 무시함
boolean	BOOLEAN
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
bytes	BYTES
`decimal` 논리 유형의 bytes	NUMERIC
string	STRING	UTF-8 전용

복합 유형

Avro 데이터 유형	BigQuery 데이터 유형	참고
record	RECORD	별칭은 무시됩니다. 문서가 필드 설명으로 변환됩니다. 기본값은 읽기 시간에 설정됩니다. 순서가 무시됩니다. 재귀 필드가 삭제됩니다. 재귀 필드에서 첫 번째 수준의 중첩만 유지됩니다.
enum	STRING	문자열은 enum의 심볼 값입니다. 별칭은 무시됩니다. 문서가 필드 설명으로 변환됩니다.
array	반복 필드	배열의 배열은 지원되지 않습니다. NULL 형식만 포함된 배열은 무시됩니다.
map<T>	RECORD	BigQuery는 Avro map <T> 필드를 두 필드(키와 값)가 포함된 반복 RECORD로 변환합니다. BigQuery는 키를 STRING으로 저장하고 값을 BigQuery의 해당 데이터 유형으로 변환합니다.
union	Null 허용 필드 Null 허용 필드 목록을 가진 RECORD	union에 null이 아닌 유형이 하나뿐이라면 null 허용 필드로 변환됩니다. 그렇지 않으면 union은 null 허용 필드 목록을 가진 RECORD로 변환됩니다. 이 필드 중 하나만 읽기 시점에 설정됩니다.
fixed	BYTES	별칭은 무시됩니다. 크기는 무시됩니다.

논리 유형

대부분의 경우, BigQuery는 logicalType 속성을 무시하고 기본 Avro 유형을 사용합니다.

Avro 논리 유형	BigQuery 데이터 유형	참고
date	INTEGER
time-millis	INTEGER
time-micros	INTEGER(LONG에서 변환됨)
timestamp-millis	INTEGER(LONG에서 변환됨)
timestamp-micros	INTEGER(LONG에서 변환됨)
duration	BYTES(`fixed` 유형의 크기 12에서 변환됨)
decimal	NUMERIC(Decimal 논리 유형 참조)

Avro 데이터 유형에 대한 자세한 내용은 Apache Avro™ 1.8.2 사양을 참조하세요.

Decimal 논리 유형

decimal 논리 유형을 가진 Avro bytes 유형의 최대 precision은 38(총 자릿수)이고 최대 scale은 9(소수 자릿수)입니다. 정수 자릿수는 precision에서 scale을 뺀 값이며, 최대 29자리입니다. 예를 들어, precision이 38이고 scale이 9인 decimal은 정수 자릿수가 29이므로 지원됩니다. precision이 38이고 scale이 5인 decimal은 정수 자릿수가 33이므로 지원되지 않습니다.

decimal 논리 유형의 bytes 열이 포함된 Avro 파일을 기존 테이블에 로드하면 테이블의 스키마 정의에서 열의 데이터 유형이 BYTES 또는 NUMERIC일 수 있습니다. 열의 데이터 유형이 BYTES이면 Avro 파일에서 열의 decimal 논리 유형이 무시됩니다.

Avro decimal 논리 유형에 대한 자세한 내용은 Apache Avro™ 1.8.2 사양을 참조하세요.

Cloud Storage에서 Avro 파일 로드

Avro의 장점

필수 권한

BigQuery 권한

Cloud Storage 권한

Avro 스키마

Avro 압축

새 테이블에 Avro 데이터 로드

웹 UI

명령줄

API

테이블에 Avro 데이터 추가 또는 덮어쓰기

웹 UI

명령줄

API

Avro 변환

기본 유형

복합 유형

논리 유형

Decimal 논리 유형

다음에 대한 의견 보내기...