레이크, 영역, 애셋의 메타데이터 관리

이 가이드에서는 레이크, 영역, 애셋의 Dataplex Universal Catalog 메타데이터와 Dataplex API를 사용하여 이를 관리하는 방법을 설명합니다.

주의: 레이크 및 영역 아래에 있는 Dataplex Universal Catalog 항목을 Data Catalog로 수집하는 작업(Dataplex Universal Catalog 탐색 출력으로 생성된 항목 포함)은 지원 중단되었으며 2025년 9월 30일에 작동이 중지됩니다. 탐색에서 게시한 BigQuery의 외부 테이블은 Dataplex Universal Catalog에 항목으로 수집됩니다.

개요

Dataplex Universal Catalog는 다음을 스캔합니다.

• 테이블 항목으로 테이블 메타데이터를 추출할 데이터 레이크에 있는 정형 데이터 애셋 및 반정형 데이터 애셋
• 파일 세트 메타데이터를 파일 세트 항목으로 추출할 이미지 및 텍스트와 같은 비정형 데이터

Dataplex Universal Catalog Metadata API를 사용하여 다음을 수행할 수 있습니다.

• 테이블 및 파일 세트 항목 메타데이터 보기, 수정, 삭제
• 자체 테이블 및 파일 세트 항목 메타데이터 만들기

다음을 사용하여 Dataplex Universal Catalog 메타데이터를 분석할 수 있습니다.

• 검색 및 태그 지정에 사용할 Data Catalog(지원 중단됨)
• 테이블 메타데이터 쿼리 및 분석 처리에 사용할 Dataproc Metastore 및 BigQuery

Dataplex API

이 섹션에서는 Dataplex API의 레이크, 영역, 애셋 리소스와 주요 리소스를 요약합니다.

컨트롤 플레인 API

Dataplex Universal Catalog 컨트롤 플레인 API를 사용하면 레이크, 영역, 애셋 리소스를 만들고 관리할 수 있습니다.

• 레이크: 조직 내 프로젝트 전반에서 스토리지 리소스를 관리할 수 있는 Dataplex Universal Catalog 서비스 인스턴스입니다.

• 영역: 레이크에 있는 애셋의 논리적 그룹화입니다. 레이크에 있는 영역 여러 개를 사용하여 준비 상태, 워크로드 또는 조직 구조를 기반으로 데이터를 구성합니다.

• 애셋: 레이크에 있는 영역에 연결된 Cloud Storage 버킷이나 BigQuery 데이터 세트에 저장된 데이터가 포함된 스토리지 리소스입니다.

Metadata API

Dataplex Universal Catalog Metadata API를 사용하여 테이블, 파일 세트 항목, 파티션에 있는 메타데이터를 만들고 관리합니다. Dataplex Universal Catalog는 레이크에 있거나 개발자가 제공한 데이터 애셋을 스캔하여 항목과 파티션을 만듭니다. 항목과 파티션은 연결된 애셋과 물리적 스토리지 위치에 대한 참조를 유지보수합니다.

주요 개념

테이블 항목:

잘 정의된 스키마가 포함된 정형 데이터의 메타데이터입니다. 테이블 항목은 항목 ID 및 데이터 위치별로 고유하게 식별됩니다. 테이블 항목 메타데이터는 BigQuery 및 Dataproc Metastore에서 쿼리될 수 있습니다.

• Cloud Storage 객체: Cloud Storage API를 통해 액세스하는 Cloud Storage 객체의 메타데이터입니다.
• BigQuery 테이블: BigQuery API를 통해 액세스하는 BigQuery 테이블의 메타데이터입니다.

파일 세트 항목:

일반적으로 스키마가 없는 비정형 데이터에 대한 메타데이터입니다. 파일 세트는 항목 ID 및 데이터 위치별로 고유하게 식별됩니다. 파일 세트마다 데이터 형식이 있습니다.

파티션:

키-값 쌍 및 데이터 위치 집합별로 식별되는 테이블이나 파일 세트 항목에 있는 데이터 하위 집합의 메타데이터입니다.

API 사용해 보기

Dataplex Universal Catalog lakes.zones.entities 및 lakes.zones.partitions API 참고 문서 페이지를 따라 각 API와 연결된 파라미터와 필드를 봅니다. 각 API 메서드의 참고 문서가 제공되는 API 사용해 보기 패널을 사용하여 다양한 파라미터와 필드를 통해 API 요청을 수행합니다. 사용자 인증 정보를 생성하지 않고도 요청을 구성하고 보고 제출한 후 서비스에서 반환한 응답을 볼 수 있습니다.

다음 섹션에서는 Dataplex Universal Catalog Metadata API를 이해하고 사용하는 데 도움이 되는 정보를 제공합니다.

항목

항목 나열

전체 API 정보는 lakes.zones.entities.list 문서를 참조하세요.

서비스에서 반환하는 항목 목록을 제한하려면 필터 쿼리 파라미터를 list entities 요청 URL에 추가합니다.

항목 가져오기

전체 API 정보는 lakes.zones.entities.get 문서를 참조하세요.

기본적으로 Get Entity 응답에는 기본 항목 메타데이터가 포함됩니다. 추가 스키마 메타데이터를 검색하려면 요청 URL에 뷰 쿼리 파라미터를 추가합니다.

호환성 세부정보: Dataplex Universal Catalog 메타데이터는 메타데이터 API에 중앙 집중식으로 등록되지만 BigQuery 및 Apache Hive Metastore와 호환되는 항목 테이블 메타데이터만 BigQuery 및 Dataproc Metastore에 게시됩니다. Get Entity API는 CompatibilityStatus 메시지를 반환합니다. 이 메시지는 테이블 메타데이터가 BigQuery 및 Hive Metastore와 호환되는지 여부와 호환되지 않는 경우 그 이유를 나타냅니다.

항목 업데이트

전체 API 정보는 lakes.zones.entities.update 문서를 참조하세요.

이 API를 사용하여 항목 메타데이터를 수정합니다. 여기에는 개발자나 Dataplex Universal Catalog에서 항목 메타데이터를 관리할지 여부가 포함됩니다.

• API는 모든 변경 가능한 항목 필드를 완전히 대체합니다. 다음 항목 필드는 변경 불가능하며 업데이트 요청에 이 항목 필드를 지정하면 항목 필드가 무시됩니다.
  • asset
  • dataPath
  • type
  • system
• 값이 변경되지 않더라도 모든 스키마 필드를 포함한 모든 변경 가능한 항목 필드의 값을 지정합니다.
• etag 필드를 제공합니다. 먼저 응답에서 항목의 etag를 반환하는 entities.get 요청을 제출하여 etag를 가져올 수 있습니다.
• 스키마 필드 업데이트: Dataplex Universal Catalog에서 탐색된 테이블 스키마를 업데이트하여 정확성을 향상시킬 수 있습니다.
  스키마 필드는 Google Cloud 콘솔의 Dataplex Universal Catalog 웹 인터페이스 탐색 탭에 나와 있습니다.
  • 스키마가 파일 세트이면 모든 스키마 필드를 비워 둡니다.
  • 반복 필드를 정의하려면 모드를 REPEATED로 설정합니다. 구조체 필드를 정의하려면 유형을 RECORD로 설정합니다.
  • 스키마의 userManaged 필드를 설정하여 개발자나 Dataplex Universal Catalog에서 테이블 메타데이터를 관리할지 여부를 지정할 수 있습니다. 기본 설정은 Dataplex Universal Catalog 관리입니다. userManaged가 true로 설정된 경우 EntityView가 SCHEMA 또는 FULL로 설정되면 이 설정은 entities.get 요청에서 반환되는 정보에 포함됩니다.
• 파티션 필드 업데이트:
  • Hive 이외 스타일로 파티션을 나눈 데이터의 경우 Dataplex Universal Catalog 탐색에서 파티션 키를 자동으로 생성합니다. 예를 들어 데이터 경로 gs://root/2020/12/31의 경우 파티션 키 p0, p1, p2가 생성됩니다. 더욱 직관적으로 쿼리하려면 p0, p1, p2를 각각 year, month, day로 업데이트하면 됩니다.
  • 파티션 스타일을 HIVE 스타일로 업데이트하면 파티션 필드를 변경할 수 없습니다.
• 다른 메타데이터 필드 업데이트: 자동 생성된 mimeType, CompressionFormat, CsvOptions, JsonOptions 필드를 업데이트하여 Dataplex Universal Catalog 탐색을 지원할 수 있습니다. Dataplex Universal Catalog 탐색은 다음 실행 시 새 값을 사용합니다.

항목 만들기

전체 API 정보는 lakes.zones.entities.create 문서를 참조하세요.

entities.create API를 사용하여 테이블 또는 파일 세트 메타데이터 항목을 만듭니다. 필수 및 관련 옵션 필드를 채우거나 Dataplex Universal Catalog 탐색 서비스가 옵션 필드를 채우도록 합니다.

항목 삭제

전체 API 정보는 lakes.zones.entities.delete 문서를 참조하세요.

• etag 필드를 제공합니다. 먼저 응답에서 항목의 etag를 반환하는 entities.get 요청을 제출하여 etag를 가져올 수 있습니다.

원시 데이터 영역의 테이블이나 파일 세트에 대한 기본 데이터가 삭제되면 다음 Discovery 스캔 시 테이블 또는 파일 세트 메타데이터가 자동으로 삭제됩니다. 선별 데이터 영역의 테이블에 대한 기본 데이터가 삭제되면 테이블 메타데이터는 삭제되지 않고 누락된 데이터 작업이 보고됩니다. 이 문제를 해결하려면 메타데이터 API를 통해 테이블 메타데이터 항목을 명시적으로 삭제하세요.

참고: 기본 데이터가 계속 있는 경우 테이블 삭제 함수를 선택하면 메타데이터 항목이 일시적으로 삭제됩니다. 다음 탐색을 실행하면 항목이 다시 생성됩니다.

파티션

파티션 나열

전체 API 정보는 lakes.zones.partitions.list 문서를 참조하세요.

서비스에서 반환하는 파티션 목록을 제한하려면 필터 쿼리 파라미터를 list partitions 요청 URL에 추가합니다.

예:

• ?filter="Country=US AND State=CA AND City=Sunnyvale"
• ?filter="year < 2000 AND month > 12 AND Date > 10"

파티션 가져오기

전체 API 정보는 lakes.zones.partitions.get 문서를 참조하세요.

파티션을 가져오려면 partitions/value1/value2/…./value10으로 읽도록 형식이 지정된 URL 끝에 파티션 키 값을 추가하여 요청 URL을 완성해야 합니다.

예: 파티션에 값 {Country=US, State=CA, City=Sunnyvale}이 있으면 가져오기 요청 URL은 /partitions/US/CA/Sunnyvale로 끝나야 합니다.

중요: 추가된 URL 값은 이중으로 인코딩되어야 합니다. 예를 들어 url_encode(url_encode(value))는 요청 URL이 /partitions/US%253ACA/CA%2523Sunnyvale로 끝나도록 'US:CA/CA#Sunnyvale'을 인코딩하는 데 사용될 수 있습니다. 응답의 이름 필드는 인코딩된 형식을 유지합니다.

파티션 만들기

전체 API 정보는 lakes.zones.partitions.create 문서를 참조하세요.

데이터 소스에 맞춤설정된 파티션을 만들려면 partitions.create API를 사용합니다. Cloud Storage 경로로 필수 위치 필드를 지정합니다.

파티션 키를 최대 20개까지 제공할 수 있지만 첫 키 10개만 필터링에 사용할 수 있습니다.

파티션 삭제

전체 API 정보는 lakes.zones.partitions.delete 문서를 참조하세요.

partitions/value1/value2/…./value10으로 읽도록 형식이 지정된 요청 URL 끝에 파티션 키 값을 추가하여 요청 URL을 완성합니다.

예: 파티션에 값 {Country=US, State=CA, City=Sunnyvale}이 있으면 요청 URL은 /partitions/US/CA/Sunnyvale로 끝나야 합니다.

중요: 추가된 URL 값은 RFC-1034를 준수하거나 이중으로 인코딩되어야 합니다(예: US:/CA#/Sunnyvale을 US%3A/CA%3A/Sunnyvale로 인코딩).

다음 단계

• Apache Spark에서 메타데이터에 액세스하는 방법 자세히 알아보기