라벨을 사용한 리소스 필터링

이 페이지에서는 라벨을 사용하여 BigQuery 리소스를 필터링하는 방법을 설명합니다.

개요

라벨을 사용하여 리소스를 필터링하려면 다음 안내를 따르세요.

  • Cloud Console 또는 기본 웹 UI에서 검색 막대를 사용합니다.
  • CLI, API, 클라이언트 라이브러리에서 사용할 필터 사양을 만듭니다.

제한사항

현재 제한사항은 다음과 같습니다.

  • API, CLI, 클라이언트 라이브러리가 데이터세트에 대해서만 필터링을 지원합니다.
  • BigQuery 도구에서는 라벨로 작업을 필터링할 수 없습니다.

필수 권한

라벨을 사용하여 리소스를 필터링하려면 리소스 메타데이터를 검색할 수 있어야 합니다. 이를 위해서는 최소한 다음 권한이 필요합니다.

  • 데이터세트를 필터링하기 위한 bigquery.datasets.get
  • 테이블 및 뷰를 필터링하기 위한 bigquery.tables.get

다음과 같은 사전 정의된 Cloud IAM 역할에는 bigquery.datasets.get 권한이 포함되어 있습니다.

  • bigquery.user
  • bigquery.metadataViewer
  • bigquery.dataViewer
  • bigquery.dataOwner
  • bigquery.dataEditor
  • bigquery.admin

다음과 같은 사전 정의된 Cloud IAM 역할에는 bigquery.tables.get 권한이 포함되어 있습니다.

  • bigquery.metadataViewer
  • bigquery.dataViewer
  • bigquery.dataOwner
  • bigquery.dataEditor
  • bigquery.admin

또한 bigquery.datasets.create 권한이 있는 사용자는 데이터세트를 만들 때 해당 데이터세트에 대한 bigquery.dataOwner 액세스 권한을 부여받습니다. bigquery.dataOwner 액세스 권한이 있으면 사용자가 자신이 만드는 리소스를 필터링할 수 있습니다.

BigQuery의 Cloud IAM 역할 및 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.

UI에서 리소스 필터링

Cloud Console 또는 기본 웹 UI를 사용하여 필터링된 리소스 목록을 생성하려면 다음 안내를 따르세요.

Console

  1. 탐색창에서 리소스 섹션을 펼칩니다.

  2. 검색창에서 key, value, key:value 쌍을 입력합니다. 결과에 부분 일치 항목이 포함됩니다.

    예를 들어 department:shipping 라벨이 있는 데이터세트만 표시하려면 다음을 입력합니다.

    • key 값: department
    • value: shipping
    • key:value 쌍: department:shipping

기본 UI

  1. 탐색창에서 Filter by ID or label(ID 또는 라벨로 필터링) 상자로 스크롤합니다. 이 상자는 프로젝트 목록 바로 위에 표시됩니다.

  2. 검색창에서 키, 값, 키-값 쌍을 입력합니다. 키-값 쌍은 key:value 형식이어야 합니다. 결과에 부분 일치 항목이 포함됩니다.

    예를 들어 department:shipping 라벨이 있는 데이터세트만 표시하려면 다음을 입력합니다.

    • key 값: department
    • value: shipping
    • key:value 쌍: department:shipping

CLI 또는 API에서 데이터세트 필터링

현재 API, CLI, 클라이언트 라이브러리가 데이터세트에 대해서만 필터링를 지원합니다.

CLI, API, 클라이언트 라이브러리를 사용하여 데이터세트를 필터링하려면 필터 사양을 만들고 사양을 다음과 같이 사용합니다.

  • CLI에서 --filter 플래그의 매개변수로 사용합니다.
  • API의 datasets.list 메서드에서 filter 속성의 값으로 사용합니다.

필터 사양 제한사항

필터 사양에는 다음과 같은 제한사항이 있습니다.

  • AND 논리 연산자만 지원됩니다. 공백으로 구분된 비교는 암시적 AND 연산자가 있는 것으로 취급됩니다.
  • 현재 필터링에 사용할 수 있는 유일한 필드는 key가 라벨 이름인 labels.key입니다.
  • 필터에는 최대 10개의 표현식이 포함될 수 있습니다.
  • 필터링은 대소문자를 구분합니다.
  • 현재 CLI, API, 클라이언트 라이브러리는 데이터세트에 대해서만 필터링을 지원합니다.

필터 사양 예시

필터 사양에는 다음 구문이 사용됩니다.

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

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

  • fieldkey가 라벨 키인 labels.key로 표시됩니다.
  • value는 선택적 라벨 값입니다.

다음 예시에서는 필터 표현식을 생성하는 방법을 보여줍니다.

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

labels.department:shipping

여러 라벨을 사용하여 리소스를 나열하려면 key:value 쌍을 공백으로 구분합니다. 공백은 논리 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

CLI 및 API에서 데이터세트 필터링

CLI, API, 클라이언트 라이브러리를 사용하여 데이터세트를 필터링하려면 다음 안내를 따르세요.

CLI

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

이러한 각 명령어의 출력은 다음과 비슷한 데이터세트 목록을 반환합니다.

+-----------+
| datasetId |
+-----------+
| mydataset |
| mydataset2|
+-----------+

API

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

Go

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// listDatasetsByLabel demonstrates walking the collection of datasets in a project, and
// filtering that list to a subset that has specific label metadata.
func listDatasetsByLabel(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}

	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)
	}
	return nil
}

Python

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

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

label_filter = "labels.color:green"
datasets = list(client.list_datasets(filter=label_filter))  # Make an API request.

if datasets:
    print("Datasets filtered by {}:".format(label_filter))
    for dataset in datasets:
        print("\t{}.{}".format(dataset.project, dataset.dataset_id))
else:
    print("No datasets found with this filter.")

다음 단계