리소스에 라벨 추가
이 페이지에서는 BigQuery 리소스에 라벨을 지정하는 방법을 설명합니다.
시작하기 전에
사용자에게 이 문서의 각 작업을 수행하는 데 필요한 권한을 부여하는 Identity and Access Management(IAM) 역할을 부여합니다. 태스크를 수행하는 데 필요한 모든 권한이 태스크의 '필요한 IAM 역할' 섹션에 나열됩니다.
데이터 세트에 라벨 추가
bq 명령줄 도구의 bq mk
명령어를 사용하거나 datasets.insert
API 메서드를 호출하여 BigQuery 데이터 세트를 만들 때 여기에 라벨을 추가할 수 있습니다.
현재는 Google Cloud 콘솔을 사용하여 데이터 세트를 만들 때 여기에 라벨을 추가할 수 없습니다.
이 페이지에서는 데이터 세트가 만들어진 후 라벨을 추가하는 방법에 대해 설명합니다. 데이터 세트를 만들 때 라벨을 추가하는 방법에 대한 자세한 내용은 데이터 세트 만들기를 참조하세요.
다음 방법으로 데이터 세트를 만든 후 여기에 라벨을 추가할 수 있습니다.
- Google Cloud 콘솔 사용
- SQL DDL 문 사용
- bq 명령줄 도구의
bq update
명령어 사용 datasets.patch
API 메서드 호출- 클라이언트 라이브러리 사용
데이터 세트에 라벨을 추가할 때, 라벨이 데이터 세트 내의 리소스로 전파되지는 않습니다. 데이터 세트 라벨은 테이블 또는 뷰에 상속되지 않습니다. 또한 데이터 세트에 라벨을 추가하면 스토리지 결제 데이터에 포함되지만 작업 관련 결제 데이터에는 포함되지 않습니다.
라벨 형식에 대한 자세한 내용은 라벨 요구사항을 참조하세요.
필요한 IAM 역할
기존 데이터 세트에 라벨을 추가하는 데 필요한 권한을 얻으려면 관리자에게 BigQuery 데이터 편집자(roles/bigquery.dataEditor
) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.
이 사전 정의된 역할에는 기존 데이터 세트에 라벨을 추가하는 데 필요한 bigquery.datasets.update
권한이 포함되어 있습니다.
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
BigQuery의 IAM 역할과 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.
데이터 세트에 라벨 추가
데이터 세트가 만들어진 후 데이터 세트에 라벨을 추가하려면 다음 안내를 따르세요.
콘솔
Google Cloud 콘솔에서 데이터 세트를 선택합니다.
데이터 세트 세부정보 페이지에서 라벨 오른쪽에 있는 연필 아이콘을 클릭합니다.
라벨 수정 대화상자에서 다음을 수행합니다.
- 라벨 추가를 클릭합니다.
- 키와 값을 입력합니다. 추가 라벨을 적용하려면 라벨 추가를 클릭합니다. 각 키는 데이터 세트당 한 번만 사용할 수 있지만 동일한 프로젝트의 여러 데이터 세트에 동일한 키를 사용할 수 있습니다.
- 라벨을 업데이트하려면 기존 키나 값을 수정합니다.
- 변경사항을 저장하려면 업데이트를 클릭합니다.
SQL
기존 데이터 세트의 라벨을 설정하려면 ALTER SCHEMA SET OPTIONS
DDL 문을 사용합니다. 라벨을 설정하면 데이터 세트의 기존 라벨을 덮어씁니다. 다음 예시에서는 mydataset
데이터 세트에 라벨을 설정합니다.
Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.
쿼리 편집기에서 다음 문을 입력합니다.
ALTER SCHEMA mydataset SET OPTIONS ( labels = [('sensitivity', 'high')]);
실행을 클릭합니다.
쿼리를 실행하는 방법에 대한 자세한 내용은 대화형 쿼리 실행을 참조하세요.
bq
기존 데이터 세트에 라벨을 추가하려면 bq update
명령어를 set_label
플래그와 함께 실행합니다. 여러 개의 라벨을 추가하려면 플래그를 반복합니다.
데이터 세트가 기본 프로젝트 이외의 프로젝트에 있으면 PROJECT_ID:DATASET
형식으로 데이터 세트에 프로젝트 ID를 추가합니다.
bq update --set_label KEY:VALUE PROJECT_ID:DATASET
다음을 바꿉니다.
KEY:VALUE
: 추가하려는 라벨의 키-값 쌍입니다. 키는 고유해야 합니다. 키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다. 모든 문자는 UTF-8 인코딩을 사용해야 하며 국제 문자가 허용됩니다.PROJECT_ID
: 프로젝트 ID입니다.DATASET
: 라벨을 지정하는 데이터 세트입니다.
예를 들면 다음과 같습니다.
부서를 추적하는 라벨을 추가하려면 bq update
명령어를 입력하고 department
를 라벨 키로 지정합니다. 예를 들어 기본 프로젝트의 mydataset
에 department:shipping
라벨을 추가하려면 다음을 입력합니다.
bq update --set_label department:shipping mydataset
데이터 세트에 여러 라벨을 추가하려면 set_label
플래그를 반복하고 각 라벨에 고유 키를 지정합니다. 예를 들어 기본 프로젝트의 mydataset
에 department:shipping
라벨과 cost_center:logistics
라벨을 추가하려면 다음을 입력합니다.
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset
API
기존 데이터 세트에 라벨을 추가하려면 datasets.patch
메서드를 호출하고 데이터 세트 리소스의 labels
속성을 입력합니다.
datasets.update
메서드는 전체 데이터 세트 리소스를 대체하므로 datasets.patch
메서드를 사용하는 것이 좋습니다.
Go
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
자바
이 샘플은 Java용 Google HTTP 클라이언트 라이브러리를 사용하여 BigQuery API에 요청을 전송합니다.
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Node.js
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
테이블 및 뷰에 라벨 추가
다음 방법으로 테이블 또는 뷰를 만들 때 여기에 라벨을 추가할 수 있습니다.
- bq 명령줄 도구의
bq mk
명령어 사용 tables.insert
API 메서드 호출
이 페이지에서는 기존 테이블 또는 뷰에 라벨을 추가하는 방법에 대해 설명합니다. 테이블 또는 뷰를 만들 때 라벨을 추가하는 방법에 관한 자세한 내용은 테이블 만들기 또는 뷰 만들기를 참조하세요.
다음 방법으로 테이블 또는 뷰를 만든 후 라벨을 추가할 수 있습니다.
- Google Cloud 콘솔 사용
- bq 명령줄 도구의
bq update
명령어 사용 tables.patch
API 메서드 호출- 클라이언트 라이브러리 사용
뷰는 테이블 리소스와 같이 취급되므로 tables.patch
메서드를 사용하여 뷰와 테이블을 모두 수정합니다.
필요한 IAM 역할
기존 테이블 또는 뷰에 라벨을 추가하는 데 필요한 권한을 얻으려면 관리자에게 BigQuery 데이터 편집자(roles/bigquery.dataEditor
) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.
이 사전 정의된 역할에는 기존 테이블 또는 뷰에 라벨을 추가하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
기존 테이블 또는 뷰에 라벨을 추가하려면 다음 권한이 필요합니다.
-
bigquery.tables.update
-
bigquery.tables.get
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
BigQuery의 IAM 역할과 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.
테이블 또는 뷰에 라벨 추가
기존 테이블 또는 뷰에 라벨을 추가하려면 다음 안내를 따르세요.
콘솔
Google Cloud 콘솔에서 테이블 또는 뷰를 선택합니다.
세부정보 탭을 클릭합니다.
라벨 오른쪽에 있는 연필 아이콘을 클릭합니다.
라벨 수정 대화상자에서 다음을 수행합니다.
- 라벨 추가를 클릭합니다.
- 키와 값을 입력하여 라벨을 추가합니다. 추가 라벨을 적용하려면 라벨 추가를 클릭합니다. 각 키는 데이터 세트당 한 번만 사용할 수 있지만 동일한 프로젝트의 여러 데이터 세트에 동일한 키를 사용할 수 있습니다.
- 기존 키 또는 값을 수정하여 라벨을 업데이트합니다.
- 업데이트를 클릭하여 변경사항을 저장합니다.
SQL
ALTER TABLE SET OPTIONS
DDL 문을 사용하여 기존 테이블에 라벨을 설정하거나 ALTER VIEW SET OPTIONS
DDL 문을 사용하여 기존 뷰에 라벨을 설정합니다. 라벨을 설정하면 테이블 또는 뷰의 기존 라벨을 덮어씁니다. 다음 예시에서는 테이블 mytable
에 라벨 두 개를 설정합니다.
Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.
쿼리 편집기에서 다음 문을 입력합니다.
ALTER TABLE mydataset.mytable SET OPTIONS ( labels = [('department', 'shipping'), ('cost_center', 'logistics')]);
실행을 클릭합니다.
쿼리를 실행하는 방법에 대한 자세한 내용은 대화형 쿼리 실행을 참조하세요.
bq
기존 테이블 또는 뷰에 라벨을 추가하려면 bq update
명령어를 set_label
플래그와 함께 실행합니다. 라벨을 여러 개 추가하려면 플래그를 반복합니다.
테이블 또는 뷰가 기본 프로젝트 이외의 프로젝트에 있으면 프로젝트 ID를 project_id:dataset
형식으로 데이터 세트에 추가합니다.
bq update \ --set_label KEY:VALUE \ PROJECT_ID:DATASET.TABLE_OR_VIEW
다음을 바꿉니다.
KEY:VALUE
: 추가하려는 라벨의 키-값 쌍입니다. 키는 고유해야 합니다. 키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다. 모든 문자는 UTF-8 인코딩을 사용해야 하며 국제 문자가 허용됩니다.PROJECT_ID
: 프로젝트 ID입니다.DATASET
: 라벨을 지정할 테이블 또는 뷰가 포함된 데이터 세트입니다.TABLE_OR_VIEW
: 라벨을 지정할 테이블 또는 뷰의 이름입니다.
예를 들면 다음과 같습니다.
부서를 추적하는 테이블 라벨을 추가하려면 bq update
명령어를 입력하고 department
를 라벨 키로 지정합니다. 예를 들어 기본 프로젝트의 mytable
에 department:shipping
라벨을 추가하려면 다음을 입력합니다.
bq update --set_label department:shipping mydataset.mytable
부서를 추적하는 뷰 라벨을 추가하려면 bq update
명령어를 입력하고 department
를 라벨 키로 지정합니다. 예를 들어 기본 프로젝트의 myview
에 department:shipping
라벨을 추가하려면 다음을 입력합니다.
bq update --set_label department:shipping mydataset.myview
테이블 또는 뷰에 여러 라벨을 추가하려면 set_label
플래그를 반복하고 각 라벨에 고유한 키를 지정합니다. 예를 들어 기본 프로젝트의 mytable
에 department:shipping
라벨과 cost_center:logistics
라벨을 추가하려면 다음을 입력합니다.
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset.mytable
API
기존 테이블 또는 뷰에 라벨을 추가하려면 tables.patch
메서드를 호출하고 테이블 리소스의 labels
속성을 입력합니다.
뷰는 테이블 리소스와 같이 취급되므로 tables.patch
메서드를 사용하여 뷰와 테이블을 모두 수정합니다.
tables.update
메서드는 전체 데이터 세트 리소스를 대체하므로 tables.patch
메서드를 사용하는 것이 좋습니다.
Go
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
자바
이 샘플은 Java용 Google HTTP 클라이언트 라이브러리를 사용하여 BigQuery API에 요청을 전송합니다.
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Node.js
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
작업에 라벨 추가
bq 명령줄 도구의 --label
플래그를 사용하여 명령줄을 통해 쿼리 작업에 라벨을 추가할 수 있습니다. bq 도구는 쿼리 작업에만 라벨 추가를 지원합니다.
또한 jobs.insert
메서드를 호출할 때 작업 구성에서 labels
속성을 지정하면 API를 통해 작업을 제출할 때 작업에 라벨을 추가할 수 있습니다. API를 사용하면 모든 작업 유형에 라벨을 추가할 수 있습니다.
대기 중이거나 실행 중이거나 완료된 작업에는 라벨을 추가하거나 업데이트할 수 없습니다.
작업에 라벨을 추가하면 라벨이 결제 데이터에 포함됩니다.
필요한 IAM 역할
작업에 라벨을 추가하는 데 필요한 권한을 얻으려면 관리자에게 BigQuery 사용자(roles/bigquery.user
) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.
이 사전 정의된 역할에는 작업에 라벨을 추가하는 데 필요한 bigquery.jobs.create
권한이 포함되어 있습니다.
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
BigQuery의 IAM 역할과 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.
작업에 라벨 추가
작업에 라벨을 추가하려면 다음 안내를 따르세요.
bq
쿼리 작업에 라벨을 추가하려면 --label
명령어를 bq query
플래그와 함께 실행합니다. 라벨을 여러 개 추가하려면 플래그를 반복합니다. --nouse_legacy_sql
플래그는 쿼리가 GoogleSQL 구문임을 나타냅니다.
bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'
다음을 바꿉니다.
KEY:VALUE
: 쿼리 작업에 추가하려는 라벨의 키-값 쌍입니다. 키는 고유해야 합니다. 키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다. 모든 문자는 UTF-8 인코딩을 사용해야 하며 국제 문자가 허용됩니다. 쿼리 작업에 여러 라벨을 추가하려면--label
플래그를 반복하고 각 라벨에 고유한 키를 지정합니다.QUERY
: 유효한 GoogleSQL 쿼리입니다.
예:
쿼리 작업에 라벨을 추가하려면 다음을 입력합니다.
bq query \
--label department:shipping \
--nouse_legacy_sql \
'SELECT
column1, column2
FROM
`mydataset.mytable`'
쿼리 작업에 여러 라벨을 추가하려면 --label
플래그를 반복하고 각 라벨에 고유한 키를 지정합니다. 예를 들어 쿼리 작업에 department:shipping
라벨과 cost_center:logistics
라벨을 추가하려면 다음을 입력합니다.
bq query \
--label department:shipping \
--label cost_center:logistics \
--nouse_legacy_sql \
'SELECT
column1, column2
FROM
`mydataset.mytable`'
API
작업에 라벨을 추가하려면 jobs.insert
메서드를 호출하고 작업 구성의 labels
속성을 입력합니다.
API를 사용하면 모든 작업 유형에 라벨을 추가할 수 있습니다.
세션의 작업을 라벨과 연결
세션에서 쿼리를 실행하는 경우 BigQuery 멀티 문 쿼리를 사용하여 세션의 모든 향후 쿼리 작업에 라벨을 할당할 수 있습니다.
SQL
다음 쿼리를 실행하여 세션에서 @@query_label
시스템 변수를 설정합니다.
SET @@query_label = "KEY:VALUE";
- KEY:VALUE: 세션의 모든 향후 쿼리에 할당할 라벨의 키-값 쌍입니다. 키는 고유해야 합니다. 키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다. 모든 문자는 UTF-8 인코딩을 사용해야 하며 국제 문자가 허용됩니다.
예:
SET @@query_label = "cost_center:logistics";
API
API 호출을 사용하여 쿼리를 실행할 때 세션의 쿼리 작업에 라벨을 추가하려면 jobs.insert
메서드를 호출하고 connectionProperties
작업 구성의 query_label
속성을 채웁니다.
쿼리 라벨을 세션과 연결하고 세션 내에서 쿼리를 실행한 후에는 해당 쿼리 라벨이 있는 쿼리의 감사 로그를 수집할 수 있습니다. 자세한 내용은 BigQuery의 감사 로그 참조를 확인하세요.
값이 없는 라벨 추가
키의 값이 비어 있는 라벨을 태그라고도 부릅니다. 이를 태그 리소스와 혼동해서는 안 됩니다. 자세한 내용은 라벨 및 태그를 참조하세요. 값이 없는 새 라벨을 만들거나 기존 라벨 키에서 값을 삭제할 수 있습니다.
값이 없는 라벨은 리소스에 라벨을 지정하지만 키-값 형식이 필요하지 않은 경우에 유용할 수 있습니다. 예를 들어 테이블에 지원 또는 개발과 같은 여러 그룹에 사용되는 테스트 데이터가 포함된 경우 test_data
라벨을 테이블에 추가하여 이를 식별할 수 있습니다.
값이 없는 라벨을 추가하려면 다음 안내를 따르세요.
콘솔
Google Cloud 콘솔에서 적절한 리소스(데이터 세트, 테이블, 뷰)를 선택합니다.
데이터 세트의 경우 데이터 세트 세부정보 페이지가 자동으로 열립니다. 테이블 및 뷰의 경우 세부정보를 클릭하여 세부정보 페이지를 엽니다.
세부정보 페이지에서 라벨 오른쪽에 있는 연필 아이콘을 클릭합니다.
라벨 수정 대화상자에서 다음을 수행합니다.
- 라벨 추가를 클릭합니다.
- 새 키를 입력하고 값을 비워 둡니다. 추가 라벨을 적용하려면 라벨 추가를 클릭하고 반복합니다.
- 변경사항을 저장하려면 업데이트를 클릭합니다.
SQL
값 없이 라벨을 추가하려면 ALTER TABLE SET OPTIONS
DDL 문을 사용합니다.
Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.
쿼리 편집기에서 다음 문을 입력합니다.
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("key1", ""), ("key2", "")]);
실행을 클릭합니다.
쿼리를 실행하는 방법에 대한 자세한 내용은 대화형 쿼리 실행을 참조하세요.
bq
기존 리소스에 값이 없는 라벨을 추가하려면 bq update
명령어를 set_label
플래그와 함께 실행합니다. 키를 지정하고 그 뒤에 콜론을 입력하고, 값을 지정하지 않고 비워 둡니다.
bq update --set_label KEY: RESOURCE_ID
다음을 바꿉니다.
KEY:
: 사용할 라벨 키입니다.RESOURCE_ID
: 유효한 데이터 세트, 테이블 또는 뷰 이름입니다. 리소스가 기본 프로젝트 이외의 프로젝트에 있으면PROJECT_ID:DATASET
형식으로 프로젝트 ID를 추가합니다.
예:
다음 명령어를 입력하여 mydataset.mytable
에 대해 test_data
라벨을 만듭니다. 여기서 mydataset
는 기본 프로젝트에 있습니다.
bq update --set_label test_data: mydataset
API
datasets.patch
메서드 또는 tables.patch
메서드를 호출하고 데이터 세트 리소스 또는 테이블 리소스에 빈 문자열(""
)로 설정된 값이 있는 라벨을 추가합니다.
기존 라벨의 값을 빈 문자열로 대체하여 값을 삭제할 수 있습니다.
뷰는 테이블 리소스와 같이 취급되므로 tables.patch
메서드를 사용하여 뷰와 테이블을 모두 수정합니다. 또한 tables.update
메서드는 전체 데이터 세트 리소스를 대체하므로 tables.patch
메서드를 사용하는 것이 좋습니다.
다음 단계
- BigQuery 리소스에 대한 라벨 보기 방법을 알아보세요.
- BigQuery 리소스에 대한 라벨 업데이트 방법을 알아보세요.
- 라벨을 사용한 리소스 필터링 방법 알아보기
- BigQuery 리소스의 라벨 삭제 방법 알아보기
- Resource Manager 문서의 라벨 사용 읽어보기