BigQuery는 Datastore 관리형 가져오기 및 내보내기 서비스를 사용하여 만든 Datastore 내보내기에서 데이터를 로드하는 기능을 지원합니다. 관리형 가져오기 및 내보내기 서비스를 사용하여 Datastore 항목을 Cloud Storage 버킷으로 내보낼 수 있습니다. 그런 다음 내보내기를 BigQuery에 테이블로 로드할 수 있습니다.
Datastore 내보내기 파일을 만드는 방법은 Datastore 문서에서 항목 내보내기 및 가져오기를 참조하세요. 내보내기 예약에 대한 자세한 내용은 내보내기 예약을 참조하세요.
API에서 projectionFields 속성을 설정하거나 CLI에서 --projection_fields 플래그를 사용하여 BigQuery에서 로드할 속성을 제어할 수 있습니다.
로드 프로세스를 건너뛰려면 내보내기를 외부 데이터 소스로 설정하여 직접 쿼리합니다. 자세한 내용은 외부 데이터 소스를 참조하세요.
Cloud Storage에서 BigQuery 테이블로 데이터를 로드하는 경우 테이블을 포함한 데이터세트는 Cloud Storage 버킷과 같은 리전이나 멀티 리전 위치에 있어야 합니다.
제한사항
Datastore 내보내기에서 BigQuery로 데이터를 로드할 때는 다음 제한사항에 유의하세요.
- Datastore 내보내기 파일을 지정할 때 Cloud Storage URI에 와일드 카드를 사용할 수 없습니다.
- Datastore 내보내기에서 데이터를 로드할 때 Cloud Storage URI를 하나만 지정할 수 있습니다.
- Datastore 내보내기 데이터를 정의된 스키마가 있는 기존 테이블에 추가할 수 없습니다.
- Datastore 내보내기를 올바르게 로드하려면 내보내기 데이터의 항목이 고유한 속성 이름이 10,000개 미만인 일관된 스키마를 공유해야 합니다.
- 항목 필터를 지정하지 않고 내보낸 데이터는 BigQuery에 로드할 수 없습니다. 내보내기 요청의 항목 필터에는 종류 이름이 한 개 이상 포함되어야 합니다.
- Datastore 내보내기의 최대 필드 크기는 64KB입니다. Datastore 내보내기를 로드할 때 64KB보다 큰 필드는 모두 잘립니다.
필수 권한
BigQuery에 데이터를 로드할 때는 로드 작업을 실행할 수 있는 권한과 새로 만들거나 기존에 있던 BigQuery 테이블 및 파티션에 데이터를 로드할 수 있는 권한이 필요합니다. Cloud Storage에서 데이터를 로드할 경우 데이터가 포함된 버킷에 대한 액세스 권한도 필요합니다.
BigQuery 권한
BigQuery에 데이터를 로드하려면 최소한 다음 권한이 필요합니다. 이러한 권한은 새로운 테이블 또는 파티션에 데이터를 로드할 때나 테이블 또는 파티션을 추가하거나 덮어쓸 때 필요합니다.
bigquery.tables.createbigquery.tables.updateDatabigquery.jobs.create
다음과 같은 사전 정의된 Cloud IAM 역할에는 bigquery.tables.create 및 bigquery.tables.updateData 권한이 모두 포함되어 있습니다.
bigquery.dataEditorbigquery.dataOwnerbigquery.admin
다음과 같은 사전 정의된 Cloud IAM 역할에는 bigquery.jobs.create 권한이 포함되어 있습니다.
bigquery.userbigquery.jobUserbigquery.admin
또한 bigquery.datasets.create 권한이 있는 사용자는 데이터세트를 만들 때 해당 데이터세트에 대한 bigquery.dataOwner 액세스 권한을 부여받습니다.
bigquery.dataOwner 액세스 권한이 있으면 사용자는 로드 작업을 통해 데이터세트에서 테이블을 만들고 업데이트할 수 있습니다.
BigQuery의 Cloud IAM 역할 및 권한에 대한 자세한 내용은 액세스 제어를 참조하세요.
Cloud Storage 권한
Cloud Storage 버킷에서 데이터를 로드하려면 storage.objects.get 권한이 있어야 합니다. URI 와일드 카드를 사용하는 경우에는 storage.objects.list 권한도 있어야 합니다.
사전 정의된 Cloud IAM 역할 storage.objectViewer가 부여되면 storage.objects.get 및 storage.objects.list 권한이 모두 제공됩니다.
Datastore 내보내기 서비스 데이터 로드
Datastore 내보내기 메타데이터 파일에서 데이터를 로드하려면 다음 안내를 따르세요.
Console
Cloud Console에서 BigQuery 웹 UI를 엽니다.
탐색 패널의 리소스 섹션에서 프로젝트를 펼치고 데이터세트를 선택합니다. 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다.
테이블 만들기 페이지의 소스 섹션에서 다음을 수행합니다.
- 다음 항목으로 테이블 만들기에서 Cloud Storage를 선택합니다.
- 소스 필드에 Cloud Storage URI를 입력합니다.
Cloud Storage 버킷은 생성 중인 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다.
Datastore 내보내기 파일의 URI는
[KIND_NAME].export_metadata또는export[NUM].export_metadata로 끝나야 합니다. 예를 들면default_namespace_kind_Book.export_metadata입니다. 이 예시에서Book은 종류 이름이고default_namespace_kind_Book은 Datastore에서 생성된 파일 이름입니다. - 파일 형식에서 Datastore 백업을 선택합니다.
테이블 만들기 페이지의 대상 섹션에서 다음을 수행합니다.
데이터세트 이름에서 적절한 데이터세트를 선택합니다.
테이블 이름 필드에 BigQuery에 만들려는 테이블의 이름을 입력합니다.
테이블 유형이 기본 테이블로 설정되어 있는지 확인합니다.
스키마 섹션은 그대로 놔둡니다. 스키마는 Datastore 내보내기에서 유추됩니다.
고급 옵션 섹션에서 해당 항목을 선택한 후 테이블 만들기를 클릭합니다. 사용 가능한 옵션에 대한 자세한 내용은 Datastore 옵션을 참조하세요.
기본 UI
- 기본 BigQuery 웹 UI로 이동합니다.
BigQuery 웹 UI로 이동 - 탐색 패널에서 데이터세트에 마우스를 가져간 다음 아래쪽 화살표 아이콘
을 클릭한 후 새 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다. - 테이블 만들기 페이지의 소스 데이터 섹션에서 다음을 수행합니다.
- 소스에서 만들기를 선택한 상태로 유지합니다.
- 위치로 Cloud Storage를 선택하고 소스 필드에 Cloud Storage URI를 입력합니다.
Cloud Storage 버킷은 생성 중인 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다.
Datastore 내보내기 파일의 URI는
[KIND_NAME].export_metadata로 끝나야 합니다. 예를 들면default_namespace_kind_Book.export_metadata입니다. 이 예시에서Book은 종류 이름이고default_namespace_kind_Book은 Datastore에서 생성된 파일 이름입니다.Cloud Storage URI에
[KIND_NAME]이 지정되었는지 확인합니다.[KIND_NAME]없이 URI를 지정하면does not contain valid backup metadata. (error code: invalid)와 같은 오류가 발생합니다. - 파일 형식에서 Datastore 백업을 선택합니다.
- 테이블 만들기 페이지의 대상 테이블 섹션에서 다음을 수행합니다.
- 테이블 이름으로 적절한 데이터세트를 선택하고 테이블 이름 필드에 BigQuery에서 만들 테이블의 이름을 입력합니다.
- 테이블 유형이 기본 테이블로 설정되어 있는지 확인합니다.
- 스키마 섹션은 그대로 놔둡니다. 스키마는 Datastore 내보내기에서 유추됩니다.
- 옵션 섹션에서 관련 항목을 선택하고 테이블 만들기를 클릭합니다. 사용 가능한 옵션에 대한 자세한 내용은 Datastore 옵션을 참조하세요.
CLI
source_format이 DATASTORE_BACKUP으로 설정된 bq load 명령어를 사용합니다.
--location 플래그를 지정하고 값을 사용자 위치로 설정합니다.
bq --location=[LOCATION] load \
--source_format=[FORMAT] \
[DATASET].[TABLE] \
[PATH_TO_SOURCE]
각 항목의 의미는 다음과 같습니다.
[LOCATION]은 사용자의 위치입니다.--location플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용한다면 플래그 값을asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.[FORMAT]은DATASTORE_BACKUP입니다.[DATASET]는 데이터를 로드할 테이블이 포함된 데이터세트입니다.[TABLE]은 데이터를 로드하는 테이블입니다. 테이블이 없는 경우에는 만들어집니다.[PATH_TO_SOURCE]는 Cloud Storage URI입니다.
예를 들어 다음 명령어는 Datastore 내보내기 파일 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata를 book_data라는 테이블로 로드합니다.
mybucket과 mydataset는 US 멀티 리전 위치에서 생성되었습니다.
bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
API
API를 사용하여 Datastore 내보내기 데이터를 로드하려면 다음 속성을 설정합니다.
Cloud Storage의 소스 데이터를 가리키는 로드 작업을 만듭니다.
소스 URI는 gs://[BUCKET]/[OBJECT] 형식으로 정규화되어야 합니다. 파일(객체) 이름은
[KIND_NAME].export_metadata로 끝나야 합니다. Datastore 내보내기에는 URI 한 개만 허용되며, 와일드 카드를 사용할 수 없습니다.configuration.load.sourceFormat 속성을
DATASTORE_BACKUP으로 설정하여 데이터 형식을 지정합니다.
Datastore 관리자 백업
Datastore 관리자 백업 기능을 사용하여 Datastore 데이터를 내보내면 파일 확장자가 .export_metadata 대신 .backup_info가 됩니다. Datastore Admin 백업 서비스를 사용할 수 없게 될 때까지는 BigQuery로 데이터를 가져올 때 .backup_info 파일 또는 .export_metadata 파일 중 하나를 사용할 수 있습니다.
Datastore 데이터로 테이블 추가 또는 덮어쓰기
Datastore 내보내기 데이터를 BigQuery로 로드할 때 데이터를 저장할 새 테이블을 만들거나 기존 테이블을 덮어쓸 수 있습니다. Datastore 내보내기 데이터를 기존 테이블에 추가할 수는 없습니다.
Datastore 내보내기 데이터를 기존 테이블에 추가하려고 하면 Cannot append a datastore backup to a table
that already has a schema. Try using the WRITE_TRUNCATE write disposition to
replace the existing table 오류가 발생합니다.
기존 테이블을 Datastore 내보내기 데이터로 덮어쓰려면 다음 안내를 따르세요.
Console
- Cloud Console에서 BigQuery 웹 UI를 엽니다. BigQuery 웹 UI로 이동
- 탐색 패널의 리소스 섹션에서 프로젝트를 확장하고 데이터세트를 선택합니다. 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다.
테이블 만들기 페이지의 소스 섹션에서 다음을 수행합니다.
다음 항목으로 테이블 만들기에서 Cloud Storage를 선택합니다.
소스 필드에 Cloud Storage URI를 입력합니다. Cloud Storage 버킷은 생성 중인 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다. Datastore 내보내기 파일의 URI는
[KIND_NAME].export_metadata로 끝나야 합니다. 예를 들면default_namespace_kind_Book.export_metadata입니다. 이 예시에서Book은 종류 이름이고default_namespace_kind_Book은 Datastore에서 생성된 파일 이름입니다.Cloud Storage URI에
[KIND_NAME]이 지정되었는지 확인합니다.[KIND_NAME]없이 URI를 지정하면does not contain valid backup metadata. (error code: invalid)와 같은 오류가 발생합니다.파일 형식에서 Datastore 백업을 선택합니다.
테이블 만들기 페이지의 대상 섹션에서 다음을 수행합니다.
데이터세트 이름에서 적절한 데이터세트를 선택합니다.
테이블 이름 필드에 BigQuery에 만들려는 테이블의 이름을 입력합니다.
테이블 유형이 기본 테이블로 설정되어 있는지 확인합니다.
스키마 섹션은 그대로 놔둡니다. 스키마는 Datastore 내보내기에서 유추됩니다.
고급 옵션 섹션의 쓰기 환경설정에서 테이블 덮어쓰기를 선택합니다.
테이블 만들기를 클릭합니다.
기본 UI
- 기본 BigQuery 웹 UI로 이동합니다.
BigQuery 웹 UI로 이동 - 탐색 패널에서 데이터세트에 마우스를 가져간 다음 아래쪽 화살표 아이콘 을 클릭한 후 새 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다.
- 테이블 만들기 페이지의 소스 데이터 섹션에서 다음을 수행합니다.
- 소스에서 만들기를 선택한 상태로 유지합니다.
- 위치로 Cloud Storage를 선택하고 소스 필드에 Cloud Storage URI를 입력합니다.
Cloud Storage 버킷은 생성 중인 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다.
Datastore 내보내기 파일의 URI는
[KIND_NAME].export_metadata로 끝나야 합니다. 예를 들면default_namespace_kind_Book.export_metadata입니다. 이 예시에서Book은 종류 이름이고default_namespace_kind_Book은 Datastore에서 생성된 파일 이름입니다.Cloud Storage URI에
[KIND_NAME]이 지정되었는지 확인합니다.[KIND_NAME]없이 URI를 지정하면does not contain valid backup metadata. (error code: invalid)와 같은 오류가 발생합니다. - 파일 형식에서 Datastore 백업을 선택합니다.
- 테이블 만들기 페이지의 대상 테이블 섹션에서 다음을 수행합니다.
- 테이블 이름으로 적절한 데이터세트를 선택하고 테이블 이름 필드에 덮어쓰려는 테이블 이름을 입력합니다.
- 테이블 유형이 기본 테이블로 설정되어 있는지 확인합니다.
- 스키마 섹션은 그대로 놔둡니다. 스키마는 Datastore 내보내기에서 유추됩니다.
- 옵션 섹션의 쓰기 기본 설정에서 테이블 덮어쓰기를 선택합니다.
- 테이블 만들기를 클릭합니다.
CLI
--replace 플래그가 지정되고 source_format이 DATASTORE_BACKUP으로 설정된 bq load 명령어를 사용합니다. --location 플래그를 지정하고 값을 사용자 위치로 설정합니다.
bq --location=[LOCATION] load \
--source_format=[FORMAT] \
--replace \
[DATASET].[TABLE] \
[PATH_TO_SOURCE]
각 항목의 의미는 다음과 같습니다.
[LOCATION]은 사용자의 위치입니다.--location플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용한다면 플래그 값을asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.[FORMAT]은DATASTORE_BACKUP입니다.[DATASET]는 데이터를 로드할 테이블이 포함된 데이터세트입니다.[TABLE]은 덮어쓸 테이블입니다.[PATH_TO_SOURCE]는 Cloud Storage URI입니다.
예를 들어 다음 명령어는 Datastore 내보내기 파일 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata를 로드하여 book_data라는 테이블을 덮어씁니다.
bq load --source_format=DATASTORE_BACKUP \
--replace \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
API
API에서 데이터를 로드하려면 속성을 다음과 같이 설정합니다.
Cloud Storage의 소스 데이터를 가리키는 로드 작업을 만듭니다.
소스 URI는 gs://[BUCKET]/[OBJECT] 형식으로 정규화되어야 합니다. 파일(객체) 이름은
[KIND_NAME].export_metadata로 끝나야 합니다. Datastore 내보내기에는 URI 한 개만 허용되며, 와일드 카드를 사용할 수 없습니다.configuration.load.sourceFormat 속성을
DATASTORE_BACKUP으로 설정하여 데이터 형식을 지정합니다.configuration.load.writeDisposition 속성을
WRITE_TRUNCATE로 설정하여 쓰기 처리를 지정합니다.
Datastore 옵션
BigQuery가 Datastore 내보내기 데이터를 파싱하는 방법을 변경하려면 기본 웹 UI, CLI 또는 API에서 추가 옵션을 지정합니다.
| CSV 옵션 | 기본 UI 옵션 | CLI 플래그 | BigQuery API 속성 | 설명 |
|---|---|---|---|---|
| 프로젝션 필드 | 없음 | --projection_fields |
projectionFields | Datastore 내보내기에서 BigQuery로 로드할 항목 속성을 나타내는 쉼표로 구분된 목록입니다. 속성 이름은 대소문자를 구분하며 최상위 수준 속성이어야 합니다. 속성을 지정하지 않으면 BigQuery가 모든 속성을 로드합니다. Datastore 내보내기에서 지정된 속성을 찾을 수 없으면 작업 결과에 잘못된 오류가 반환됩니다. 기본값은 ''입니다. |
| 허용되는 불량 레코드 수 | 허용되는 오류 개수 | --max_bad_records |
maxBadRecords | (선택사항) 작업을 실행할 때 BigQuery가 무시할 수 있는 불량 레코드의 최대 개수입니다. 불량 레코드의 수가 이 값을 초과하면 작업 결과에 잘못된 오류가 반환됩니다. 기본값은 0이며 모든 레코드가 유효해야 합니다. |
데이터 유형 변환
BigQuery는 Datastore 내보내기 파일에 있는 각 항목의 데이터를 BigQuery의 데이터 유형으로 변환합니다. 다음 표에서는 데이터 유형 간의 변환을 설명합니다.
| Datastore 데이터 유형 | BigQuery 데이터 유형 |
|---|---|
| blob | BYTES |
| Blobstore 키 | STRING |
| 부울 | BOOLEAN |
| 카테고리 | STRING |
| Datastore 키 | RECORD |
| 날짜 및 시간 | TIMESTAMP |
| 이메일 | STRING |
| 삽입된 항목 | RECORD |
| 부동 소수점 수 | FLOAT |
| 지리적 지점 |
RECORD
[{"lat","DOUBLE"},
{"long","DOUBLE"}]
|
| IM 핸들 | STRING |
| 정수 | INTEGER |
| 링크 | STRING |
| 전화번호 | STRING |
| 우편 주소 | STRING |
| 평점 | INTEGER |
| 간단한 blob | BYTES |
| 문자열 | STRING(64KB로 잘림) |
| 사용자 |
RECORD
[{"email","STRING"}
{"userid","STRING"}]
|
Datastore 키 속성
Datastore의 각 항목에는 네임스페이스, 경로와 같은 정보가 포함된 고유한 키가 있습니다. BigQuery는 다음 표와 같이 각 정보의 중첩된 필드와 함께 키의 RECORD 데이터 유형을 만듭니다.
| 키 속성 | 설명 | BigQuery 데이터 유형 |
|---|---|---|
__key__.app |
Datastore 앱 이름입니다. | STRING |
__key__.id |
항목의 ID이거나 __key__.name이 설정된 경우에는 null입니다. |
INTEGER |
__key__.kind |
항목의 종류입니다. | STRING |
__key__.name |
항목의 이름이거나 __key__.id가 설정된 경우에는 null입니다. |
STRING |
__key__.namespace |
Datastore 앱에서 커스텀 네임스페이스를 사용하는 경우 항목의 네임스페이스입니다. 그렇지 않으면 기본 네임스페이스가 빈 문자열로 표시됩니다. | STRING |
__key__.path |
평면화된 항목의 상위 경로이며, 루트 항목에서 항목 자체까지의 일련의 종류 식별자 쌍으로 구성됩니다. 예를 들면 "Country", "USA", "PostalCode",
10011, "Route", 1234입니다. |
STRING |