라벨 만들기 및 관리

BigQuery 리소스를 체계화하기 위해 데이터세트, 테이블, 뷰에 라벨을 추가할 수 있습니다. 라벨은 리소스에 연결할 수 있는 키-값 쌍입니다. BigQuery 리소스를 만들 때 라벨은 선택사항입니다.

리소스에 라벨을 추가하면 라벨 값을 기준으로 리소스를 검색할 수 있습니다. 예를 들어 라벨을 사용하여 용도, 환경, 부서 등을 기준으로 데이터세트를 그룹화할 수 있습니다.

이 페이지에서는 BigQuery 리소스에서 라벨을 사용하는 방법을 설명합니다. 또한 리소스의 라벨을 추가, 업데이트, 제거하는 방법도 설명합니다.

라벨이란 무엇인가요?

라벨은 Google Cloud Platform BigQuery 리소스를 체계화하는 데 도움이 되는 키-값 쌍입니다. 각 리소스에 라벨을 연결한 다음 해당 라벨을 기준으로 리소스를 필터링할 수 있습니다. 라벨에 대한 정보는 결제 시스템으로 전달되므로 라벨을 기준으로 청구 상세 내역을 확인할 수 있습니다.

라벨의 일반적인 사용 사례

다음은 라벨의 몇 가지 일반적인 사용 사례입니다.

  • 팀 또는 비용 센터 라벨: 팀 또는 비용 센터 기준의 라벨을 추가하여 team:researchteam:analytics와 같은 여러 팀에서 소유한 BigQuery 리소스를 구별할 수 있습니다. 원가 계산이나 예산 책정에 이 유형의 라벨을 사용할 수 있습니다.

  • 구성요소 라벨: component:redis, component:frontend, component:ingest, component:dashboard를 예로 들 수 있습니다.

  • 환경 또는 단계 라벨: environment:productionenvironment:test를 예로 들 수 있습니다.

  • 소유자 또는 연락처 라벨: 소유자 또는 BigQuery 리소스의 기본 연락처를 기준으로 라벨을 추가합니다.

  • 상태 라벨: state:active, state:readytodelete, state:archive를 예로 들 수 있습니다.

라벨 요구 사항

리소스에 적용된 라벨은 다음 요구 사항을 충족해야 합니다.

  • 각 리소스는 여러 개의 라벨(최대 64개)을 가질 수 있습니다.
  • 각 라벨은 키-값 쌍이어야 합니다.
  • 키는 비워 둘 수 없으며 최소 길이는 1자이고 최대 길이는 63자입니다. 값은 비워 둘 수 있으며 최대 길이는 63자입니다.
  • 키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다. 모든 문자는 UTF-8 인코딩을 사용해야 하며 국제 문자가 허용됩니다.
  • 라벨의 키 부분은 고유해야 합니다. 그러나 여러 리소스에 동일한 키를 사용할 수 있습니다.
  • 키는 소문자나 국제 문자로 시작해야 합니다.

데이터세트 라벨 생성 및 준비

BigQuery 데이터세트를 만들 때 명령줄 도구의 bq mk 명령어를 사용하거나 datasets.insert API 메소드를 호출하여 라벨을 추가할 수 있습니다. 데이터세트를 만들 때 라벨을 추가하는 방법에 대한 자세한 내용은 데이터세트 만들기를 참조하세요.

데이터세트를 만든 후 BigQuery 웹 UI, 명령줄 도구의 bq update 명령어를 사용하거나 datasets.patch API 메소드를 호출하여 라벨을 추가하거나 업데이트할 수 있습니다.

필수 권한

데이터세트가 만들어진 후 데이터세트 라벨을 추가하거나 업데이트하려면 데이터세트 수준의 OWNER 액세스 권한이 있거나 bigquery.datasets.update 권한이 포함된 프로젝트 수준의 IAM 역할을 할당받아야 합니다. 사전 정의된 프로젝트 수준의 다음 IAM 역할에는 bigquery.datasets.update 권한이 포함되어 있습니다.

또한 bigquery.user 역할에는 bigquery.datasets.create 권한이 있으므로 bigquery.user 역할에 할당된 사용자는 만드는 모든 데이터세트를 업데이트할 수 있습니다. bigquery.user 역할에 할당된 사용자가 데이터세트를 만들면 이 사용자에게 데이터세트 OWNER 액세스 권한이 부여됩니다. 데이터세트에 대한 OWNER 액세스 권한은 사용자에게 전체 제어 권한을 부여합니다.

BigQuery의 IAM 역할 및 권한에 대한 자세한 내용은 액세스 제어를 참조하세요. 데이터세트 수준 역할에 대한 자세한 내용은 데이터세트의 기본 역할을 참조하세요.

데이터세트 라벨 만들기 또는 업데이트

데이터세트가 만들어진 후 데이터세트 라벨을 업데이트하거나 데이터세트에 라벨을 추가하려면 다음 안내를 따르세요.

웹 UI

  1. 웹 UI에서 데이터세트를 선택합니다.

  2. 데이터세트 세부정보 페이지에서 라벨 오른쪽의 편집을 클릭합니다.

    라벨 수정

  3. 라벨 편집 대화 상자에서:

    • 키와 값을 입력하여 라벨을 추가합니다. 추가 라벨을 적용하려면 라벨 추가를 클릭합니다. 각 키는 데이터세트당 한 번만 사용할 수 있지만 동일한 프로젝트의 여러 데이터세트에 동일한 키를 사용할 수 있습니다.
    • 기존 키 또는 값을 수정하여 라벨을 업데이트합니다.
    • 확인을 클릭합니다.

      새 라벨

명령줄

데이터세트 라벨을 추가하거나 업데이트하려면 bq update 명령어를 set_label 플래그와 함께 실행합니다. 여러 개의 라벨을 추가하거나 업데이트하려면 플래그를 반복합니다.

데이터세트가 기본 프로젝트 이외의 프로젝트에 있는 경우 [PROJECT_ID]:[DATASET] 형식으로 데이터세트에 프로젝트 ID를 추가합니다.

    bq update --set_label [KEY:VALUE] [PROJECT_ID]:[DATASET]

각 항목의 의미는 다음과 같습니다.

  • [KEY:VALUE]는 만들거나 업데이트하려는 라벨의 키:값 쌍에 해당합니다. 기존 라벨과 동일한 키를 지정하는 경우 기존 라벨의 값이 업데이트됩니다. 키는 고유해야 합니다.
  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 업데이트하는 데이터세트입니다.

예:

부서를 추적하기 위한 라벨을 추가하려면 bq update 명령어를 입력하고 department를 라벨 키로 지정합니다. 예를 들어 기본 프로젝트의 mydatasetdepartment:shipping 라벨을 추가하려면 다음을 입력합니다.

    bq update --set_label department:shipping mydataset

department 라벨을 업데이트하려면 bq update 명령어를 입력하고 department를 라벨 키로 지정합니다. 예를 들어 department:shipping 라벨을 department:logistics로 업데이트하려면 다음 명령어를 입력합니다. mydataset는 기본 프로젝트가 아닌 myotherproject에 있습니다.

    bq update --set_label department:logistics myotherproject:mydataset

데이터세트에 여러 라벨을 추가하려면 set_label 플래그를 반복하고 각 라벨에 고유한 키를 지정합니다. 데이터세트의 여러 라벨을 삭제하려면 clear_label 플래그를 반복하고 각 키:값 쌍을 지정합니다. 예를 들어 기본 프로젝트의 mydatasetdepartment: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 참조 문서를 확인하세요.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
ds := client.Dataset(datasetID)
meta, err := ds.Metadata(ctx)
if err != nil {
	return err
}

update := bigquery.DatasetMetadataToUpdate{}
update.SetLabel("color", "green")
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

자바

이 샘플은 자바용 Google HTTP 클라이언트 라이브러리를 사용하여 BigQuery API에 요청을 전송합니다.
static final HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
static final JsonFactory JSON_FACTORY = new JacksonFactory();

public static class Dataset {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Dataset addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a dataset.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelDataset(
    String projectId, String datasetId, String labelKey, String labelValue) throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Dataset dataset = new Dataset();
  dataset.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, dataset);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url = new GenericUrl(String.format(urlFormat, projectId, datasetId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Dataset responseDataset = response.parseAs(Dataset.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseDataset.getLabels().get(labelKey));
}

Python

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참조 문서를 확인하세요.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

assert dataset.labels == {}
labels = {'color': 'green'}
dataset.labels = labels

dataset = client.update_dataset(dataset, ['labels'])  # API request

assert dataset.labels == labels

테이블 및 뷰 라벨 만들기 및 업데이트

테이블 또는 뷰를 만들 때 명령줄 도구의 bq mk 명령어를 사용하거나 tables.insert API 메소드를 호출하여 라벨을 추가할 수 있습니다. 테이블 또는 뷰를 만들 때 라벨을 추가하는 방법에 관한 자세한 내용은 테이블 만들기 또는 뷰 만들기를 참조하세요.

테이블 또는 뷰를 만든 후 BigQuery 웹 UI, 명령줄 도구의 bq update 명령어를 사용하거나 tables.patch API 메소드를 호출하여 라벨을 추가하거나 업데이트할 수 있습니다. 뷰는 테이블 리소스와 같이 취급되므로 tables.patch 메소드를 사용하여 뷰와 테이블을 모두 수정합니다.

필수 권한

테이블 또는 뷰 라벨을 만들거나 업데이트하려면 데이터세트 수준의 OWNER 액세스 권한이 있거나 bigquery.tables.update 권한이 포함된 프로젝트 수준 IAM 역할을 할당받아야 합니다. 다음 사전 정의된 프로젝트 수준 IAM 역할에는 bigquery.tables.update 권한이 포함됩니다.

또한 bigquery.user 역할에는 bigquery.datasets.create 권한이 있으므로 bigquery.user 역할에 할당된 사용자는 사용자가 만드는 모든 데이터세트의 테이블과 뷰를 업데이트할 수 있습니다. bigquery.user 역할에 할당된 사용자가 데이터세트를 만들면 이 사용자에게 데이터세트 OWNER 액세스 권한이 부여됩니다. 데이터세트 OWNER 액세스 권한이 있으면 사용자는 해당 데이터세트와 데이터세트에 포함된 테이블 및 뷰를 완전히 제어할 수 있습니다.

BigQuery의 IAM 역할 및 권한에 대한 자세한 내용은 액세스 제어를 참조하세요. 데이터세트 수준 역할에 대한 자세한 내용은 데이터세트의 기본 역할을 참조하세요.

테이블 또는 뷰 라벨 만들기 또는 업데이트

테이블 또는 뷰 라벨을 업데이트하거나 테이블 또는 뷰가 만들어진 후 라벨을 추가하려면 다음 안내를 따르세요.

웹 UI

  1. 웹 UI에서 테이블 또는 뷰를 선택합니다.

  2. 세부정보 페이지에서 라벨 오른쪽의 편집을 클릭합니다. 이 예에서는 테이블의 세부정보를 보여줍니다.

    라벨 수정

  3. 라벨 편집 대화 상자에서:

    • 키와 값을 입력하여 라벨을 추가합니다. 추가 라벨을 적용하려면 라벨 추가를 클릭합니다. 각 키는 테이블 또는 뷰당 한 번만 사용할 수 있지만 여러 데이터세트의 테이블 또는 뷰에 동일한 키를 사용할 수 있습니다.
    • 기존 키 또는 값을 수정하여 라벨을 업데이트합니다.
    • 확인을 클릭합니다.

      새 라벨

명령줄

테이블 또는 뷰 라벨을 추가하거나 업데이트하려면 bq update 명령어를 set_label 플래그와 함께 실행합니다. 여러 개의 라벨을 추가하거나 업데이트하려면 플래그를 반복합니다.

테이블 또는 뷰가 기본 프로젝트가 아닌 다른 프로젝트에 있는 경우 프로젝트 ID를 [PROJECT_ID]:[DATASET] 형식으로 데이터세트에 추가합니다.

    bq update --set_label [KEY:VALUE] [PROJECT_ID]:[DATASET].[TABLE_OR_VIEW]

각 항목의 의미는 다음과 같습니다.

  • [KEY:VALUE]는 만들거나 업데이트하려는 라벨의 키:값 쌍에 해당합니다. 기존 라벨과 동일한 키를 지정하는 경우 기존 라벨의 값이 업데이트됩니다. 키는 고유해야 합니다.
  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 업데이트하는 테이블 또는 뷰가 포함된 데이터세트입니다.
  • [TABLE_OR_VIEW]는 업데이트하는 테이블 또는 뷰의 이름입니다.

예:

부서를 추적하기 위한 라벨을 추가하려면 bq update 명령어를 입력하고 department를 라벨 키로 지정합니다. 예를 들어 기본 프로젝트의 mytabledepartment:shipping 라벨을 추가하려면 다음을 입력합니다.

    bq update --set_label department:shipping mydataset.mytable

부서를 추적하기 위한 라벨을 추가하려면 bq update 명령어를 입력하고 department를 라벨 키로 지정합니다. 예를 들어 기본 프로젝트의 myviewdepartment:shipping 라벨을 추가하려면 다음을 입력합니다.

    bq update --set_label department:shipping mydataset.myview

department 라벨을 업데이트하려면 bq update 명령어를 입력하고 department를 라벨 키로 지정합니다. 예를 들어 mytabledepartment:shipping 라벨을 department:logistics로 업데이트하려면 다음 명령어를 입력합니다. mytable은 기본 프로젝트가 아닌 myotherproject에 있습니다.

    bq update --set_label department:logistics myotherproject:mydataset.mytable

테이블 또는 뷰에 여러 라벨을 추가하려면 set_label 플래그를 반복하고 각 라벨에 고유한 키를 지정합니다. 예를 들어 기본 프로젝트의 mytabledepartment: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 참조 문서를 확인하세요.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
tbl := client.Dataset(datasetID).Table(tableID)
meta, err := tbl.Metadata(ctx)
if err != nil {
	return err
}

update := bigquery.TableMetadataToUpdate{}
update.SetLabel("color", "green")
if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
	return err
}

자바

이 샘플은 자바용 Google HTTP 클라이언트 라이브러리를 사용하여 BigQuery API에 요청을 전송합니다.
public static class Table {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Table addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a table.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelTable(
    String projectId,
    String datasetId,
    String tableId,
    String labelKey,
    String labelValue)
    throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Table table = new Table();
  table.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, table);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s/tables/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url =
      new GenericUrl(String.format(urlFormat, projectId, datasetId, tableId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Table responseTable = response.parseAs(Table.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseTable.getLabels().get(labelKey));
}

Python

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참조 문서를 확인하세요.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.labels == {}
labels = {'color': 'green'}
table.labels = labels

table = client.update_table(table, ['labels'])  # API request

assert table.labels == labels

라벨 삭제

BigQuery 웹 UI, 명령줄 도구의 bq update 명령어를 사용하거나 datasets.patch 또는 tables.patch API 메소드를 호출하여 데이터세트, 테이블 또는 뷰에서 라벨을 제거할 수 있습니다.

데이터세트 라벨 삭제

데이터세트 라벨을 제거하려면 BigQuery 웹 UI, 명령줄 도구의 bq update 명령어를 사용하거나 datasets.patch API 메소드를 호출합니다.

필수 권한

데이터세트 라벨을 삭제하려면 데이터세트 수준의 OWNER 액세스 권한이 있거나 bigquery.datasets.update 권한이 포함된 프로젝트 수준의 IAM 역할을 할당받아야 합니다. 사전 정의된 프로젝트 수준의 다음 IAM 역할에는 bigquery.datasets.update 권한이 포함되어 있습니다.

또한 bigquery.user 역할에는 bigquery.datasets.create 권한이 있으므로 bigquery.user 역할에 할당된 사용자는 만드는 모든 데이터세트를 업데이트할 수 있습니다. bigquery.user 역할에 할당된 사용자가 데이터세트를 만들면 이 사용자에게 데이터세트 OWNER 액세스 권한이 부여됩니다. 데이터세트에 대한 OWNER 액세스 권한은 사용자에게 전체 제어 권한을 부여합니다.

BigQuery의 IAM 역할 및 권한에 대한 자세한 내용은 액세스 제어를 참조하세요. 데이터세트 수준 역할에 대한 자세한 내용은 데이터세트의 기본 역할을 참조하세요.

데이터세트 라벨 삭제

데이터세트에서 라벨을 삭제하려면 다음 안내를 따르세요.

웹 UI

  1. 웹 UI에서 데이터세트를 선택합니다.

  2. 데이터세트 세부정보 페이지에서 라벨 오른쪽의 편집을 클릭합니다.

  3. 라벨 편집 대화 상자에서:

    • 제거할 각 라벨의 삭제 아이콘(X)을 클릭합니다.
    • 확인을 클릭합니다.

      라벨 삭제

명령줄

데이터세트 라벨을 추가하거나 업데이트하려면 bq update 명령어를 clear_label 플래그와 함께 실행합니다. 여러 개의 라벨을 제거하려면 플래그를 반복합니다.

데이터세트가 기본 프로젝트 이외의 프로젝트에 있는 경우 [PROJECT_ID]:[DATASET] 형식으로 데이터세트에 프로젝트 ID를 추가합니다.

    bq update --clear_label [KEY] [PROJECT_ID]:[DATASET]

각 항목의 의미는 다음과 같습니다.

  • [KEY]는 제거할 라벨의 키입니다.
  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 업데이트하는 데이터세트입니다.

예:

mydataset에서 department:shipping 라벨을 제거하려면 bq update 명령어를 --clear_label 플래그와 함께 입력합니다. mydataset는 기본 프로젝트에 있습니다.

    bq update --clear_label department mydataset

myotherprojectmydataset에서 department:shipping 라벨을 제거하려면 bq update 명령어를 --clear_label 플래그와 함께 입력합니다.

    bq update --clear_label department myotherproject:mydataset

데이터세트에서 여러 라벨을 제거하려면 clear_label 플래그를 반복하고 각 라벨의 키를 지정합니다. 예를 들어 기본 프로젝트의 mydataset에서 department:shipping 라벨과 cost_center:logistics 라벨을 제거하려면 다음을 입력합니다.

    bq update --clear_label department --clear_label cost_center mydataset

API

기존 데이터세트의 특정 라벨을 제거하려면 datasets.patch 메소드를 호출하고 라벨의 키 값을 null로 설정하여 데이터세트 리소스labels 속성을 업데이트합니다.

데이터세트에서 모든 라벨을 제거하려면 datasets.patch 메소드를 호출하고 labels 속성을 제거합니다.

datasets.update 메소드는 전체 데이터세트 리소스를 대체하므로 datasets.patch 메소드를 사용하는 것이 좋습니다.

Go

이 샘플을 시도하기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참조 문서를 확인하세요.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
ds := client.Dataset(datasetID)
meta, err := ds.Metadata(ctx)
if err != nil {
	return err
}
update := bigquery.DatasetMetadataToUpdate{}
update.DeleteLabel("color")
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Python

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참조 문서를 확인하세요.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

# This example dataset starts with one label
assert dataset.labels == {'color': 'green'}
# To delete a label from a dataset, set its value to None
dataset.labels['color'] = None

dataset = client.update_dataset(dataset, ['labels'])  # API request

assert dataset.labels == {}

테이블 또는 뷰 라벨 삭제

테이블 또는 뷰 라벨을 제거하려면 BigQuery 웹 UI, 명령줄 도구의 bq update 명령어를 사용하거나 tables.patch API 메소드를 호출합니다. 뷰는 테이블 리소스와 같이 취급되므로 tables.patch 메소드를 사용하여 뷰와 테이블을 모두 수정합니다.

필수 권한

테이블 또는 뷰 라벨을 삭제하려면 데이터세트 수준의 OWNER 액세스 권한이 있거나 bigquery.tables.update 권한이 포함된 프로젝트 수준 IAM 역할을 할당받아야 합니다. 다음 사전 정의된 프로젝트 수준 IAM 역할에는 bigquery.tables.update 권한이 포함됩니다.

또한 bigquery.user 역할에 bigquery.datasets.create 권한이 포함되므로 bigquery.user 역할에 할당된 사용자는 사용자가 만드는 모든 데이터세트의 테이블 또는 뷰를 업데이트할 수 있습니다. bigquery.user 역할에 할당된 사용자가 데이터세트를 만들면 이 사용자에게 데이터세트 OWNER 액세스 권한이 부여됩니다. 데이터세트에 대한 OWNER 액세스 권한이 있으면 사용자는 해당 데이터세트와 데이터세트에 포함된 모든 테이블 및 뷰를 완전히 제어할 수 있습니다.

BigQuery의 IAM 역할 및 권한에 대한 자세한 내용은 액세스 제어를 참조하세요. 데이터세트 수준 역할에 대한 자세한 내용은 데이터세트의 기본 역할을 참조하세요.

테이블 또는 뷰 라벨 삭제

테이블 또는 뷰에서 라벨을 삭제하려면 다음 안내를 따르세요.

웹 UI

  1. 웹 UI에서 테이블 또는 뷰를 선택합니다.

  2. 세부정보 페이지에서 라벨 오른쪽의 편집을 클릭합니다.

  3. 라벨 편집 대화 상자에서:

    • 제거할 각 라벨의 삭제 아이콘(X)을 클릭합니다.
    • 확인을 클릭합니다.

      라벨 삭제

명령줄

테이블 또는 뷰 라벨을 삭제하려면 bq update 명령어를 clear_label 플래그와 함께 실행합니다. 여러 개의 라벨을 제거하려면 플래그를 반복합니다.

테이블 또는 뷰가 기본 프로젝트가 아닌 다른 프로젝트에 있는 경우 프로젝트 ID를 [PROJECT_ID]:[DATASET] 형식으로 데이터세트에 추가합니다.

    bq update --clear_label [KEY] [PROJECT_ID]:[TABLE_OR_VIEW]

각 항목의 의미는 다음과 같습니다.

  • [KEY]는 제거할 라벨의 키입니다.
  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 업데이트하는 데이터세트입니다.
  • [TABLE_OR_VIEW]는 업데이트하는 테이블 또는 뷰의 이름입니다.

예:

mydataset.mytable에서 department:shipping 라벨을 제거하려면 bq update 명령어를 --clear_label 플래그와 함께 입력합니다. mydataset는 기본 프로젝트에 있습니다.

    bq update --clear_label department mydataset.mytable

myotherprojectmydataset.myview에서 department:shipping 라벨을 제거하려면 bq update 명령어를 --clear_label 플래그와 함께 입력합니다.

    bq update --clear_label department myotherproject:mydataset.myview

테이블 또는 뷰에서 여러 라벨을 제거하려면 clear_label 플래그를 반복하고 각 라벨의 키를 지정합니다. 예를 들어 기본 프로젝트의 mydataset.mytable에서 department:shipping 라벨과 cost_center:logistics 라벨을 제거하려면 다음을 입력합니다.

    bq update --clear_label department --clear_label cost_center mydataset.mytable

API

기존 테이블 또는 뷰의 특정 라벨을 제거하려면 tables.patch 메소드를 호출하고 라벨의 키 값을 null로 설정하여 테이블 리소스labels 속성을 업데이트합니다.

테이블 또는 뷰에서 모든 라벨을 제거하려면 tables.patch 메소드를 호출하고 labels 속성을 제거합니다.

뷰는 테이블 리소스와 같이 취급되므로 tables.patch 메소드를 사용하여 뷰와 테이블을 모두 수정합니다. 또한 tables.update 메소드는 전체 데이터세트 리소스를 대체하므로 tables.patch 메소드를 사용하는 것이 좋습니다.

Go

이 샘플을 시도하기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참조 문서를 확인하세요.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
tbl := client.Dataset(datasetID).Table(tableID)
meta, err := tbl.Metadata(ctx)
if err != nil {
	return err
}
update := bigquery.TableMetadataToUpdate{}
update.DeleteLabel("color")
if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Python

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참조 문서를 확인하세요.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('my_table')
# table = client.get_table(table_ref)  # API request

# This example table starts with one label
assert table.labels == {'color': 'green'}
# To delete a label from a table, set its value to None
table.labels['color'] = None

table = client.update_table(table, ['labels'])  # API request

assert table.labels == {}

태그 만들기

값이 빈 키가 있는 라벨은 태그로 사용됩니다. 값이 없는 새 라벨을 만들거나 기존 라벨을 태그로 만들 수 있습니다.

태그는 리소스에 라벨을 지정하는 경우 유용할 수 있지만 키:값 형식은 필요하지 않습니다. 예를 들어 여러 그룹(지원, 개발 등)이 사용하는 테스트 데이터가 포함된 테이블이 있는 경우 테이블에 test_data 태그를 추가하여 식별할 수 있습니다.

태그를 만들려면 다음 안내를 따르세요.

웹 UI

  1. 웹 UI에서 적절한 리소스(데이터세트, 테이블, 뷰)를 선택합니다.

  2. 데이터세트의 경우 데이터세트 세부정보 페이지가 자동으로 열립니다. 테이블 및 뷰의 경우 세부정보를 클릭하여 세부정보 페이지를 엽니다.

  3. 세부정보 페이지에서 라벨 오른쪽의 편집을 클릭합니다.

  4. 라벨 편집 대화 상자에서:

    • 새 키를 입력하고 값을 비워 두거나 기존 라벨의 값을 삭제합니다. 추가 태그를 적용하려면 라벨 추가를 클릭합니다.
    • 확인을 클릭합니다.

      태그 추가

명령줄

bq update 명령어를 set_label 플래그와 함께 사용합니다. 키를 지정하고 그 뒤에 콜론을 입력하고, 값을 지정하지 않고 비워 둡니다. 이는 기존 라벨을 태그로 업데이트하거나 새 태그를 추가하는 데 사용할 수 있습니다.

bq update --set_label [KEY]: [RESOURCE_ID]

각 항목의 의미는 다음과 같습니다.

  • [KEY]는 태그로 사용할 라벨 키입니다.
  • [RESOURCE_ID]는 유효한 데이터세트, 테이블 또는 뷰 이름입니다. 리소스가 기본 프로젝트 이외의 프로젝트에 있는 경우 [PROJECT_ID]:[DATASET] 형식으로 프로젝트 ID를 추가합니다.

예:

다음 명령어를 입력하여 mydataset.mytabletest_data 태그를 만듭니다. mydataset는 기본 프로젝트에 있습니다.

bq update --set_label test_data: mydataset

다음 명령어를 입력하여 mydataset의 기존 test_data:development 라벨을 태그로 변경합니다. mydataset는 기본 프로젝트가 아닌 myotherproject에 있습니다.

bq update --set_label test_data: myotherproject:mydataset

API

datasets.patch 메소드 또는 tables.patch 메소드를 호출하고 데이터세트 리소스 또는 테이블 리소스에 빈 문자열("")로 설정된 값이 있는 라벨을 추가합니다. 기존 라벨의 값을 빈 문자열로 대체하여 라벨을 태그로 만들 수 있습니다.

뷰는 테이블 리소스와 같이 취급되므로 tables.patch 메소드를 사용하여 뷰와 테이블을 모두 수정합니다. 또한 tables.update 메소드는 전체 데이터세트 리소스를 대체하므로 tables.patch 메소드를 사용하는 것이 좋습니다.

라벨 보기

BigQuery 웹 UI, 명령줄 도구의 bq show 명령어를 사용하거나 datasets.get 또는 tables.get API 메소드를 호출하여 라벨을 볼 수 있습니다. 뷰는 테이블 리소스와 같이 취급되므로 tables.get 메소드를 사용하여 뷰와 테이블의 라벨 정보를 모두 가져올 수 있습니다.

필수 권한

라벨을 보기 위해 필요한 권한은 액세스하는 리소스의 유형에 따라 다릅니다.

데이터세트 권한

데이터세트에 관한 정보를 가져오려면 데이터세트 수준의 READER 역할을 할당받거나 bigquery.datasets.get 권한이 포함된 프로젝트 수준의 IAM 역할을 할당받아야 합니다. 사전 정의된 프로젝트 수준의 모든 IAM 역할에는 bigquery.jobUser제외한 bigquery.datasets.get 권한이 포함됩니다.

또한 bigquery.user 역할을 할당받은 사용자도 bigquery.datasets.create 권한을 가지고 있습니다. 이를 통해 bigquery.user 역할을 할당받은 사용자는 사용자가 생성하는 모든 데이터세트에 대한 정보를 얻을 수 있습니다. bigquery.user 역할에 할당된 사용자가 데이터세트를 만들면 이 사용자에게 데이터세트 OWNER 액세스 권한이 부여됩니다. 데이터세트에 대한 OWNER 액세스 권한은 사용자에게 전체 제어 권한을 부여합니다.

BigQuery의 IAM 역할 및 권한에 대한 자세한 내용은 액세스 제어를 참조하세요. 데이터세트 수준 역할에 대한 자세한 내용은 데이터세트의 기본 역할을 참조하세요.

테이블 및 뷰 권한

테이블에 대한 정보를 가져오려면 데이터세트의 READER 역할을 할당받거나 bigquery.tables.get 권한이 포함된 사전 정의된 프로젝트 수준 IAM 역할을 할당받아야 합니다. 프로젝트 수준에서 bigquery.tables.get 권한을 할당받으면 프로젝트의 모든 테이블 정보를 가져올 수 있습니다. 사전 정의된 프로젝트 수준의 모든 IAM 역할에는 bigquery.userbigquery.jobUser제외한 bigquery.tables.get 권한이 포함됩니다.

또한 bigquery.user 역할을 할당받은 사용자도 bigquery.datasets.create 권한을 가지고 있습니다. 이를 통해 bigquery.user 역할을 할당받은 사용자는 사용자가 생성하는 모든 데이터세트의 테이블 및 뷰에 대한 정보를 얻을 수 있습니다. bigquery.user 역할에 할당된 사용자가 데이터세트를 만들면 이 사용자에게 데이터세트 OWNER 액세스 권한이 부여됩니다. 데이터세트에 대한 OWNER 액세스 권한이 있으면 사용자는 해당 데이터세트와 데이터세트에 포함된 모든 테이블 및 뷰를 완전히 제어할 수 있습니다.

BigQuery의 IAM 역할 및 권한에 대한 자세한 내용은 액세스 제어를 참조하세요. 데이터세트 수준 역할에 대한 자세한 내용은 데이터세트의 기본 역할을 참조하세요.

데이터세트, 테이블, 뷰 라벨 보기

리소스의 라벨을 보려면 다음 안내를 따르세요.

웹 UI

  1. 웹 UI에서 적절한 리소스(데이터세트, 테이블, 뷰)를 선택합니다.

  2. 데이터세트의 경우 데이터세트 세부정보 페이지가 자동으로 열립니다. 테이블 및 뷰의 경우 세부정보를 클릭하여 세부정보 페이지를 엽니다. 리소스 정보 테이블에 라벨 정보가 표시됩니다.

명령줄

bq show 명령어를 리소스 ID와 함께 사용합니다. --format 플래그를 사용하여 출력을 제어할 수 있습니다. 리소스가 기본 프로젝트 이외의 프로젝트에 있는 경우 [PROJECT_ID]:[DATASET] 형식으로 프로젝트 ID를 추가합니다. 읽기 편하도록 --format 플래그를 pretty로 설정하여 출력을 제어할 수 있습니다.

bq show --format=pretty [RESOURCE_ID]

여기서 [RESOURCE_ID]는 유효한 데이터세트, 테이블 또는 뷰 이름입니다.

예:

다음 명령어를 입력하여 기본 프로젝트에 있는 mydataset의 라벨을 표시합니다.

bq show --format=pretty mydataset

다음 명령어를 입력하여 mydataset.mytable의 라벨을 표시합니다. mydataset는 기본 프로젝트가 아닌 myotherproject에 있습니다.

bq show --format=pretty myotherproject:mydataset.mytable

API

datasets.get 메소드 또는 tables.get 메소드를 호출합니다. 응답에 해당 리소스와 연결된 모든 라벨이 포함됩니다.

또는 datasets.list를 사용하여 여러 데이터세트의 라벨을 보거나 tables.list를 사용하여 여러 테이블 및 뷰의 라벨을 볼 수 있습니다.

뷰는 테이블 리소스와 같이 취급되므로 tables.gettables.list 메소드를 사용하여 뷰와 테이블의 라벨 정보를 모두 볼 수 있습니다.

Go

이 샘플을 시도하기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참조 문서를 확인하세요.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
meta, err := client.Dataset(datasetID).Metadata(ctx)
if err != nil {
	return err
}
fmt.Fprintf(w, "Dataset %s labels:\n", datasetID)
if len(meta.Labels) == 0 {
	fmt.Fprintln(w, "Dataset has no labels defined.")
	return nil
}
for k, v := range meta.Labels {
	fmt.Fprintf(w, "\t%s:%s\n", k, v)
}

Python

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참조 문서를 확인하세요.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
dataset = client.get_dataset(dataset_ref)  # API request

# View dataset labels
print('Dataset ID: {}'.format(dataset_id))
print('Labels:')
if dataset.labels:
    for label, value in dataset.labels.items():
        print('\t{}: {}'.format(label, value))
else:
    print("\tDataset has no labels defined.")

라벨을 사용하여 데이터세트 필터링

라벨을 기준으로 데이터세트를 필터링하려면 bq 명령줄 도구 또는 BigQuery API에서 사용할, 다음 구문을 사용하는 필터 사양을 만듭니다.

    "field[:value][ field[:value]..."

각 항목의 의미는 다음과 같습니다.

  • fieldlabels.[KEY]로 표현되며 여기서 [KEY]는 라벨 키입니다.
  • value는 선택사항인 라벨 값입니다.

현재 필터 사양을 기준으로 테이블 또는 뷰를 나열할 수 없습니다.

제한사항

필터 사양에는 다음 제한사항이 적용됩니다.

  • AND 논리 연산자만 지원됩니다. 공백으로 구분된 비교는 암시적 AND 연산자가 있는 것으로 취급됩니다.
  • 현재 필터링에 사용 가능한 유일한 필드는 'labels.key'이며 여기서 'key'는 라벨의 이름입니다.
  • 필터에는 최대 10개의 표현식이 포함될 수 있습니다.
  • 필터링은 대소문자를 구분합니다.
  • 필터 사양을 사용하여 테이블 및 뷰를 필터링할 수 없습니다.
  • 현재 BigQuery 웹 UI를 사용하여 데이터세트를 필터링할 수 없습니다.

필터 사양 예

department:shipping 라벨이 있는 데이터세트를 나열하려면 다음 필터 사양을 사용합니다.

labels.department:shipping

여러 라벨을 사용하여 데이터세트를 나열하려면 키:값 쌍을 공백으로 구분합니다. 공백은 논리 AND 연산자로 취급됩니다. 예를 들어 department:shipping 라벨과 location:usa 라벨이 있는 데이터세트를 나열하려면 다음 필터 사양을 사용합니다.

labels.department:shipping labels.location:usa

키:값 쌍과 대조하지 않고 키 단독으로 필터링할 수 있습니다. 다음 필터 사양은 값에 관계없이 department 라벨이 지정된 모든 데이터세트를 나열합니다.

labels.department

이와 동등한 필터 사양으로, 별표를 사용하여 department 키와 연결된 가능한 모든 값을 표현하는 필터 사양이 있습니다.

labels.department:*

필터 사양에 태그를 사용할 수도 있습니다. 예를 들어 department:shipping 라벨과 test_data 라벨이 있는 데이터세트를 나열하려면 다음 필터 사양을 사용합니다.

labels.department:shipping labels.test_data

필터링된 목록 생성

필터링된 데이터세트 목록을 생성하려면 다음 안내를 따르세요.

웹 UI

현재 BigQuery 웹 UI를 사용하여 데이터세트를 필터링할 수 없습니다.

명령줄

bq ls 명령어를 --filter 플래그와 함께 실행합니다. 기본 프로젝트 이외의 다른 프로젝트에 있는 데이터세트를 나열하는 경우 --project_id 플래그를 지정합니다.

bq ls --filter "[FILTER_SPECIFICATION]" --project_id [PROJECT_ID]

각 항목의 의미는 다음과 같습니다.

  • [FILTER_SPECIFICATION]유효한 필터 사양입니다. 명령줄 도구는 필터 요구 사항을 충족하는 데이터세트 목록을 반환합니다.
  • [PROJECT_ID]는 프로젝트 ID입니다.

예:

다음 명령어를 입력하여 department:shipping 라벨이 있는 기본 프로젝트의 데이터세트를 나열할 수 있습니다.

bq ls --filter "labels.department:shipping"

다음 명령어를 입력하여 department:shipping 라벨과 test_data 태그가 있는 기본 프로젝트의 데이터세트를 나열합니다.

bq ls --filter "labels.department:shipping labels.test_data"

다음 명령어를 입력하여 department:shipping 라벨이 있는 myotherproject의 데이터세트를 나열합니다.

bq ls --filter "labels.department:shipping" --project_id myotherproject

API

datasets.list API 메소드를 호출하고 filter 속성을 사용하여 필터 사양을 제공합니다.

Go

이 샘플을 시도하기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참조 문서를 확인하세요.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
it := client.Datasets(ctx)
it.Filter = "labels.color:green"
for {
	dataset, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "dataset: %s\n", dataset.DatasetID)
}

Python

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참조 문서를 확인하세요.

# from google.cloud import bigquery
# client = bigquery.Client()

# The following label filter example will find datasets with an
# arbitrary 'color' label set to 'green'
label_filter = 'labels.color:green'
datasets = list(client.list_datasets(filter=label_filter))

if datasets:
    print('Datasets filtered by {}:'.format(label_filter))
    for dataset in datasets:  # API request(s)
        print('\t{}'.format(dataset.dataset_id))
else:
    print('No datasets found with this filter.')

다음 단계

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

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

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