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

라벨을 사용하여 리소스를 필터링하려면 다음 중 하나를 수행합니다.

  • Google Cloud 콘솔에서 검색창을 사용합니다.
  • API, bq 명령줄 도구, 클라이언트 라이브러리에서 사용할 필터 사양을 만듭니다.

제한사항

  • API, bq 명령줄 도구, 클라이언트 라이브러리는 데이터베이스에 대해서만 필터를 지원합니다.
  • BigQuery 도구에서는 라벨로 작업을 필터링할 수 없습니다.

시작하기 전에

사용자에게 이 문서의 각 작업을 수행하는 데 필요한 권한을 부여하는 Identity and Access Management(IAM) 역할을 부여합니다.

필수 권한

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

  • bigquery.datasets.get(데이터 세트 필터링 가능)
  • bigquery.tables.get(테이블 및 뷰를 필터링할 수 있음)

사전 정의된 다음 각 IAM 역할에는 데이터 세트를 필터링하는 데 필요한 권한이 포함되어 있습니다.

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

다음과 같은 사전 정의된 IAM 역할에는 테이블과 뷰를 필터링하는 데 필요한 권한이 포함되어 있습니다.

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

또한 bigquery.datasets.create 권한이 있으면 만드는 리소스를 필터링할 수 있습니다.

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

Google Cloud 콘솔에서 리소스 필터링

필터링된 리소스 목록을 생성하려면 Google Cloud 콘솔을 사용하세요.

  1. Google Cloud 콘솔에서 탐색기 창으로 이동합니다.

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

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

API 또는 bq 명령줄 도구에서 데이터 세트 필터링

현재 API, bq 명령줄 도구, 클라이언트 라이브러리는 데이터베이스에 대해서만 필터를 지원합니다.

API, bq 도구, 클라이언트 라이브러리를 사용하여 데이터베이스를 필터링하려면 필터 사양을 만들고 이 사양을 사용합니다.

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

필터 사양 제한사항

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

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

필터 사양 예시

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

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

다음을 바꿉니다.

  • field는 key가 라벨 키인 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

bq 명령줄 도구 및 API에서 데이터베이스 필터링

API, bq 명령줄 도구, 클라이언트 라이브러리를 사용하여 데이터베이스를 필터링하려면 다음 안내를 따르세요.

bq

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 참고 문서를 확인하세요.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 

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
}

자바

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

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 

import com.google.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

// Sample to get list of datasets by label
public class ListDatasetsByLabel {

  public static void runListDatasetsByLabel() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String filter = "MY_LABEL_FILTER";
    listDatasetsByLabel(projectId, filter);
  }

  public static void listDatasetsByLabel(String projectId, String filter) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Page<Dataset> datasets =
          bigquery.listDatasets(
              projectId,
              BigQuery.DatasetListOption.pageSize(100),
              BigQuery.DatasetListOption.labelFilter(filter)); // "labels.color:green"
      if (datasets == null) {
        System.out.println("Dataset does not contain any models");
        return;
      }
      datasets
          .iterateAll()
          .forEach(
              dataset -> System.out.printf("Success! Dataset ID: %s ", dataset.getDatasetId()));
    } catch (BigQueryException e) {
      System.out.println("Project does not contain any datasets \n" + e.toString());
    }
  }
}

Node.js

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

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 

// 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 참고 문서를 확인하세요.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 


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

다음 단계