Cloud Firestore 내보내기에서 데이터 로드

BigQuery에서는 Cloud Firestore 관리형 가져오기 및 내보내기 서비스로 만든 Cloud Firestore 내보내기에서 데이터를 로드할 수 있습니다. 관리형 가져오기 및 내보내기 서비스는 Cloud Firestore 문서를 Cloud Storage 버킷으로 내보냅니다. 그런 다음 내보낸 데이터를 BigQuery 테이블로 로드할 수 있습니다.

제한사항

Cloud Firestore 내보내기에서 BigQuery로 데이터를 로드할 때 다음 제한사항에 유의하세요.

  • 데이터세트는 내보내기 파일이 포함된 Cloud Storage 버킷과 같은 리전 내 또는 멀티 리전 위치에 있어야 합니다.
  • Cloud Storage URI를 하나만 지정할 수 있으며 URI 와일드 카드를 사용할 수 없습니다.
  • Cloud Firestore 내보내기를 올바르게 로드하려면 내보내기 데이터의 문서가 고유한 필드 이름이 10,000개 미만인 일관된 스키마를 공유해야 합니다.
  • 데이터를 저장할 새 테이블을 만들거나 기존 테이블을 덮어쓸 수 있습니다. 하지만, Cloud Firestore 내보내기 데이터를 기존 테이블에 추가할 수 없습니다.
  • 내보내기 명령어에는 collection-ids 필터를 지정해야 합니다. 컬렉션 ID 필터를 지정하지 않고 내보낸 데이터는 BigQuery에 로드할 수 없습니다.

필수 권한

BigQuery에 데이터를 로드할 때는 로드 작업을 실행할 수 있는 권한과 새로운 또는 기존의 BigQuery 테이블 및 파티션에 데이터를 로드할 수 있는 권한이 있어야 합니다. Cloud Storage에서 데이터를 로드하는 경우 데이터가 포함된 버킷에 대한 액세스 권한도 필요합니다.

BigQuery 권한

BigQuery에 데이터를 로드하려면 최소한 다음 권한이 필요합니다. 이러한 권한은 새 테이블 또는 파티션에 데이터를 로드하는 경우 또는 테이블 또는 파티션을 추가하거나 덮어쓰는 경우 필요합니다.

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.jobs.create

사전 정의된 다음 Cloud IAM 역할에는 bigquery.tables.createbigquery.tables.updateData 권한이 모두 포함되어 있습니다.

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

사전 정의된 다음 Cloud IAM 역할에는 bigquery.jobs.create 권한이 포함되어 있습니다.

  • bigquery.user
  • bigquery.jobUser
  • bigquery.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.getstorage.objects.list 권한이 모두 제공됩니다.

Cloud Firestore 내보내기 서비스 데이터 로드

BigQuery 웹 UI, bq 명령줄 도구, API를 사용하여 Cloud Firestore 내보내기 메타데이터 파일에서 데이터를 로드할 수 있습니다.

Cloud Datastore 용어가 UI 또는 명령어에 사용되는 경우도 있지만 다음 절차는 Cloud Firestore 내보내기 파일에서 사용됩니다. Cloud Firestore와 Cloud Datastore는 내보내기 형식을 공유합니다.

Console

  1. GCP Console에서 BigQuery 웹 UI를 엽니다.
    BigQuery 웹 UI로 이동
  2. 탐색 패널의 리소스 섹션에서 프로젝트를 확장하고 데이터세트를 선택합니다. 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다. 테이블 만들기
  3. 테이블 만들기 페이지의 소스 섹션에서 다음을 수행합니다.

    • 다음 항목으로 테이블 만들기에서 Cloud Storage를 선택합니다.

    • 소스 필드에 Cloud Storage URI를 입력합니다. Cloud Storage 버킷이 데이터세트와 같은 위치에 있어야 합니다. Cloud Firestore 내보내기 파일의 URI는 [KIND_COLLECTION_ID].export_metadata로 끝나야 합니다. 예를 들면 default_namespace_kind_Book.export_metadata입니다. 이 예시에서 Book은 컬렉션 ID이고 default_namespace_kind_Book은 Cloud Firestore에서 생성된 파일 이름입니다.

      Cloud Storage URI에 [KIND_COLLECTION_ID]가 지정되었는지 확인합니다. [KIND_COLLECTION_ID] 없이 URI를 지정하면 does not contain valid backup metadata. (error code: invalid) 오류가 발생합니다.

    • 파일 형식으로 Cloud Datastore 백업을 선택합니다. Cloud Datastore 백업은 Cloud Firestore의 올바른 옵션입니다. Cloud Firestore와 Cloud Datastore는 내보내기 형식을 공유합니다.

  4. 테이블 만들기 페이지의 대상 섹션에서 다음을 수행합니다.

    • 데이터세트 이름에서 적절한 데이터세트를 선택합니다.

      데이터세트 선택

    • 테이블 이름 필드에 BigQuery에 생성 중인 테이블의 이름을 입력합니다.

    • 테이블 유형기본 테이블로 설정되어 있는지 확인합니다.

  5. 스키마 섹션은 별도의 설정이 필요하지 않습니다. 스키마는 Cloud Firestore 내보내기에 대해 유추됩니다.

  6. 고급 옵션 섹션에서 해당 항목을 선택합니다. 기존 테이블을 덮어쓰는 경우 쓰기 환경설정테이블 덮어쓰기로 설정합니다.

    테이블 덮어쓰기

  7. 테이블 만들기를 클릭합니다.

기본 UI

  1. 기본 BigQuery 웹 UI로 이동합니다.
    BigQuery 웹 UI로 이동
  2. 탐색 패널에서 마우스로 데이터세트를 가리키고 아래쪽 화살표 아이콘 아래쪽 화살표 아이콘 이미지을 클릭한 후 새 테이블 만들기를 클릭합니다.
  3. 테이블 만들기 페이지의 소스 데이터 섹션에서 다음을 수행합니다.

    • 소스에서 만들기를 선택한 상태로 유지합니다.
    • 위치Cloud Storage를 선택하고 소스 필드에 Cloud Storage URI를 입력합니다. Cloud Storage 버킷은 데이터세트와 같은 위치에 있어야 합니다. Cloud Firestore 내보내기 파일의 URI는 [KIND_COLLECTION_ID].export_metadata로 끝나야 합니다. 예를 들면 default_namespace_kind_Book.export_metadata입니다. 이 예시에서 Book은 컬렉션 ID이고 default_namespace_kind_Book은 Cloud Firestore에서 생성된 파일 이름입니다.

      Cloud Storage URI에 [KIND_COLLECTION_ID]가 지정되었는지 확인합니다. [KIND_COLLECTION_ID] 없이 URI를 지정하면 does not contain valid backup metadata. (error code: invalid) 오류가 발생합니다.

    • 파일 형식으로 Cloud Datastore 백업을 선택합니다. Cloud Datastore 백업은 Cloud Firestore의 올바른 옵션입니다. Cloud Firestore와 Cloud Datastore는 내보내기 형식을 공유합니다.

  4. 테이블 만들기 페이지의 대상 테이블 섹션:

    • 테이블 이름으로 적절한 데이터세트를 선택하고 테이블 이름 필드에 BigQuery에서 만들 테이블의 이름을 입력합니다.
    • 테이블 유형기본 테이블로 설정되어 있는지 확인합니다.
  5. 스키마 섹션은 별도의 설정이 필요하지 않습니다. 스키마는 Cloud Firestore 내보내기에 대해 유추됩니다.

  6. 옵션 섹션에서 해당 항목을 선택합니다. 기존 테이블을 덮어쓰는 경우 쓰기 환경설정테이블 덮어쓰기로 설정합니다.

  7. 테이블 만들기를 클릭합니다.

CLI

source_formatDATASTORE_BACKUP으로 설정하여 bq load 명령어를 사용합니다. --location 플래그를 제공하고 갑을 사용자 위치로 설정합니다. 기존 테이블을 덮어쓰는 경우 --replace 플래그를 추가합니다.

특정 필드만 로드하려면 --projection_fields 플래그를 사용합니다.

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

여기서

  • [LOCATION]은 사용자의 위치입니다. --location 플래그는 선택사항입니다.
  • [FORMAT]DATASTORE_BACKUP입니다. Cloud Datastore 백업은 Cloud Firestore의 올바른 옵션입니다. Cloud Firestore와 Cloud Datastore는 내보내기 형식을 공유합니다.
  • [DATASET]는 데이터를 로드하는 테이블이 포함된 데이터세트입니다.
  • [TABLE]은 데이터를 로드하는 테이블입니다. 테이블이 없는 경우에는 만들어집니다.
  • [PATH_TO_SOURCE]Cloud Storage URI입니다.

예를 들어 다음 명령어는 Cloud Firestore 내보내기 파일인 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadatabook_data라는 테이블에 로드합니다. mybucketmydatasetUS 다중 지역 위치에서 생성되었습니다.

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를 사용하여 Cloud Firestore 내보내기 데이터를 로드하려면 다음 속성을 설정합니다.

  1. Cloud Storage의 소스 데이터를 가리키는 load 작업 구성을 만듭니다.

  2. 작업 리소스jobReference 섹션에 있는 location 속성에 사용자 위치를 지정합니다.

  3. sourceUris는 로드 작업 구성에서 gs://[BUCKET]/[OBJECT] 형식으로 정규화되어야 합니다. 파일(객체) 이름은 [KIND_NAME].export_metadata로 끝나야 합니다. Cloud Firestore 내보내기에는 URI가 하나만 허용되며 와일드 카드를 사용할 수 없습니다.

  4. 로드 작업 구성에서 sourceFormat 속성을 DATASTORE_BACKUP으로 설정하여 데이터 형식을 지정합니다. Cloud Datastore 백업은 Cloud Firestore의 올바른 옵션입니다. Cloud Firestore와 Cloud Datastore는 내보내기 형식을 공유합니다.

  5. 특정 필드만 로드하려면 projectionFields 속성을 설정합니다.

  6. 기존 테이블을 덮어쓰려면 writeDisposition 속성을 WRITE_TRUNCATE로 설정하여 쓰기 처리를 지정합니다.

Cloud Firestore 옵션

BigQuery가 Cloud Firestore 내보내기 데이터를 파싱하는 방법을 변경하려면 다음 옵션을 지정합니다.

CSV 옵션 기본 UI 옵션 CLI 플래그 BigQuery API 속성 설명
프로젝션 필드 없음 --projection_fields projectionFields (선택사항) Cloud Firestore 내보내기에서 로드할 문서 필드를 나타내는 쉼표로 구분된 목록입니다. BigQuery는 기본적으로 모든 필드를 로드합니다. 필드 이름은 대소문자를 구분하며 내보내기에 있어야 합니다. map.foo와 같은 맵 필드 내에 필드 경로를 지정할 수 없습니다.
허용된 불량 레코드 수 허용되는 오류 개수 --max_bad_records maxBadRecords (선택사항) 작업을 실행할 때 BigQuery가 무시할 수 있는 불량 레코드의 최대 개수입니다. 불량 레코드의 수가 이 값을 초과하면 작업 결과에 잘못된 오류가 반환됩니다. 기본값은 0이며 모든 레코드가 유효해야 합니다.

데이터 유형 변환

BigQuery는 Cloud Firestore 내보내기 파일에 있는 각 문서의 데이터를 BigQuery 데이터 유형으로 변환합니다. 다음 표에서는 데이터 유형 사이의 변환을 설명합니다.

Cloud Firestore 데이터 유형 BigQuery 데이터 유형
배열 RECORD
부울 BOOLEAN
참조 RECORD
날짜 및 시간 TIMESTAMP
RECORD
부동 소수점 수 FLOAT
지리적 지점

RECORD


[{"lat","FLOAT"},
 {"long","FLOAT"}]
        
정수 INTEGER
문자열 STRING(64KB로 잘림)

Firestore 키 속성

Cloud Firestore의 각 문서에는 문서 ID, 문서 경로와 같은 정보가 포함된 고유한 키가 있습니다. BigQuery는 다음 표의 설명대로 각 정보의 중첩 필드를 사용하여 키의 RECORD 데이터 유형(STRUCT라고도 함)을 만듭니다.

키 속성 설명 BigQuery 데이터 유형
__key__.app Cloud Firestore 앱 이름입니다. STRING
__key__.id 문서의 ID입니다. __key__.name이 설정된 경우에는 null입니다. INTEGER
__key__.kind 문서의 컬렉션 ID입니다. STRING
__key__.name 문서의 이름입니다. __key__.id가 설정된 경우에는 null입니다. STRING
__key__.namespace Cloud Firestore는 커스텀 네임스페이스를 지원하지 않습니다. 기본 네임스페이스는 빈 문자열로 표시됩니다. STRING
__key__.path 문서의 경로이며, 루트 컬렉션의 일련의 문서와 컬렉션 쌍입니다. 예: "Country", "USA", "PostalCode", 10011, "Route", 1234. STRING
이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

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

도움이 필요하시나요? 지원 페이지를 방문하세요.