bq 명령줄 도구 사용

bq는 python 기반의 BigQuery용 명령줄 도구입니다. 이 페이지에는 bq 명령줄 도구 사용에 대한 일반 정보가 있습니다.

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

시작하기 전에

BigQuery 명령줄 도구를 사용하려면 먼저 Google Cloud Platform 콘솔을 사용하여 프로젝트를 만들거나 선택하고 결제를 사용 설정해야 합니다. Google Cloud SDK도 설치해야 합니다.

  1. Google 계정에 로그인합니다.

    아직 계정이 없으면 새 계정을 등록하세요.

  2. Select or create a Google Cloud Platform project.

    Go to the Manage resources page

  3. 프로젝트에 결제가 사용 설정되어 있는지 확인하세요.

    결제 사용 설정 방법 알아보기

  4. Install and initialize the Cloud SDK.
  5. 새 프로젝트에서는 BigQuery가 자동으로 사용 설정됩니다. 기존 프로젝트에서 BigQuery를 활성화하려면 다음으로 이동하세요. BigQuery API를 사용 설정합니다.

    API 사용 설정

Cloud SDK를 다운로드하여 설치하는 방법 이외에 Google Cloud Shell에서 사전 설치된 SDK 버전을 사용할 수 있습니다.

일반적인 사용

플래그 위치 지정

bq는 두 가지 종류(전역 플래그, 명령어 플래그)의 플래그를 지원합니다. 플래그는 다음과 같은 순서로 사용해야 합니다.

    bq --global_flag [ARGUMENT] bq_command --command-specific_flag [ARGUMENT]
  • 전역 플래그(또는 공통 플래그)는 모든 명령어에 사용할 수 있습니다.
  • 명령어 관련 플래그는 특정 명령어에 적용됩니다.

여러 전역 플래그 또는 명령어 관련 플래그는 공백으로 구분합니다. 예를 들면 다음과 같습니다.

    bq --global_flag [ARGUMENT] --global_flag [ARGUMENT] bq_command --command-specific_flag [ARGUMENT] --command-specific_flag [ARGUMENT]

다음 방법 중 하나로 명령어 인수를 지정할 수 있습니다.

  • --flag=[ARGUMENT]
  • --flag='[ARGUMENT]'
  • --flag="[ARGUMENT]"
  • --flag [ARGUMENT]
  • --flag '[ARGUMENT]'
  • --flag "[ARGUMENT]"

이러한 각 메소드는 BigQuery 문서 전체에서 사용됩니다.

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

bq query --nouse_legacy_sql 'select count(*) from `bigquery-public-data.samples.shakespeare`'

부울 값이 있는 플래그는 인수 없이 지정할 수 있습니다. true 또는 false를 지정하는 경우 =[ARGUMENT]를 지정해야 합니다.

예를 들어, 다음 명령어는 부울 플래그 --use_legacy_sql에 대해 플래그 앞에 no를 지정하여 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 명령줄 도구 참조를 확인하세요.

도움말 보기

다음 명령어를 입력하면 bq 명령줄 도구의 도움말을 확인할 수 있습니다.

  • 설치된 bq 버전에 bq version을 입력하세요.
  • 전체 명령어 목록에 bq help를 입력하세요.
  • 전역 플래그 목록에 bq --help를 입력하세요.
  • 특정 명령어에 대한 도움말을 보려면 bq help [COMMAND]를 입력하세요.
  • 특정 명령어에 대한 도움말과 전역 플래그 목록을 보려면 bq [COMMAND] --help를 입력하세요.

디버깅

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

  • 보내고 받은 요청 확인하기
    --apilog=[PATH_TO_FILE] 플래그를 추가하여 작업 로그를 로컬 파일에 저장합니다. bq는 표준 REST 기반 API 호출을 수행하여 작동하므로 보는 데 유용합니다. 또한 문제 보고 시 이 로그를 첨부하는 것이 유용합니다. 파일 경로 대신 - 또는 stdout을 사용하면 로그가 콘솔로 출력됩니다. --apilogstderr로 설정하면 표준 오류 파일로 출력됩니다.
  • 오류 해결하기
    작업의 상태를 가져오거나 테이블 및 데이터세트와 같은 리소스의 자세한 정보를 보는 경우, --format=prettyjson 플래그를 입력합니다. 이 플래그를 사용하면 reason 속성을 포함하여 JSON 형식의 응답이 출력됩니다. reason 속성을 사용하면 문제 해결 단계를 확인할 수 있습니다.

명령줄 플래그 기본값 설정

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

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

.bigqueryrc에 플래그 추가

.bigqueryrc에 명령줄 플래그 기본값을 추가하려면 다음과 같이 하세요.

  • 파일 맨 위에 헤더 없이 전역 플래그를 배치합니다.
  • 명령어 관련 플래그의 경우, 대괄호 안에 명령어 이름을 입력하고 그 아래에 다음 형식으로 명령어 관련 플래그를 한 줄에 하나씩 추가합니다.

    [COMMAND]
    --command-specific_flag=[ARGUMENT]
    --command-specific_flag=[ARGUMENT]
    

.bigqueryrc에 명령줄 플래그를 입력하면 플래그 인수를 =[ARGUMENT] 형식으로 지정해야 합니다.

.bigqueryrcbq를 실행할 때마다 읽혀지므로 변경 사항이 즉시 업데이트됩니다. 대화형 모드(bq shell)에서 bq를 실행하는 경우 변경 사항을 적용하려면 셸을 다시 시작해야 합니다.

다음 예에서는 다음 전역 플래그 기본값을 설정합니다.

  • --apilogstdout으로 설정하여 디버깅 출력을 콘솔에 표시합니다.
  • --formatprettyjson으로 설정하여 명령어 출력을 사람이 읽을 수 있는 JSON 형식으로 표시합니다.
  • --locationUS 다중 지역 위치로 설정합니다.

다음 예에서는 다음 query 명령어 관련 플래그 기본값을 설정합니다.

  • --use_legacy_sqlfalse로 설정하여 표준 SQL을 기본 쿼리 구문으로 지정합니다.

  • --max_rows를 100으로 설정하여 쿼리 출력의 행 수를 제어합니다.

  • --maximum_bytes_billed를 10,000,000바이트(10MB)로 설정하면 10MB가 넘는 데이터를 읽는 쿼리가 실패합니다.

다음 예에서는 다음 load 명령어 관련 플래그 기본값을 설정합니다.

  • --destination_kms_keyprojects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey로 설정합니다.
credential_file = [PATH_TO_CREDENTIAL_FILE]
--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

설정을 확인하려면 다음 명령어를 입력하세요.

cat ~/.bigqueryrc

대화형 셸에서 bq 실행

대화형 셸에서 bq를 실행할 수 있으며, 이 경우 명령어에 bq 프리픽스를 붙일 필요가 없습니다. bq shell을 입력하여 대화형 모드를 시작합니다. 셸이 시작되면 프롬프트가 기본 프로젝트의 ID로 변경됩니다. 대화형 모드를 종료하려면 exit을 입력합니다.

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

리소스 만들기

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

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

리소스 정보 가져오기

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

리소스 나열

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

리소스 업데이트

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

데이터 로드

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

데이터 쿼리

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

외부 데이터 소스 사용

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

데이터 내보내기

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

BigQuery 데이터 전송 서비스 사용

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

이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

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

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