Cloud Storage 또는 로컬 파일에서 BigQuery에 데이터를 일괄 작업으로 로드할 수 있습니다. 소스 데이터는 다음 형식 중 하나일 수 있습니다.
- Avro
- 쉼표로 구분된 값(CSV)
- JSON(줄바꿈으로 구분)
- ORC
- Parquet
- Cloud Storage에 저장된 Firestore 내보내기
BigQuery Data Transfer Service를 사용하여 Cloud Storage에서 BigQuery로 반복되는 로드를 설정할 수도 있습니다.
직접 사용해 보기
Google Cloud를 처음 사용하는 경우 계정을 만들어 실제 시나리오에서 BigQuery의 성능을 평가할 수 있습니다. 또한 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.
BigQuery 무료로 사용해 보기필수 권한
BigQuery에 데이터를 로드할 때는 로드 작업을 실행할 수 있는 권한과 새로 만들거나 기존에 있던 BigQuery 테이블 및 파티션에 데이터를 로드할 수 있는 권한이 필요합니다. Cloud Storage에서 데이터를 로드할 경우 데이터가 포함된 버킷에 대한 액세스 권한도 필요합니다.
BigQuery 권한
BigQuery에 데이터를 로드하려면 최소한 다음 권한이 필요합니다. 이들 권한은 새로운 테이블 또는 파티션에 데이터를 로드할 때나 테이블 또는 파티션을 추가하거나 덮어쓸 때 필요합니다.
bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create
다음과 같은 사전 정의된 IAM 역할에는 bigquery.tables.create
권한과 bigquery.tables.updateData
권한이 모두 포함되어 있습니다.
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
다음과 같은 사전 정의된 IAM 역할에는 bigquery.jobs.create
권한이 포함되어 있습니다.
bigquery.user
bigquery.jobUser
bigquery.admin
또한 bigquery.datasets.create
권한이 있는 사용자는 데이터 세트를 만들 때 해당 데이터 세트에 대한 bigquery.dataOwner
액세스 권한을 부여받습니다.
bigquery.dataOwner
액세스 권한이 있는 사용자는 로드 작업을 사용하여 데이터 세트에서 테이블을 만들고 업데이트할 수 있습니다.
BigQuery의 IAM 역할과 권한에 대한 자세한 내용은 액세스 제어를 참조하세요.
Cloud Storage 권한
Cloud Storage 버킷에서 데이터를 로드하려면 storage.objects.get
권한을 부여받아야 합니다. URI 와일드 카드를 사용하는 경우에는 storage.objects.list
권한도 있어야 합니다.
사전 정의된 IAM 역할 storage.objectViewer
가 부여되면 storage.objects.get
및 storage.objects.list
권한이 모두 제공됩니다.
Cloud Storage에서 데이터 로드
BigQuery는 다음 Cloud Storage 저장소 등급에서 데이터 로드를 지원합니다.
- Standard
- Nearline
- Coldline
- Archive
BigQuery에 데이터를 로드하는 방법은 다음 데이터 형식 페이지를 참조하세요.
Cloud Storage에서 BigQuery로 로드를 반복하는 방법을 알아보려면 Cloud Storage 전송을 참조하세요.
위치 고려사항
데이터 위치를 선택할 때는 다음 사항을 고려해야 합니다.
- 데이터 로드용 Cloud Storage 버킷을 같은 위치에 배치합니다.
- BigQuery 데이터세트가 멀티 리전 위치에 있는 경우 로드하는 데이터가 포함된 Cloud Storage 버킷은 같은 위치의 리전이나 멀티 리전 버킷에 있어야 합니다. 예를 들어 BigQuery 데이터세트가 EU에 있으면 Cloud Storage 버킷은 EU 내 리전 또는 멀티 리전 버킷에 있어야 합니다.
- 데이터세트가 리전 위치에 있는 경우, Cloud Storage 버킷은 같은 위치의 리전 버킷에 있어야 합니다. 예를 들어 데이터세트가 도쿄 리전에 있으면 Cloud Storage 버킷은 도쿄 내 리전 버킷에 있어야 합니다.
- 예외: 데이터세트가 US 멀티 리전 위치에 있는 경우 모든 리전 내 또는 멀티 리전 위치에 있는 Cloud Storage 버킷에서 데이터를 로드할 수 있습니다.
- 데이터 관리 계획을 세웁니다.
- BigQuery 데이터세트 또는 Cloud Storage 버킷과 같은 리전 내 스토리지 리소스를 선택한 경우 데이터를 지리적으로 관리하기 위한 계획을 세웁니다.
Cloud Storage 위치에 대한 자세한 내용은 Cloud Storage 문서의 버킷 위치를 참조하세요.
데이터 세트가 생성된 후에는 데이터 세트 위치를 변경할 수 없지만 데이터 세트를 복사하거나 수동으로 이동할 수 있습니다. 자세한 내용은 다음을 참고하세요.
Cloud Storage URI 검색
Cloud Storage 데이터 소스에서 데이터를 로드하려면 Cloud Storage URI를 제공해야 합니다.
Cloud Storage URI는 버킷 이름과 객체(파일 이름)로 구성됩니다.
예를 들어 Cloud Storage 버킷 이름이 mybucket
이고 데이터 파일 이름이 myfile.csv
라면 버킷 URI는 gs://mybucket/myfile.csv
가 됩니다.
데이터가 여러 개의 파일로 분리되어 있으면 URI에 와일드 카드를 사용할 수 있습니다. 자세한 내용은 Cloud Storage 요청 URI를 참조하세요.
BigQuery는 처음 이중 슬래시 다음에 슬래시 여러 개가 연속으로 포함된 소스 URI를 지원하지 않습니다. Cloud Storage 객체 이름에는 연속된 슬래시('/') 문자 여러 개가 포함될 수 있습니다. 하지만 BigQuery는 연속된 슬래시 여러 개를 단일 슬래시로 변환합니다. 예를 들어 소스 URI gs://bucket/my//object//name
은 Cloud Storage에서는 유효하지만 BigQuery에서는 작동하지 않습니다.
Cloud Storage URI를 가져오려면 다음 안내를 따르세요.
Cloud Storage 콘솔을 엽니다.
소스 데이터가 포함된 객체(파일) 위치로 이동합니다.
Cloud Storage Console 맨 위에서 객체 경로를 확인합니다. URI를 만들기 위해
gs://bucket/file
을 적절한 경로로 바꿉니다(예:gs://mybucket/myfile.json
). bucket은 Cloud Storage 버킷 이름이고 file은 데이터가 포함된 객체(파일) 이름입니다.
Cloud Storage URI의 와일드 카드 지원
Cloud Storage 데이터가 공통된 기본 이름을 공유하는 여러 파일로 분리되어 있는 경우, 데이터를 로드할 때 URI에 와일드 카드를 사용할 수 있습니다.
Cloud Storage URI에 와일드 카드를 추가하려면 기본 이름에 별표(*
)를 추가합니다. 예를 들어 fed-sample000001.csv
와 fed-sample000002.csv
라는 파일 두 개가 있다면 버킷 URI는 gs://mybucket/fed-sample*
입니다.
그런 다음 Cloud Console, bq
명령줄 도구, API 또는 클라이언트 라이브러리에서 이 와일드 카드 URI를 사용할 수 있습니다.
와일드 카드는 버킷 내의 객체(파일 이름)에 하나만 사용할 수 있습니다. 와일드 카드는 객체 이름 중간이나 끝에 입력할 수 있습니다. 버킷 이름에는 와일드 카드를 추가할 수 없습니다.
Google Datastore 내보내기의 경우 URI를 하나만 지정할 수 있으며 .backup_info
또는 .export_metadata
로 끝나야 합니다.
다음과 같은 경우 별표 와일드 카드 문자가 허용되지 않습니다.
- Datastore 또는 Firestore 내보내기에 연결된 외부 테이블을 만드는 경우
- Cloud Storage에서 Datastore 또는 Firestore 내보내기 데이터를 로드하는 경우
제한사항
Cloud Storage 버킷에서 BigQuery로 데이터를 로드할 때는 다음과 같은 제한사항이 적용됩니다.
- 데이터세트 위치가
US
이외의 값으로 설정된 경우 리전별 또는 멀티 리전 Cloud Storage 버킷이 데이터세트와 동일한 리전에 있어야 합니다. - BigQuery는 외부 데이터 소스의 데이터 일관성을 보장하지 않습니다. 쿼리가 실행되는 동안 기본 데이터가 변경되면 예상치 못한 동작이 발생할 수 있습니다.
Cloud Storage 소스 데이터의 형식에 따라 추가 제한사항이 적용될 수 있습니다. 자세한 내용은 다음을 참조하세요.
로컬 파일에서 데이터 로드
다음 중 하나를 사용하여 읽을 수 있는 데이터 소스(예: 로컬 머신)에서 데이터를 로드할 수 있습니다.
- Google Cloud Console
bq
명령줄 도구의bq load
명령어- API
- 클라이언트 라이브러리
Cloud Console 또는 bq
명령줄 도구를 사용하여 데이터를 로드하면 로드 작업이 자동으로 생성됩니다.
로컬 데이터 소스에서 데이터를 로드하는 방법:
Console
Cloud Console에서 BigQuery 페이지를 엽니다.
탐색 패널의 리소스 섹션에서 Google Cloud 프로젝트를 펼치고 데이터 세트를 선택합니다.
창의 오른쪽에 있는 세부정보 패널에서 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다.
테이블 만들기 페이지의 소스 섹션에서 다음을 수행합니다.
다음 항목으로 테이블 만들기에서 업로드를 선택합니다.
파일 선택 아래에 있는 찾아보기를 클릭합니다.
파일을 찾은 후 열기를 클릭합니다. 로컬 파일에서는 와일드 카드와 쉼표로 구분된 목록이 지원되지 않습니다.
파일 형식에서 CSV, JSON(줄바꿈으로 구분), Avro, Parquet 또는 ORC를 선택합니다.
테이블 만들기 페이지의 대상 섹션에서 다음을 수행합니다.
데이터 세트 이름에서 적절한 데이터 세트를 선택합니다.
테이블 이름 필드에 BigQuery에 만들려는 테이블의 이름을 입력합니다.
테이블 유형이 기본 테이블로 설정되어 있는지 확인합니다.
스키마 섹션에 스키마 정의를 입력합니다.
CSV 및 JSON 파일의 경우 자동 감지 옵션을 선택하여 스키마 자동 감지를 사용 설정할 수 있습니다. 다른 지원되는 파일 유형의 경우 스키마 정보는 소스 데이터에서 자체 기술됩니다.
스키마 정보를 수동으로 입력하는 방법은 다음과 같습니다.
텍스트로 편집을 클릭하고 테이블 스키마를 JSON 배열로 입력합니다.
필드 추가를 사용하여 스키마를 직접 입력합니다.
고급 옵션 섹션에서 해당 항목을 선택합니다. 사용 가능한 옵션에 대한 자세한 내용은 CSV 옵션과 JSON 옵션을 참조하세요.
선택사항: 고급 옵션에서 쓰기 처리를 선택합니다.
- 비어 있으면 쓰기: 테이블이 비어 있는 경우에만 데이터를 씁니다.
- 테이블에 추가: 데이터를 테이블 끝에 추가합니다. 이 설정은 기본값입니다.
- 테이블 덮어쓰기: 새 데이터를 쓰기 전에 테이블의 모든 기존 데이터를 삭제합니다.
테이블 만들기를 클릭합니다.
bq
bq load
명령어를 사용하고 source_format
을 지정하고 로컬 파일 경로를 포함합니다.
(선택사항) --location
플래그를 지정하고 값을 사용자 위치로 설정합니다.
기본 프로젝트가 아닌 다른 프로젝트에 데이터를 로드하려면 프로젝트 ID를 PROJECT_ID:DATASET
형식으로 데이터 세트에 추가합니다.
bq --location=LOCATION load \ --source_format=FORMAT \ PROJECT_ID:DATASET.TABLE \ PATH_TO_SOURCE \ SCHEMA
다음을 바꿉니다.
LOCATION
: 사용자 위치입니다.--location
플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용하는 경우 플래그 값을asia-northeast1
로 설정합니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.FORMAT
:CSV
,AVRO
,PARQUET
,ORC
, 또는NEWLINE_DELIMITED_JSON
.project_id
: 프로젝트 ID입니다.dataset
: 기존 데이터 세트입니다.table
: 데이터를 로드할 테이블의 이름입니다.path_to_source
: 로컬 파일의 경로입니다.schema
: 유효한 스키마입니다. 스키마는 로컬 JSON 파일일 수 있고 명령어의 일부로 인라인으로 입력할 수도 있습니다. 스키마 정의를 제공하는 대신--autodetect
플래그를 사용해도 됩니다.
또한 BigQuery가 데이터를 파싱하는 방법을 제어할 수 있는 옵션에 플래그를 추가할 수 있습니다. 예를 들어 --skip_leading_rows
플래그를 사용하면 CSV 파일의 헤더 행을 무시할 수 있습니다. 자세한 내용은 CSV 옵션과 JSON 옵션을 참조하세요.
예를 들면 다음과 같습니다.
다음 명령어는 줄바꿈으로 구분된 JSON 파일(mydata.json
)을 기본 프로젝트의 mydataset
에 있는 mytable
이라는 테이블에 로드합니다. 스키마는 myschema.json
이라는 로컬 스키마 파일에 정의됩니다.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
./mydata.json \
./myschema.json
다음 명령어는 로컬 CSV 파일(mydata.csv
)을 myotherproject
의 mydataset
에 있는 mytable
이라는 테이블에 로드합니다. 스키마는 FIELD:DATA_TYPE, FIELD:DATA_TYPE
형식으로 인라인으로 정의됩니다.
bq load \
--source_format=CSV \
myotherproject:mydataset.mytable \
./mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
다음 명령어는 로컬 CSV 파일(mydata.csv
)을 기본 프로젝트의 mydataset
에 있는 mytable
이라는 테이블에 로드합니다. 스키마는 스키마 자동 감지를 통해 정의됩니다.
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
./mydata.csv
C#
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 BigQuery C# API 참조 문서를 확인하세요.
다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면UploadCsvOptions
대신 JobCreationOptions 기본 클래스에서 적절한 형식의 업데이트 옵션 클래스를 사용합니다.
Go
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참조 문서를 확인하세요.
다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면NewReaderSource
의 DataFormat 속성을 적절한 형식으로 설정합니다.
자바
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 자바 설정 안내를 따르세요. 자세한 내용은 BigQuery 자바 API 참조 문서를 확인하세요.
다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 FormatOptions를 적절한 형식으로 설정합니다.
Node.js
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참조 문서를 확인하세요.
다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 load 함수의metadata
매개변수를 적절한 형식으로 설정합니다.
PHP
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 PHP 설정 안내를 따르세요. 자세한 내용은 BigQuery PHP API 참조 문서를 참조하세요.
다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 sourceFormat을 적절한 형식으로 설정합니다.
Python
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참조 문서를 확인하세요.
다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 LoadJobConfig.source_forma 속성을 적절한 형식으로 설정합니다.
Ruby
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Ruby 설정 안내를 따르세요. 자세한 내용은 BigQuery Ruby API 참조 문서를 확인하세요.
다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 Table#load_job 메서드의format
매개변수를 적절한 형식으로 설정합니다.
제한사항
로컬 데이터 소스에서 데이터 로드 시 다음과 같은 제한사항이 적용됩니다.
- 로컬 데이터 소스에서 파일 로드 시 와일드 카드와 쉼표로 구분된 목록이 지원되지 않습니다. 파일을 개별적으로 로드해야 합니다.
- Cloud Console을 사용할 때 로컬 데이터 소스에서 로드된 파일은 10MB를 초과할 수 없습니다. 더 큰 파일의 경우 Cloud Storage에서 파일을 로드합니다.
압축 및 비압축 데이터 로드
압축 및 비압축 데이터를 로드하는 데 권장되는 형식은 Avro 바이너리 형식입니다. Avro 데이터는 데이터 블록이 압축된 경우에도 데이터를 병렬로 읽을 수 있으므로 더 빠르게 로드됩니다. 압축된 Avro 파일은 지원되지 않지만 압축된 데이터 블록은 지원됩니다. BigQuery는 Avro 파일의 압축된 데이터 블록에 DEFLATE 및 Snappy 코덱을 지원합니다.
또한 Parquet의 효율적인 열 단위 인코딩은 일반적으로 더 높은 압축 비율과 더 작은 파일 크기로 이어지므로 Parquet 바이너리 형식은 좋은 선택입니다. 또한 Parquet 파일은 파일을 병렬로 로드할 수 있는 압축 기술을 활용합니다. 압축된 Parquet 파일은 지원되지 않지만 압축된 데이터 블록은 지원됩니다. BigQuery는 Parquet 파일의 압축된 데이터 블록에 Snappy, GZip, and LZO_1X 코덱을 지원합니다.
ORC 바이너리 형식은 Parquet 형식과 비슷한 이점을 제공합니다. ORC 파일의 데이터는 데이터 스트라이프를 병렬로 읽을 수 있으므로 로드 속도가 빠릅니다. 각 데이터 스트라이프의 행은 순차적으로 로드됩니다. 로드 시간을 최적화하려면 약 256MB 이하의 데이터 스트라이프를 사용하세요. 압축된 ORC 파일은 지원되지 않지만 압축된 파일 바닥글과 스트라이프는 지원됩니다. BigQuery는 ORC 파일 바닥글 및 스트라이프에 Zlib, Snappy, LZO, LZ4 압축을 지원합니다.
비압축 파일은 병렬로 읽을 수 있으므로 CSV 및 JSON과 같은 다른 데이터 형식의 경우 BigQuery는 압축 파일보다 비압축 파일을 훨씬 더 빠르게 로드할 수 있습니다. 비압축 파일은 용량이 더 크므로 비압축 파일 사용 시 대역폭 제한이 발생하거나 Cloud Storage에 준비된 데이터의 경우 BigQuery로 로드되기 전에 Cloud Storage 비용 상승을 유발할 수 있습니다. 압축된 파일이나 압축되지 않은 파일의 라인 정렬은 보장되지 않습니다. 사용 사례에 따라 이러한 장단점을 고려하는 것이 중요합니다.
일반적으로 대역폭이 제한된 경우 gzip을 사용하여 CSV 및 JSON 파일을 압축한 후 Cloud Storage에 업로드하세요. 현재 BigQuery로 데이터를 로드할 때 CSV 및 JSON 파일에 지원되는 유일한 파일 압축 유형은 gzip입니다. 앱의 로딩 속도가 중요하고 데이터를 로드할 대역폭이 넉넉하다면 파일을 압축되지 않은 상태로 유지하세요.
테이블에 추가 또는 덮어쓰기
소스 파일에서 또는 쿼리 결과를 추가하여 테이블에 추가 데이터를 로드할 수 있습니다. 데이터의 스키마가 대상 테이블 또는 파티션의 스키마와 일치하지 않는다면 추가하거나 덮어쓸 때 스키마를 업데이트하면 됩니다.
데이터를 추가할 때 스키마를 업데이트하면 BigQuery에서 다음 작업을 처리할 수 있습니다.
- 새 필드 추가
REQUIRED
필드를NULLABLE
로 완화
테이블을 덮어쓰면 스키마를 항상 덮어쓰게 됩니다. 테이블을 덮어쓸 때는 스키마 업데이트가 제한되지 않습니다.
Cloud Console에서 쓰기 환경설정 옵션을 사용하여 소스 파일 또는 쿼리 결과에서 데이터를 로드할 때 수행할 작업을 지정합니다. bq
명령줄 도구와 API에는 다음 옵션이 포함되어 있습니다.
Console 옵션 | bq 도구 플래그 |
BigQuery API 속성 | 설명 |
---|---|---|---|
비어 있으면 쓰기 | 없음 | WRITE_EMPTY | 테이블이 비어 있는 경우에만 데이터를 씁니다. |
테이블에 추가 | --noreplace 또는 --replace=false . --replace 를 지정하지 않으면 기본값은 추가임 |
WRITE_APPEND | (기본값) 데이터를 테이블 끝에 추가합니다. |
테이블 덮어쓰기 | --replace 또는 --replace=true |
WRITE_TRUNCATE | 새 데이터를 쓰기 전에 테이블의 기존 데이터를 모두 지웁니다. |
할당량 정책
데이터 일괄 로드의 할당량 정책에 대한 자세한 내용은 할당량 및 한도 페이지의 로드 작업을 참조하세요.
가격 책정
BigQuery로 데이터를 일괄 로드하는 데는 비용이 청구되지 않습니다. 자세한 내용은 BigQuery 데이터 수집 가격 책정을 참조하세요.