Dataproc Metastore 관리자 인터페이스

이 페이지에서는 Dataproc Metastore 관리자 인터페이스를 사용하는 방법을 설명합니다.

관리자 인터페이스는 Dataproc 클러스터 또는 Hive 인스턴스에 연결하지 않고도 Dataproc Metastore 서비스에 저장된 메타데이터를 검사하고 관리할 수 있는 중앙 집중식 도구를 제공합니다. 대신 gcloud CLI 또는 Dataproc Metastore API를 사용하여 메타데이터를 관리할 수 있습니다.

예를 들어 관리자 인터페이스를 사용하여 백엔드 메타데이터에서 직접 SQL 쿼리를 실행하여 특정 테이블 이름을 가져올 수 있습니다. 이 프로세스에는 Dataproc 클러스터 만들기, SSH를 사용하여 클러스터에 연결, Hive 인스턴스 시작, 마지막으로 쿼리 실행(예: SELECT * FROM table_name) 등과 같은 일반적인 워크플로우보다 더 적은 단계가 포함됩니다.

따라서 관리자 인터페이스를 사용하면 시간을 절약하고 데이터를 검색하는 데 필요한 Google Cloud 리소스의 양을 줄일 수 있습니다.

시작하기 전에

필요한 역할

Dataproc Metastore 관리자 인터페이스를 사용하는 데 필요한 권한을 얻으려면 관리자에게 최소 권한의 원칙에 따라 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

Dataproc Metastore 메타데이터를 쿼리하려는 경우: 사용자 계정 또는 서비스 계정의 메타데이터 쿼리 관리자(roles/metastore.metadataQueryAdmin)
데이터베이스, 테이블, 파티션 등 메타데이터의 리소스 위치를 변경하거나 테이블을 다른 데이터베이스로 이동하려는 경우:
- 사용자 계정 또는 서비스 계정에 대한 메타데이터 변형 관리자(roles/metastore.metadataMutateAdmin)
- 사용자 계정 또는 서비스 계정에 Dataproc Metastore 편집자 역할(roles/metastore.editor)

역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 Dataproc Metastore 관리자 인터페이스를 사용하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

Dataproc Metastore 관리자 인터페이스를 사용하려면 다음 권한이 필요합니다.

Dataproc Metastore 메타데이터를 쿼리하려는 경우: metastore.services.queryMetadata
Dataproc Metastore 테이블을 변경하거나 이동하려는 경우: metastore.services.mutateMetadata

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

특정 Dataproc Metastore 역할 및 권한에 대한 자세한 내용은 Dataproc Metastore IAM 개요를 참조하세요.

지원되는 관리자 작업

관리자 인터페이스 작업은 gcloud CLI 또는 Dataproc Metastore API를 사용해서만 실행할 수 있습니다. Google Cloud 콘솔에서는 관리자 인터페이스 작업이 지원되지 않습니다.

관리자 인터페이스는 다음 작업을 지원합니다.

읽기 전용 작업.
- 쿼리 메타데이터
경고: 읽기 전용 쿼리만 대화형으로 실행합니다. 프로덕션에 중요한 프로세스에서 비대화형 읽기 전용 쿼리를 자동화하거나 실행하지 마세요. 비대화형 쿼리를 실행하면 기본 데이터베이스 스키마가 통보 없이 변경될 경우 문제가 발생할 수 있습니다.
읽기 및 쓰기 작업
- 데이터베이스, 테이블, 파티션을 포함하여 메타데이터의 리소스 위치를 변경합니다.
- 커스텀 키-값 쌍과 같은 테이블 속성을 변경합니다.
- 테이블을 다른 데이터베이스로 이동합니다.

쿼리 메타데이터

이 작업은 SQL 쿼리를 사용하여 데이터베이스에서 메타데이터 정보를 조회할 수 있게 해줍니다. 쿼리를 실행한 후 결과는 아티팩트 Google Cloud 버킷에 덤프됩니다.

이 작업을 실행하기 전 다음 고려사항을 참조하세요.

지원되는 작업에는 read-only MySQL 또는 Spanner 쿼리만 포함됩니다. 쿼리에서 데이터를 수정하려고 시도하면 작업이 실패합니다.
출력 파일에는 최대 1,000개의 행이 포함됩니다. 이 구성은 변경할 수 없습니다.
출력 파일은 자동으로 삭제되지 않습니다. 대신 Google Cloud 버킷에서 수동으로 삭제해야 합니다. 삭제하지 않으면 추가 스토리지 비용이 발생할 수 있습니다.

gcloud CLI

메타데이터를 쿼리하려면 다음 gcloud metastore services query-metadata 명령어를 실행합니다.
```
gcloud metastore services query-metadata SERVICE \
  --location=LOCATION \
  --query=QUERY
```
다음을 바꿉니다.
- SERVICE: Dataproc Metastore 서비스 이름
- LOCATION: Dataproc Metastore 서비스가 있는 Google Cloud 리전
- QUERY: 메타데이터를 타겟팅할 SQL 쿼리
  - MySQL 데이터베이스를 사용하는 경우 일반 MySQL 쿼리를 사용합니다.
  - Spanner 데이터베이스를 사용하는 경우 GoogleSQL 쿼리를 사용합니다.
아티팩트 Google Cloud 버킷에서 출력 파일을 확인합니다.

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -X POST -d '{"query": "QUERY"}' \
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:queryMetadata

다음을 바꿉니다.

QUERY: 메타데이터를 타겟팅하는 데 사용하는 SQL 쿼리
- MySQL 데이터베이스를 사용하는 경우 일반 MySQL 쿼리를 사용합니다.
- Spanner 데이터베이스를 사용하는 경우 GoogleSQL 쿼리를 사용합니다.
PROJECT_ID: Dataproc Metastore 서비스가 있는 Google Cloud 프로젝트 ID
SERVICE: Dataproc Metastore 서비스 이름
LOCATION: Dataproc Metastore가 있는 리전

다음 예시에서는 DBS라는 데이터베이스에서 select * 쿼리를 실행하는 샘플 명령어를 보여줍니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" -X POST -d  '{"query": "select * from DBS;"}' \
  https://metastore.googleapis.com/projects/dpms/locations/us-central1/services/dpms1:queryMetadata

쿼리 메타데이터 작업의 출력 해석

쿼리 메타데이터 명령어를 처음 실행하면 Dataproc Metastore가 자동으로 아티팩트 Google Cloud 버킷에 Google Cloud 폴더를 만듭니다. 이 폴더 이름은 query-results입니다. 쿼리가 성공적으로 실행될 때마다(API 호출) query-results 폴더(임의로 생성된 UUID로 이름 지정) 내에 새 폴더가 생성됩니다.

각 새 폴더에는 쿼리 결과가 포함된 result manifest 파일이 있습니다. 이 폴더의 위치는 API 호출의 응답으로 반환됩니다.

예를 들어 응답애서 resultManifestUri 필드에는 파일 위치가 포함됩니다.

"response": {
    "@type": "type.googleapis.com/google.cloud.metastore.QueryMetadataResponse",
    "resultManifestUri": "gs://gcs-bucket-6a3638b8-e319-46363-ad33-e632a5e/query-results/800156f5-2d13-4b80-bec3-2345a9e880f6/result-manifest"
  }

result manifest 파일의 출력은 다음과 비슷합니다.

{
  "status": {
    "code": 0,
    "message": "Query results are successfully uploaded to cloud storage",
    "details": []
  },
  "filenames": ["result-001"]
}

결과 매니페스트 파일 세부정보는 다음과 같습니다.

status 필드는 쿼리의 성공 또는 실패 여부를 보여줍니다.
쿼리 실행이 성공하면 filenames 필드에 생성된 모든 파일이 나열됩니다. 이 파일은 result manifest 파일과 동일한 폴더에 있습니다.
쿼리 결과에 오류가 발생한 경우 details 필드에 오류 메시지가 표시됩니다.

메타데이터의 리소스 위치 변경

이 작업을 사용하면 데이터베이스, 테이블 또는 파티션의 리소스 위치를 변경할 수 있습니다.

이 명령어를 실행하면 상위 디렉터리 또는 해당 메타데이터 리소스만 업데이트됩니다. 이 명령어는 기존 데이터를 새 위치로 전송하지 않습니다.

gcloud CLI

메타데이터의 리소스 위치를 변경하려면 다음 gcloud metastore services alter-metadata-resource-location 명령어를 실행합니다.
```
gcloud metastore services alter-metadata-resource-location SERVICE \
  --location=LOCATION \
  --resource_name=RESOURCE_NAME \
  --location_uri=LOCATION_URI
```
다음을 바꿉니다.
- SERVICE: Dataproc Metastore 서비스 이름
- LOCATION: Dataproc Metastore 서비스가 있는 Google Cloud 리전
- RESOURCE_NAME: 변경할 데이터베이스, 테이블 또는 파티션의 이름
- LOCATION_URI: RESOURCE_NAME 콘텐츠의 새 Cloud Storage 경로. 이 값은 메타데이터 리소스 위치를 이동할 경로입니다. 이 경로는 gs://로 시작해야 합니다. 예를 들면 gs://bucket/object입니다.
리소스 위치 변경이 성공했는지 확인합니다.

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"resource_name": "RESOURCE_NAME", "location_uri":"LOCATION_URI"}' \
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:alterLocation

다음을 바꿉니다.

PROJECT_ID: Dataproc Metastore 서비스가 있는 Google Cloud 프로젝트 ID
SERVICE: Dataproc Metastore 서비스 이름
LOCATION: Dataproc Metastore가 있는 리전
RESOURCE_NAME: 변경할 데이터베이스, 테이블 또는 파티션의 이름
LOCATION_URI: RESOURCE_NAME 콘텐츠의 새 Cloud Storage 경로. 이 값은 메타데이터 리소스 위치를 이동할 경로입니다. 이 경로는 gs://로 시작해야 합니다. 예를 들면 gs://bucket/object입니다.

다음 예시에서는 test-table2라는 테이블을 새 Cloud Storage 버킷으로 이동하는 샘플 명령어를 보여줍니다.

 curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -X POST -d  '{"resource_name": "databases/testdb1/tables/test-table2",
   "location_uri":"gs://gcs-bucket-dpms1-9425bd83-b794-4f1c-9e79-2d833f758cc1/empty"}'
   https://metastore.googleapis.com/projects/dpms/locations/us-central1/services/dpms1:alterLocation

테이블 속성 변경

이 작업을 사용하면 데이터를 저장하는 데 사용하는 커스텀 키-값 쌍과 같은 테이블 속성을 변경할 수 있습니다. 예를 들어 properties.customerID_1의 키-값 쌍을 properties.customerID_2로 변경할 수 있습니다.

gcloud CLI

테이블 속성을 변경하려면 다음 gcloud metastore services alter-table-properties 명령어를 실행합니다.
```
gcloud metastore services alter-table-properties SERVICE \
  --location=LOCATION \
  --table-name=TABLE_NAME \
  --update-mask=UPDATE_MASK \
  --properties=PROPERTIES
```
다음을 바꿉니다.
- SERVICE: Dataproc Metastore 서비스 이름
- LOCATION: Dataproc Metastore 서비스가 있는 Google Cloud 리전
- TABLE_NAME: 변경하려는 속성이 포함된 테이블의 이름(databases/{database_id}/tables/{table_id})
- UPDATE_MASK: 업데이트할 기존 속성 값. 쉼표로 구분된 목록을 사용하여 키-값 쌍을 설명하세요(예:properties.1,properties.2,properties.3,...).
- PROPERTIES: 테이블의 새 속성. 쉼표로 구분된 목록을 사용하여 키-값 쌍을 설명하세요. 예를 들면 a=1,b=2,c=3,...입니다. 여기에 나열한 값은 UPDATE_MASK의 값을 덮어씁니다.

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"table_name": "TABLE_NAME", "update_mask":"UPDATE_MASK", "properties":PROPERTIES}'\
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:alterTableProperties

다음을 바꿉니다.

SERVICE: Dataproc Metastore 서비스 이름
LOCATION: Dataproc Metastore 서비스가 있는 Google Cloud 리전
TABLE_NAME: 변경하려는 속성이 포함된 테이블의 이름(databases/{database_id}/tables/{table_id})
UPDATE_MASK: 업데이트할 기존 속성 값. 쉼표로 구분된 목록을 사용하여 키-값 쌍을 설명하세요(예:properties.1,properties.2,properties.3,...).
PROPERTIES: 테이블의 새 속성. 쉼표로 구분된 목록을 사용하여 키-값 쌍을 설명합니다(예:a=1,b=2,c=3,...). 여기에 나열하는 값은 UPDATE_MASK의 값을 덮어씁니다.

다음 예시에서는 test-table이라는 테이블의 테이블 속성을 변경하는 샘플 명령어를 보여줍니다. 이 예시에서는 기존 키-값 쌍 properties.customerID_1을 새 값 properties.customerID_2로 업데이트합니다.

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -X POST -d  '{"table_name": "databases/default/tables/test-table", "update_mask":{"paths":"properties.customerID_1"}, "properties":{"customerID_1":"customerID_2"}}' https://metastore.googleapis.com/projects/dpms-p

다른 데이터베이스로 테이블 이동

이 작업을 통해 내부 테이블(관리형 테이블)을 다른 데이터베이스로 이동할 수 있습니다. 이 경우 데이터베이스 상위 디렉터리와 해당 데이터가 모두 이동합니다.

외부 테이블에 저장된 데이터는 이동할 수 없습니다.

gcloud CLI

테이블을 다른 데이터베이스로 이동하려면 다음 gcloud metastore services move-table-to-database 명령어를 실행합니다.
```
gcloud metastore services move-table-to-database SERVICE \
  --location=LOCATION \
  --db_name=DB_NAME \
  --table_name=TABLE_NAME \
  --destination_db_name=DESTINATION_DB_NAME
```
다음을 바꿉니다.
- SERVICE: Dataproc Metastore 서비스 이름
- LOCATION: Dataproc Metastore 서비스가 있는 Google Cloud 리전
- DB_NAME: 이동할 테이블이 포함된 소스 데이터베이스의 이름
- TABLE_NAME: 이동할 테이블의 이름
- DESTINATION_DB_NAME: 테이블을 이동할 새 데이터베이스의 이름
테이블 변경이 성공했는지 확인하세요.

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"table_name": "TABLE_NAME", "db_name": "DB_NAME", "destination_db_name": "DESTINATION_DB_NAME"}'\
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:moveTableToDatabase

다음을 바꿉니다.

PROJECT_ID: Dataproc Metastore 서비스가 있는 Google Cloud 프로젝트 ID
SERVICE: Dataproc Metastore 서비스 이름
LOCATION: Dataproc Metastore가 있는 리전
DB_NAME: 이동할 테이블이 포함된 소스 데이터베이스의 이름
TABLE_NAME: 이동할 테이블의 이름
DESTINATION_DB_NAME: 테이블을 이동할 새 데이터베이스의 이름

다음 예시는 testdb1이라는 데이터베이스를 testdb2라는 다른 데이터베이스로 이동하는 샘플 명령어를 보여줍니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json"
 -X POST -d  '{"table_name": "testtb1", "db_name": "testdb1",
 "destination_db_name": "testdb2"}' https://metastore.googleapis.com/projects/dpms/locations/asia-northeast2/services/dpms1:moveTableToDatabase

Dataproc Metastore 관리자 인터페이스

시작하기 전에

필요한 역할

필수 권한

지원되는 관리자 작업

쿼리 메타데이터

gcloud CLI

REST

쿼리 메타데이터 작업의 출력 해석

메타데이터의 리소스 위치 변경

gcloud CLI

REST

테이블 속성 변경

gcloud CLI

REST

다른 데이터베이스로 테이블 이동

gcloud CLI

REST

다음 단계