bq 명령줄 도구 살펴보기

bq 명령줄 도구는 BigQuery용 Python 기반 명령줄 도구입니다. 이 페이지에는 bq 명령줄 도구 사용에 대한 일반적인 정보가 포함되어 있습니다.

모든 bq 명령어 및 플래그에 대한 자세한 내용은 bq 명령줄 도구 참조를 확인하세요.

시작하기 전에

bq 명령줄 도구를 사용하려면 먼저 Google Cloud 콘솔을 사용하여 프로젝트를 만들거나 선택해야 합니다.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

BigQuery는 새 프로젝트에서 자동으로 사용 설정됩니다. 기존 프로젝트에서 BigQuery를 활성화하려면
Enable the BigQuery API.
Enable the API
로 이동합니다.
(선택사항) 프로젝트에 대한 결제를 사용 설정합니다. 결제를 사용 설정하거나 신용카드를 제공하지 않는 경우 이 문서의 단계가 계속 작동합니다. BigQuery에서는 단계를 수행하기 위한 샌드박스를 제공합니다. 자세한 내용은 BigQuery 샌드박스 사용 설정을 참조하세요.
참고: 프로젝트에 결제 계정이 있고 BigQuery 샌드박스를 사용하려는 경우 프로젝트의 결제를 중지하세요.

Cloud Shell에서 `bq` 명령어 입력

Google Cloud 콘솔 또는 Google Cloud CLI에서 Cloud Shell에 bq명령줄 도구 명령어를 입력할 수 있습니다.

Google Cloud 콘솔에서 bq 명령줄 도구를 사용하려면 Cloud Shell을 활성화합니다.

Cloud Shell 활성화
gcloud CLI에서 bq 명령줄 도구를 사용하려면 gcloud CLI 설치 및 구성을 수행합니다.

플래그 및 인수 위치 지정

bq 명령줄 도구는 두 가지 종류의 플래그를 지원합니다.

전역 플래그는 모든 명령어에 사용할 수 있습니다.
명령어별 플래그는 특정 명령어에 적용됩니다.

사용 가능한 전역 플래그와 명령어 관련 플래그 목록은 bq 명령줄 도구 참조 문서를 참조하세요.

전역 플래그를 bq 명령어 앞에 배치한 후 명령어별 플래그를 포함합니다. 전역 플래그 또는 명령어별 플래그를 여러 개 포함할 수 있습니다. 예를 들면 다음과 같습니다.

bq --location=us mk --reservation --project_id=project reservation_name

다음과 같은 방법으로 명령어 인수를 지정할 수 있습니다.

--FLAG ARGUMENT(이전 예시와 같이)
--FLAG=ARGUMENT
--FLAG='ARGUMENT'
--FLAG="ARGUMENT"
--FLAG 'ARGUMENT'
--FLAG "ARGUMENT"

다음을 바꿉니다.

FLAG: 전역 플래그 또는 명령어별 플래그
ARGUMENT: 플래그 인수

일부 명령어에서는 인수를 작은 따옴표나 큰 따옴표로 묶어야 합니다. 인수에 공백, 쉼표 또는 기타 특수 문자가 포함되어 있는 경우가 주로 여기에 해당합니다. 예를 들면 다음과 같습니다.

bq query --nouse_legacy_sql \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

부울 값이 있는 플래그는 인수 없이 지정할 수 있습니다. true 또는 false를 지정할 경우 FLAG=ARGUMENT 형식을 사용해야 합니다.

예를 들어 다음 명령어는 플래그 앞에 no를 추가하는 방법으로 부울 플래그 --use_legacy_sql을 false로 지정합니다.

bq query --nouse_legacy_sql \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

또는 플래그의 인수로 false를 지정하려면 다음을 입력합니다.

bq query --use_legacy_sql=false \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

bq 명령줄 도구에서 쿼리 실행

Google Cloud 콘솔에서 개발한 쿼리를 가져와 bq 명령줄 도구에서 실행하려면 다음 안내를 따르세요.

bq query --use_legacy_sql=false 'QUERY' 같이 bq query 명령어에 쿼리를 포함합니다. QUERY를 쿼리로 바꿉니다.
쿼리 문자열의 형식을 지정합니다.

쿼리 내에 추가 문자열 리터럴을 사용해야 하는 경우 사용 중인 셸(예: Bash 또는 PowerShell)의 따옴표 규칙을 따라야 합니다.

다음 예시는 Bash의 일반적인 접근방식을 보여줍니다. 즉, 큰따옴표를 사용하여 쿼리에서 문자열 리터럴을 나타낸 다음 쿼리 자체를 작은따옴표로 묶습니다.
```
'SELECT * FROM mydataset.mytable WHERE column1 = "value";'
```
다른 위치에서 쿼리를 복사하는 경우 쿼리의 주석도 삭제해야 합니다.

예를 들어 다음 Google Cloud 콘솔 쿼리를
```
-- count Shakespeare's use of the string "raisin"
SELECT
  word,
  SUM(word_count) AS count
FROM
  `bigquery-public-data`.samples.shakespeare
WHERE
  word LIKE '%raisin%'
GROUP BY
  word
```
다음과 같이 bq 명령줄 도구 쿼리로 변환합니다.
```
bq query --use_legacy_sql=false \
'SELECT
  word,
  SUM(word_count) AS count
FROM
  `bigquery-public-data`.samples.shakespeare
WHERE
  word LIKE "%raisin%"
GROUP BY
  word'
```

자세한 내용은 대화형 및 일괄 쿼리 작업 실행을 참조하세요.

도움말 보기

bq 명령줄 도구에 대한 도움말을 보려면 다음 명령어를 입력하세요.

설치된 bq 명령줄 도구 버전을 확인하려면 bq version을 입력합니다.
전체 명령어 목록을 확인하려면 bq help를 입력합니다.
전역 플래그 목록을 확인하려면 bq --help를 입력합니다.
특정 명령어의 도움말을 확인하려면 bq help COMMAND를 입력합니다.
특정 명령어 및 전역 플래그 목록에 대한 도움말은 bq COMMAND --help를 입력합니다.

COMMAND를 도움이 필요한 명령어로 바꿉니다.

명령줄 플래그 기본값 설정

bq 명령줄 도구의 구성 파일인 .bigqueryrc에 명령줄 플래그를 포함하여 명령줄 플래그의 기본값을 설정할 수 있습니다. 기본 옵션을 구성하려면 먼저 .bigqueryrc 파일을 만들어야 합니다. 원하는 텍스트 편집기를 사용하여 파일을 만들 수 있습니다. .bigqueryrc 파일을 만든 후 --bigqueryrc 전역 플래그를 사용하여 파일 경로를 지정할 수 있습니다.

--bigqueryrc 플래그를 지정하지 않으면 BIGQUERYRC 환경 변수가 사용되며 이를 지정하지 않으면 경로 ~/.bigqueryrc가 사용됩니다. 기본 경로는 $HOME/.bigqueryrc입니다.

`.bigqueryrc`에 플래그 추가

.bigqueryrc에 명령줄 플래그의 기본값을 추가하려면 다음 안내를 따르세요.

파일 맨 위에 헤더 없이 전역 플래그를 배치합니다.
명령어별 플래그의 경우 대괄호 안에 명령어 이름을 입력하고 그 아래에 명령어별 플래그를 한 행에 하나씩 추가합니다.

예를 들면 다음과 같습니다.

--apilog=stdout
--format=prettyjson
--location=US

[query]
--use_legacy_sql=false
--max_rows=100
--maximum_bytes_billed=10000000

[load]
--destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey

앞의 예시에서는 다음 플래그의 기본값을 설정합니다.

전역 플래그 --apilog를 stdout로 설정하여 디버깅 출력을 Google Cloud 콘솔에 인쇄합니다.
전역 플래그 --format을 prettyjson으로 설정하여 인간이 읽을 수 있는 JSON 형식으로 명령어 출력을 표시합니다.
전역 플래그 --location을 US 멀티 리전 위치로 설정합니다.
query 명령어별 플래그 --use_legacy_sql을 false로 설정하여 GoogleSQL을 기본 쿼리 문법으로 지정합니다.
참고: .bigqueryrc에서 --nouse_legacy_sql은 사용할 수 없습니다.
query 명령어별 플래그 --max_rows를 100으로 설정되어 쿼리 출력의 행 수를 제어합니다.
query 명령어별 플래그 --maximum_bytes_billed를 10,000,000바이트(10MB)로 설정하여 10MB가 넘는 데이터를 읽는 쿼리가 실패하도록 합니다.
load 명령어별 플래그 --destination_kms_key가 projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey로 설정됩니다.

대화형 셸에서 bq 명령줄 도구 실행

명령어에 bq 프리픽스를 사용해야 하는 대화형 셸에서 bq 명령줄 도구를 실행할 수 있습니다. 대화형 모드를 시작하려면 bq shell을 입력합니다. 셸이 시작되면 프롬프트가 기본 프로젝트의 ID로 변경됩니다. 대화형 모드를 종료하려면 exit를 입력합니다.

스크립트에서 bq 명령줄 도구 실행

스크립트에서 Google Cloud CLI 명령어를 실행할 수 있는 것처럼 스크립트에서 bq 명령줄 도구를 실행할 수 있습니다. 다음은 bash 스크립트의 gcloud 및 bq 명령어 예시입니다.

#!/bin/bash
gcloud config set project myProject
bq query --use_legacy_sql=false --destination_table=myDataset.myTable \
'SELECT
   word,
   SUM(word_count) AS count
 FROM
   `bigquery-public-data`.samples.shakespeare
 WHERE
   word LIKE "%raisin%"
 GROUP BY
   word'

서비스 계정에서 `bq` 명령어 실행

서비스 계정을 사용하여 승인된 API 호출을 수행하거나 자동으로 쿼리 작업을 실행할 수 있습니다. bq 명령줄 도구에서 서비스 계정을 사용하려면 서비스 계정에서 Google Cloud에 대한 액세스를 승인합니다. 자세한 내용은 gcloud auth activate-service-account를 참조하세요.

서비스 계정 가장을 사용하여 bq 명령어 실행을 시작하려면 다음 명령어를 실행합니다.

gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_NAME

SERVICE_ACCOUNT_NAME을 서비스 계정 이름으로 바꿉니다.

이제 사용자가 실행하는 bq 명령어에서 서비스 계정 사용자 인증 정보를 사용합니다.

서비스 계정에서 bq 명령어 실행을 중지하려면 다음 명령어를 실행합니다.

gcloud config unset auth/impersonate_service_account

예

BigQuery 문서의 안내 가이드 섹션에 명령줄 예시가 있습니다. 이 섹션에는 BigQuery 리소스 만들기, 가져오기, 나열, 삭제, 수정과 같은 일반적인 명령줄 작업에 대한 링크가 포함되어 있습니다.

리소스 만들기

bq 명령줄 도구를 사용하여 리소스를 만드는 방법은 다음 항목을 참조하세요.

데이터 파일을 사용하여 테이블을 만드는 예에 대해서는 데이터 로드를 참조하세요.

리소스 정보 가져오기

bq 명령줄 도구를 사용하여 리소스 정보를 가져오는 방법은 다음 항목을 참조하세요.

리소스 나열

bq 명령줄 도구를 사용하여 리소스를 나열하는 방법은 다음 항목을 참조하세요.

작업 나열

bq 명령줄 도구를 사용하여 작업을 나열하는 방법은 다음 항목을 참조하세요.

작업 나열

리소스 업데이트

bq 명령줄 도구를 사용하여 리소스를 업데이트하는 방법은 다음 항목을 참조하세요.

데이터 로드

bq 명령줄 도구를 사용하여 데이터를 로드하는 방법은 다음 항목을 참조하세요.

데이터 쿼리

bq 명령줄 도구를 사용하여 데이터를 쿼리하는 방법은 다음 항목을 참조하세요.

외부 데이터 소스 사용

bq 명령줄 도구를 사용하여 외부 데이터 소스의 데이터를 쿼리하는 방법은 다음 항목을 참조하세요.

데이터 내보내기

bq 명령줄 도구를 사용하여 데이터를 내보내는 방법은 다음 항목을 참조하세요.

BigQuery에 저장된 데이터 내보내기

BigQuery Data Transfer Service 사용

BigQuery Data Transfer Service에서 bq 명령줄 도구를 사용하는 방법은 다음 항목을 참조하세요.

bq 명령줄 도구 문제 해결

이 섹션에서는 bq 명령줄 도구 관련 문제를 해결하는 방법을 보여줍니다.

gcloud CLI를 최신 상태로 유지

Google Cloud CLI에서 bq 명령줄 도구를 사용하는 경우 gcloud CLI 설치를 최신 상태로 유지하여 bq 명령줄 도구의 최신 기능과 수정이 있는지 확인하세요. 최신 버전의 gcloud CLI를 실행 중인지 확인하려면 Cloud Shell에서 다음 명령어를 입력합니다.

gcloud components list

출력의 처음 두 줄에는 현재 gcloud CLI 설치의 버전 번호와 최신 gcloud CLI의 버전 번호가 표시됩니다. 버전이 최신 상태가 아닌 경우 Cloud Shell에서 다음 명령어를 입력하여 gcloud CLI 설치를 최신 버전으로 업데이트할 수 있습니다.

gcloud components update

디버깅

다음 명령어를 입력하여 bq 명령줄 도구를 디버깅할 수 있습니다.

보내고 받은 요청 확인. --apilog=PATH_TO_FILE 플래그를 추가하여 작업 로그를 로컬 파일에 저장합니다. PATH_TO_FILE을 로그를 저장할 경로로 바꿉니다. bq 명령줄 도구는 표준 REST 기반 API 호출을 수행하여 작동하므로 보는 데 유용합니다. 또한 문제 보고 시 이 로그를 첨부하는 것이 유용합니다. 경로 대신 - 또는 stdout를 사용하면 로그가 Google Cloud 콘솔에 출력됩니다. --apilog를 stderr로 설정하면 로그가 표준 오류 파일로 출력됩니다. 더 많은 요청을 로깅하려면 --httplib2_debuglevel=LOG_LEVEL 플래그를 사용하세요. LOG_LEVEL이 높을수록 http 요청에 대한 추가 정보가 로깅됩니다.
문제 해결. 작업 상태를 확인하거나 테이블 및 데이터 세트와 같은 리소스의 자세한 정보를 보려면 --format=prettyjson 플래그를 입력합니다. 이 플래그를 사용하면 reason 속성을 포함하여 JSON 형식의 응답이 출력됩니다. reason 속성을 사용하면 문제 해결 단계를 확인할 수 있습니다. 실행 중 오류에 관한 자세한 내용은 --debug_mode 플래그를 사용하세요.

bq 명령줄 도구 살펴보기

시작하기 전에

Cloud Shell에서 bq 명령어 입력

플래그 및 인수 위치 지정

bq 명령줄 도구에서 쿼리 실행

도움말 보기

명령줄 플래그 기본값 설정

.bigqueryrc에 플래그 추가

대화형 셸에서 bq 명령줄 도구 실행

스크립트에서 bq 명령줄 도구 실행

서비스 계정에서 bq 명령어 실행

예

리소스 만들기

리소스 정보 가져오기

리소스 나열

작업 나열

리소스 업데이트

데이터 로드

데이터 쿼리

외부 데이터 소스 사용

데이터 내보내기

BigQuery Data Transfer Service 사용

bq 명령줄 도구 문제 해결

gcloud CLI를 최신 상태로 유지

디버깅

Cloud Shell에서 `bq` 명령어 입력

`.bigqueryrc`에 플래그 추가

서비스 계정에서 `bq` 명령어 실행