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

이 페이지에서는 라벨을 사용하여 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)
    	}
    	defer client.Close()

    	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
    }
    

Node.js

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

// Import the Google Cloud client library
    const {BigQuery} = require('@google-cloud/bigquery');
    const bigquery = new BigQuery();

    async function listDatasetsByLabel() {
      // Lists all datasets in current GCP project, filtering by label color:green.

      const options = {
        filter: 'labels.color:green',
      };
      // Lists all datasets in the specified project
      const [datasets] = await bigquery.getDatasets(options);

      console.log('Datasets:');
      datasets.forEach(dataset => console.log(dataset.id));
    }

Python

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


    from google.cloud import bigquery

    # 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.")

다음 단계