Firestore 내보내기에서 데이터로드
BigQuery에서는 Firestore 관리형 가져오기 및 내보내기 서비스로 만든 Firestore 내보내기에서 데이터를 로드할 수 있습니다. 관리형 가져오기 및 내보내기 서비스는 Firestore 문서를 Cloud Storage 버킷으로 내보냅니다. 그런 다음 내보낸 데이터를 BigQuery 테이블로 로드할 수 있습니다.
제한사항
Firestore 내보내기에서 BigQuery로 데이터를 로드할 때는 다음 제한사항에 유의하세요.
- 데이터 세트는 내보내기 파일이 포함된 Cloud Storage 버킷과 같은 위치에 있어야 합니다.
- Cloud Storage URI를 하나만 지정할 수 있으며 URI 와일드 카드를 사용할 수 없습니다.
- Firestore 내보내기를 올바르게 로드하려면 내보내기 데이터의 문서가 고유한 필드 이름이 10,000개 미만인 일관된 스키마를 공유해야 합니다.
- 데이터를 저장할 새 테이블을 만들거나 기존 테이블을 덮어쓸 수 있습니다. 하지만 Firestore 내보내기 데이터를 기존 테이블에 추가할 수 없습니다.
- 내보내기 명령어에는
collection-ids
필터를 지정해야 합니다. 컬렉션 ID 필터를 지정하지 않고 내보낸 데이터는 BigQuery에 로드할 수 없습니다.
시작하기 전에
사용자에게 이 문서의 각 작업을 수행하는 데 필요한 권한을 부여하는 Identity and Access Management(IAM) 역할을 부여합니다.
필수 권한
데이터를 BigQuery로 로드하려면 로드 작업을 실행하고 데이터를 BigQuery 테이블과 파티션으로 로드할 수 있는 IAM 권한이 필요합니다. Cloud Storage에서 데이터를 로드할 경우 데이터가 포함된 버킷에 액세스할 수 있는 IAM 권한도 필요합니다.
데이터를 BigQuery로 로드할 수 있는 권한
데이터를 새 BigQuery 테이블이나 파티션으로 로드하거나 기존 테이블 또는 파티션을 추가하거나 덮어쓰려면 다음 IAM 권한이 필요합니다.
bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create
다음과 같이 사전 정의된 각 IAM 역할에는 데이터를 BigQuery 테이블이나 파티션에 로드하기 위해 필요한 권한이 포함되어 있습니다.
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin
(bigquery.jobs.create
권한 포함)bigquery.user
(bigquery.jobs.create
권한 포함)bigquery.jobUser
(bigquery.jobs.create
권한 포함)
또한 bigquery.datasets.create
권한이 있으면 만들 데이터 세트에서 로드 작업을 사용하여 테이블을 만들고 업데이트할 수 있습니다.
BigQuery의 IAM 역할과 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.
Cloud Storage에서 데이터를 로드할 수 있는 권한
Cloud Storage 버킷에서 데이터를 로드하는 데 필요한 권한을 얻으려면 관리자에게 버킷의 스토리지 관리자(roles/storage.admin
) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
이 사전 정의된 역할에는 Cloud Storage 버킷에서 데이터를 로드하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
Cloud Storage 버킷에서 데이터를 로드하려면 다음 권한이 필요합니다.
-
storage.buckets.get
-
storage.objects.get
-
storage.objects.list (required if you are using a URI wildcard)
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
Firestore 내보내기 서비스 데이터 로드
Google Cloud 콘솔, bq 명령줄 도구 또는 API를 사용하여 Firestore 내보내기 메타데이터 파일에서 데이터를 로드할 수 있습니다.
경우에 따라 Datastore 용어가 Google Cloud 콘솔 및 bq 명령줄 도구에 사용되지만 다음 절차는 Firestore 내보내기 파일과 호환됩니다. Firestore와 Datastore는 내보내기 형식을 공유합니다.
콘솔
Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.
- 탐색기 창에서 프로젝트를 펼친 후 데이터 세트를 선택합니다.
- 데이터 세트 정보 섹션에서 테이블 만들기를 클릭합니다.
- 테이블 만들기 패널에서 다음 세부정보를 지정합니다.
- 소스 섹션의 다음 항목으로 테이블 만들기 목록에서 Google Cloud Storage를 선택합니다.
그런 후 다음 작업을 수행합니다.
- Cloud Storage 버킷에서 파일을 선택하거나 Cloud Storage URI를 입력합니다.
Google Cloud 콘솔에서는 URI를 여러 개 포함할 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 생성, 추가 또는 덮어쓰려는 테이블이 포함된 데이터 세트와 동일한 위치에 있어야 합니다.
Firestore 내보내기 파일의 URI는KIND_COLLECTION_ID.export_metadata
로 끝나야 합니다. 예를 들어default_namespace_kind_Book.export_metadata
에서Book
은 컬렉션 ID이고default_namespace_kind_Book
은 Firestore에서 생성된 파일 이름입니다. URI가KIND_COLLECTION_ID.export_metadata
로 끝나지 않으면 다음과 같은 오류 메시지가 표시됩니다. 유효한 백업 메타데이터를 포함하지 않습니다 (error code: invalid). - 파일 형식으로 Cloud Datastore 백업을 선택합니다. Firestore와 Datastore는 내보내기 형식을 공유합니다.
- Cloud Storage 버킷에서 파일을 선택하거나 Cloud Storage URI를 입력합니다.
Google Cloud 콘솔에서는 URI를 여러 개 포함할 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 생성, 추가 또는 덮어쓰려는 테이블이 포함된 데이터 세트와 동일한 위치에 있어야 합니다.
- 대상 섹션에서 다음 세부정보를 지정합니다.
- 데이터 세트에서 테이블을 만들 데이터 세트를 선택합니다.
- 테이블 필드에 만들려는 테이블의 이름을 입력합니다.
- 테이블 유형 필드가 기본 테이블로 설정되어 있는지 확인합니다.
- 스키마 섹션은 그대로 놔둡니다. 스키마는 Firestore 내보내기에 대해 유추됩니다.
- 선택사항: 파티션 및 클러스터 설정을 지정합니다. 자세한 내용은 파티션을 나눈 테이블 만들기 및 클러스터링된 테이블 만들기 및 사용을 참조하세요.
- 고급 옵션을 클릭하고 다음을 수행합니다.
- 쓰기 환경설정에서 비어 있으면 쓰기를 선택한 상태로 둡니다. 이 옵션은 새 테이블을 만들어 데이터를 로드합니다.
- 테이블 스키마에 없는 행의 값을 무시하려면 알 수 없는 값을 선택합니다.
- Cloud Key Management Service 키를 사용하려면 암호화에서 고객 관리 키를 클릭합니다. Google 관리 키 설정을 그대로 두면 BigQuery는 저장 데이터를 암호화합니다.
- 테이블 만들기를 클릭합니다.
bq
source_format
이 DATASTORE_BACKUP
으로 설정된 bq load
명령어를 사용합니다.
--location
플래그를 지정하고 값을 사용자 위치로 설정합니다. 기존 테이블을 덮어쓰는 경우 --replace
플래그를 추가합니다.
특정 필드만 로드하려면 --projection_fields 플래그를 사용합니다.
bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE
다음을 바꿉니다.
LOCATION
: 사용자 위치입니다.--location
플래그는 선택사항입니다.FORMAT
:DATASTORE_BACKUP
. Datastore 백업은 Firestore에 올바른 옵션입니다. Firestore와 Datastore는 내보내기 형식을 공유합니다.DATASET
: 데이터를 로드할 테이블이 포함된 데이터 세트입니다.TABLE
: 데이터를 로드할 대상 테이블입니다. 테이블이 없으면 생성됩니다.PATH_TO_SOURCE
: Cloud Storage URI입니다.
예를 들어 다음 명령어는 Firestore 내보내기 파일 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를 사용하여 Firestore 내보내기 데이터를 로드하려면 다음 속성을 설정합니다.
Cloud Storage의 소스 데이터를 가리키는
load
작업 구성을 만듭니다.sourceUris
는 로드 작업 구성에서gs://BUCKET/OBJECT
형식으로 정규화되어야 합니다. 파일(객체) 이름은KIND_NAME.export_metadata
로 끝나야 합니다. Firestore 내보내기에는 URI가 하나만 허용되며 와일드 카드를 사용할 수 없습니다.로드 작업 구성에서
sourceFormat
속성을DATASTORE_BACKUP
으로 설정하여 데이터 형식을 지정합니다. Datastore 백업은 Firestore에 올바른 옵션입니다. Firestore와 Datastore는 내보내기 형식을 공유합니다.특정 필드만 로드하려면
projectionFields
속성을 설정합니다.기존 테이블을 덮어쓰려면
writeDisposition
속성을WRITE_TRUNCATE
로 설정하여 쓰기 처리를 지정합니다.
Python
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Firestore 옵션
BigQuery가 Firestore 내보내기 데이터를 파싱하는 방법을 변경하려면 다음 옵션을 지정합니다.
Google Cloud 콘솔 옵션 | `bq` 플래그 | BigQuery API 속성 | 설명 |
---|---|---|---|
해당 없음 | --projection_fields |
projectionFields
(자바,
Python) |
(선택사항) Firestore 내보내기에서 로드할 문서 필드를 나타내는 쉼표로 구분된 목록입니다. BigQuery는 기본적으로 모든 필드를 로드합니다. 필드 이름은 대소문자를 구분하며 내보내기에 있어야 합니다. map.foo 와 같은 맵 필드 내에 필드 경로를 지정할 수 없습니다.
|
데이터 유형 변환
BigQuery는 Firestore 내보내기 파일에 있는 각 문서의 데이터를 BigQuery 데이터 유형으로 변환합니다. 다음 표에서는 지원되는 데이터 유형 간의 변환을 설명합니다.
Firestore 데이터 유형 | BigQuery 데이터 유형 |
---|---|
배열 | RECORD |
불리언 | BOOLEAN |
참조 | RECORD |
날짜 및 시간 | TIMESTAMP |
맵 | RECORD |
부동 소수점 수 | FLOAT |
지리적 지점 |
RECORD [{"lat","FLOAT"}, {"long","FLOAT"}] |
정수 | INTEGER |
문자열 | STRING(64KB로 잘림) |
Firestore 키 속성
Firestore의 각 문서에는 문서 ID, 문서 경로와 같은 정보가 포함된 고유 키가 있습니다.
BigQuery는 다음 표의 설명대로 각 정보의 중첩 필드를 사용하여 키의 RECORD
데이터 유형(STRUCT
라고도 함)을 만듭니다.
키 속성 | 설명 | BigQuery 데이터 유형 |
---|---|---|
__key__.app |
Firestore 앱 이름입니다. | STRING |
__key__.id |
문서의 ID이거나 __key__.name 가 설정된 경우에는 null 입니다. |
INTEGER |
__key__.kind |
문서의 컬렉션 ID입니다. | STRING |
__key__.name |
문서의 이름이거나 __key__.id 가 설정된 경우에는 null 입니다. |
STRING |
__key__.namespace |
Firestore는 커스텀 네임스페이스를 지원하지 않습니다. 기본 네임스페이스는 빈 문자열로 표시됩니다. | STRING |
__key__.path |
문서의 경로이며, 루트 컬렉션의 일련의 문서와 컬렉션 쌍입니다. 예를 들면 "Country",
"USA", "PostalCode", 10011, "Route", 1234 입니다. |
STRING |