2026년 4월 10일부터 Dataplex Universal Catalog가 Knowledge Catalog로 변경되었습니다. API, 클라이언트 라이브러리, CLI, IAM 이름은 변경되지 않습니다. 자세한 내용은 Google Cloud Knowledge Catalog 소개를 참조하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Databricks Unity Catalog에서 메타데이터 가져오기

Knowledge Catalog (이전의 Dataplex Universal Catalog) 커넥터를 사용하여 Databricks Unity Catalog에서 Google Cloud로 메타데이터를 직접 가져오면 데이터 사일로를 해소하고 도구 간 전환을 방지할 수 있습니다.

이 커넥터는Google Cloud, Microsoft Azure 또는 Amazon Web Services (AWS)에서 호스팅되는 Databricks Unity Catalog 인스턴스를 지원합니다.

다음 표에는 Databricks Unity Catalog 커넥터가 캡처하는 메타데이터가 나와 있습니다.

카테고리	메타데이터 캡처됨
기술	metastore 카탈로그 스키마 테이블 (관리형 Delta, 외부, 스트리밍, 온라인, 특성, Apache Iceberg REST 카탈로그 (IRC)) 뷰 (표준, 구체화) 볼륨 함수 및 프로시저
운영	사용 측정항목 (30일 및 90일 동안의 조회수, 30일 동안의 읽기, 쓰기, 빈번한 사용자, 빈번하게 조인된 테이블) 기본 키 및 외래 키
비즈니스	태그 (객체, 데이터 분류) 데이터 품질 (데이터 품질 모니터링의 이상 감지 결과, 레이크하우스 모니터링의 데이터 드리프트 및 커스텀 측정항목) 데이터 프로파일링 (Lakehouse Monitoring) 조인 및 관계 테이블 및 뷰 소유자, 생성 시간, 최종 변경 시간
시맨틱	측정항목 뷰 (측정기준, 측정, 관계 매핑, 인증) 측정항목 뷰 소유자 측정항목 뷰 사용량 (30일 및 90일 동안의 뷰, 30일 동안의 읽기, 쓰기, 빈번한 사용자, 빈번하게 조인된 테이블) 표시 이름 (측정항목 뷰에서 가져옴) 동의어 (측정항목 뷰에서) 마크다운 댓글

제한사항

Databricks Unity Catalog 커넥터에는 다음과 같은 제한사항이 있습니다.

계보는 지원되지 않습니다.
시맨틱 태그와 비즈니스 용어집은 통합(Genie API)에서 지원되지 않습니다.
커넥터는 Iceberg 테이블의 메타데이터를 가져오지만 가져온 항목을 해당 Google Cloud Lakehouse Databricks Unity Catalog Iceberg REST 카탈로그 (IRC) 항목에 자동으로 연결하지는 않습니다.

시작하기 전에

Databricks Unity Catalog에서 메타데이터를 가져오려면 먼저 다음 작업을 완료하세요.

필요한 역할 및 권한을 부여합니다.
Dataplex API 및 BigQuery Data Transfer Service API를 사용 설정합니다.
Databricks Unity Catalog 기본 요건 충족
네트워킹 기본 요건을 충족합니다.

IAM 역할 및 권한

Knowledge Catalog 커넥터 작업을 만들고 관리하려면 Knowledge Catalog 및 BigQuery Data Transfer Service에 대한 권한을 부여하는 Identity and Access Management (IAM) 역할이 필요합니다.

Databricks Unity Catalog 커넥터를 구성하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

항목 그룹 만들기 및 관리: 프로젝트에 대한 Dataplex 카탈로그 관리자(roles/dataplex.catalogAdmin), Dataplex 카탈로그 편집자(roles/dataplex.catalogEditor) 또는 Dataplex 항목 그룹 소유자(roles/dataplex.entryGroupOwner) 역할
Databricks Unity Catalog 메타데이터 보기: 프로젝트에 대한 Dataplex 카탈로그 뷰어(roles/dataplex.catalogViewer)
BigQuery Data Transfer Service 전송 작업을 만들고 관리하려면 프로젝트에 대한 BigQuery 관리자(roles/bigquery.admin) 역할이 필요합니다.
Cloud Logging에서 로그 보기: 프로젝트에 대한 로그 뷰어(roles/logging.viewer)

또한 BigQuery Data Transfer Service 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com)에 다음 두 역할을 모두 부여해야 합니다.

대상 항목 그룹 또는 이를 포함하는 프로젝트에 대한 Dataplex 항목 그룹 가져오기 도구(roles/dataplex.entryGroupImporter) 이 역할을 통해 서비스 에이전트는 메타데이터를 항목 그룹 (dataplex.entryGroups.import)으로 가져올 수 있습니다.
대상 항목 그룹이 포함된 프로젝트에 대한 Dataplex 항목 및 EntryLink 소유자(roles/dataplex.entryOwner) 이 역할을 통해 서비스 에이전트는 사용량, 비즈니스, 데이터 품질 메타데이터, 항목 링크를 가져올 수 있습니다. 여기에는 다음 권한이 포함됩니다.
- dataplex.entryGroups.useDataProfileAspect
- dataplex.entryGroups.useDataQualityScorecardAspect
- dataplex.entryGroups.useManagedConnectorTypes
- dataplex.entryGroups.useReferenceEntryLink
- dataplex.entryGroups.useSchemaAspect
- dataplex.entryGroups.useSchemaJoinAspect
- dataplex.entryGroups.useSchemaJoinEntryLink
- dataplex.entryGroups.useUsageAspect
- dataplex.entryLinks.reference
가져오기에서 프로젝트에 대한 dataplex.entryLinks.reference 권한을 확인하므로 항목 그룹뿐만 아니라 프로젝트에도 이 역할을 부여합니다. 서비스 에이전트에 프로젝트에 대한 이 권한이 없으면 전송 실행이 Permission 'dataplex.entryLinks.reference' denied과 같은 오류와 함께 실패하고 메타데이터를 가져오지 않습니다.

이러한 두 역할을 모두 부여하는 대신 대상 항목 그룹이 포함된 프로젝트에 대한 Dataplex 항목 그룹 소유자(roles/dataplex.entryGroupOwner) 역할을 부여할 수 있습니다. 이 역할에는 두 역할의 권한이 모두 포함되며 서비스 에이전트가 프로젝트의 모든 항목 그룹에 대한 액세스 권한을 만들고, 삭제하고, 관리할 수 있습니다.

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

API 사용 설정

Dataplex API 및 BigQuery Data Transfer Service API를 사용 설정합니다.

API 사용 설정

Databricks Unity Catalog 기본 요건

Databricks Unity Catalog 커넥터에 사용되는 서비스 주 구성원에게는 Databricks Unity Catalog에서 다음 권한이 있어야 합니다.

커넥터에서 사용하는 Databricks SQL 웨어하우스에 대한 Can use 권한
대상 카탈로그에 대한 BROWSE 권한 또는 대상 카탈로그, 스키마, 테이블 또는 뷰에 대한 USE CATALOG, USE SCHEMA, SELECT
system 카탈로그에 대한 USE CATALOG 및 다음 시스템 스키마에 대한 USE SCHEMA 및 SELECT:
- system.information_schema: 카탈로그, 스키마, 테이블, 열, 볼륨, 루틴, 제약 조건, 태그를 읽는 데 필요합니다.
- system.access 및 system.query: 선택사항, 사용량 측정항목, 사용량 통계, 쿼리 기록 조인을 가져오는 데 필요합니다.
- system.data_quality_monitoring: 선택사항, 이상 감지 결과를 가져오는 데 필요합니다.
선택사항: Lakehouse Monitoring 출력 테이블 (TABLE_NAME_profile_metrics 및 TABLE_NAME_drift_metrics)에 대한 USE CATALOG, USE SCHEMA, SELECT을 통해 데이터 프로파일링 및 드리프트 측정항목을 가져옵니다.

원격 Databricks 카탈로그에 대해 SQL 쿼리 또는 Spark 작업을 실행하려면 Databricks Unity Catalog에 대한 크로스 클라우드 연결 설정을 참조하세요.

네트워킹 기본 요건

BigQuery Data Transfer Service가 비공개 네트워크 내의 비공개 IP 주소를 사용하여 외부 데이터베이스 또는 서드 파티 클라우드 데이터 소스에 안전하게 연결할 수 있도록 하려면 Private Service Connect를 통해 네트워크 연결을 구성합니다.

공개 IP 주소를 사용하여 온프레미스 환경 또는 클라우드 호스팅 인스턴스에 연결하는 경우 네트워크 연결이 필요하지 않습니다.

Databricks Unity Catalog 커넥터 구성

Google Cloud 콘솔 또는 REST API를 사용하여 Databricks Unity Catalog 커넥터를 구성합니다.

콘솔

Google Cloud 콘솔에서 Knowledge Catalog 페이지로 이동합니다.

Knowledge Catalog로 이동
탐색 메뉴의 관리 섹션에서 커넥터를 클릭한 후 연결 추가를 클릭합니다.
커넥터 목록에서 Databricks Unity Catalog 카드를 선택합니다.
데이터 소스 세부정보 섹션에서 Databricks Unity Catalog 인스턴스의 연결 세부정보를 제공합니다.
- 네트워크 연결의 경우 필요한 경우 기존 네트워크 연결을 선택하거나 새로 만듭니다.
- 작업공간 호스트, SQL 웨어하우스 HTTP 경로, 클라이언트 ID, 클라이언트 보안 비밀번호를 입력합니다.
- 전송할 Databricks 객체에서 찾아보기를 클릭하여 Knowledge Catalog로 가져올 메타스토어, 카탈로그, 스키마 또는 개별 객체 (테이블, 뷰, 볼륨, 함수, 프로시져)를 선택합니다. 메타스토어, 카탈로그 또는 스키마를 선택하면 그 안에 있는 모든 객체가 가져오기됩니다.
  
  TYPE:METASTORE[/CATALOG[/SCHEMA[/OBJECT]]] 형식으로 객체를 수동으로 입력할 수도 있습니다. 여기서 TYPE는 METASTORE, CATALOG, SCHEMA, TABLE, VIEW, VOLUME, FUNCTION 또는 PROCEDURE입니다(예: SCHEMA:my_metastore/main/sales). 이름 패턴은 지원되지 않습니다.
대상 설정 섹션에서 다음을 수행합니다.
- 찾아보기를 클릭하고 가져온 메타데이터를 저장할 기존 Knowledge Catalog 항목 그룹을 선택하거나 새 항목 그룹 만들기를 클릭합니다.
- 항목 그룹에 대한 권한을 지금 설정할지 아니면 나중에 설정할지 선택합니다. 사용자가 가져온 메타데이터를 볼 수 있도록 하려면 항목 그룹에 권한을 설정합니다. 프로젝트 수준에서 BigQuery Data Transfer Service 서비스 에이전트에 Dataplex 항목 그룹 가져오기 도구(roles/dataplex.entryGroupImporter) 역할 또는 dataplex.entryGroups.import 권한을 부여하지 않은 경우 이 항목 그룹에 부여합니다. dataplex.entryLinks.reference 권한은 프로젝트 수준에서 확인되므로 프로젝트에 대한 Dataplex 항목 및 EntryLink 소유자(roles/dataplex.entryOwner) 역할을 부여해야 합니다. 자세한 내용은 IAM 역할 및 권한을 참조하세요.
전송 구성 이름 섹션의 표시 이름에 메타데이터 가져오기 작업 이름을 입력합니다.
일정 옵션 섹션에서 메타데이터 가져오기 작업의 빈도를 구성합니다. 주문형을 선택하면 수동으로 트리거할 때만 작업이 실행됩니다.
선택사항: 알림 옵션 섹션에서 작업 실패에 대한 이메일 또는 Pub/Sub 알림을 구성합니다.
(선택사항) 고급 옵션 섹션에서 암호화 설정을 구성합니다. 고객 관리 암호화 키(CMEK)를 선택하면 키가 Knowledge Catalog 메타데이터 가져오기 작업을 시작하기 전에 스테이징된 모든 임시 데이터를 암호화합니다. 키는 대상 Knowledge Catalog 항목 그룹의 메타데이터를 암호화하지 않습니다.
저장을 클릭합니다.

REST

projects.locations.transferConfigs.create 메서드를 사용합니다. TransferConfig 리소스에서 다음 필드를 구성합니다.

dataSourceId 필드를 "databricks_unity"로 설정합니다.
metadataDestination 필드에서 dataplexConfiguration.entryGroup 필드에 대상 Knowledge Catalog 항목 그룹의 리소스 경로인 projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID를 입력합니다.
params 필드에서 다음 파라미터를 설정합니다.
- connector.host (필수): Databricks 작업공간 호스트 이름 (예: dbc-a1b2345c-d6e7.cloud.databricks.com)
- connector.httpPath (필수): Databricks SQL 웨어하우스의 HTTP 경로입니다 (예: /sql/1.0/warehouses/a1b2345c67890def).
- connector.authentication.oauth.clientId (필수): Databricks OAuth 클라이언트 ID입니다.
- connector.authentication.oauth.clientSecret (필수): Databricks OAuth 클라이언트 보안 비밀번호입니다.
- connector.networkAttachment (선택사항): projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT_ID 형식의 네트워크 연결입니다.
- assets(필수): 가져올 Databricks Unity Catalog 객체 목록입니다. TYPE:METASTORE[/CATALOG[/SCHEMA[/OBJECT]]] 형식입니다(예: ["SCHEMA:my_metastore/main/sales"]).
선택사항: 전송 구성에서 OAuth 사용자 인증 정보를 제외하려면 Secret Manager에 저장합니다.
1. connector.authentication.oauth.clientSecret (원하는 경우 connector.authentication.oauth.clientId)를 projects/SECRET_PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID 형식의 보안 비밀 버전 리소스 이름으로 설정하고 해당 파라미터 이름을 paramConfig.secretManagerManagedParams 필드에 추가합니다.
2. 전송 구성(service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com)이 포함된 프로젝트의 BigQuery Data Transfer Service 서비스 에이전트에 각 보안 비밀에 대한 Secret Manager 보안 비밀 접근자(roles/secretmanager.secretAccessor) 역할을 부여합니다. 보안 비밀은 다른 프로젝트에 있을 수 있습니다. 서비스 에이전트가 보안 비밀을 읽을 수 없으면 실행이 시작되기 전에 Failed to retrieve secret ... Permission 'secretmanager.versions.access' denied와 같은 오류가 발생하여 실패합니다. BigQuery Data Transfer Service는 각 실행이 시작될 때 보안 비밀을 읽으므로 VERSION_ID를 latest로 설정하면 다음 실행부터 순환된 보안 비밀이 사용됩니다.

다음 예시에서는 TransferConfig 요청 본문을 보여줍니다.

{
  "displayName": "databricks-unity-metadata-import",
  "dataSourceId": "databricks_unity",
  "schedule": "every 24 hours",
  "params": {
    "connector.host": "dbc-a1b2345c-d6e7.cloud.databricks.com",
    "connector.httpPath": "/sql/1.0/warehouses/a1b2345c67890def",
    "connector.authentication.oauth.clientId": "CLIENT_ID",
    "connector.authentication.oauth.clientSecret": "CLIENT_SECRET",
    "assets": [
      "SCHEMA:my_metastore/main/sales"
    ]
  },
  "metadataDestination": {
    "dataplexConfiguration": {
      "entryGroup": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID"
    }
  }
}

작업은 일정에 따라 자동으로 실행되거나 수동으로 트리거할 수 있습니다.

Databricks Unity Catalog 커넥터 작업 모니터링

Google Cloud 콘솔 또는 REST API를 사용하여 Databricks Unity Catalog 커넥터 작업을 모니터링합니다.

콘솔

Google Cloud 콘솔의 커넥터 페이지에서 Databricks Unity Catalog 전송 작업의 표시 이름을 클릭합니다.
실행 기록 탭에서 세부정보 보기를 클릭하여 로그를 확인합니다.
생성된 항목을 보려면 세부정보 탭을 클릭한 후 메타데이터 대상 항목 그룹 링크를 클릭합니다.

REST

전송 구성의 실행을 나열하고 상태를 보려면 projects.locations.transferConfigs.runs.list 메서드를 사용합니다.
각 실행은 ID가 dts-run-RUN_ID인 메타데이터 가져오기 작업을 사용하여 수집된 메타데이터를 Knowledge Catalog로 가져옵니다. 생성된 항목 수와 같은 가져오기 결과를 보려면 다음 쿼리를 사용하여 Logging에서 작업 로그를 필터링합니다.
```
logName="projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fmetadata_job"
AND resource.labels.metadata_job_id="dts-run-RUN_ID"
```
Logging을 사용하지 않고 가져오기 결과를 보려면 projects/PROJECT_ID/locations/LOCATION/metadataJobs/dts-run-RUN_ID에서 projects.locations.metadataJobs.get 메서드를 호출합니다. importResult 필드에는 생성, 업데이트, 변경되지 않음, 삭제된 항목 및 항목 링크 수가 표시됩니다.

Databricks Unity Catalog 메타데이터 검색 및 보기

Google Cloud 콘솔에서 Knowledge Catalog 검색 페이지로 이동합니다.

검색 페이지로 이동
필터 패널에서 프로젝트, 시스템, 유형 별칭 섹션을 사용하여 Databricks Unity Catalog 애셋을 필터링합니다. 모든 Databricks Unity Catalog 메타데이터를 필터링하려면 시스템 섹션에서 가져온 컨텍스트를 선택한 후 관리형 커넥터 하위 섹션에서 Databricks Unity를 선택합니다.
검색창에 키워드 또는 자연어 검색어를 입력합니다. 예를 들어 키워드 검색을 통해 모든 Databricks Unity Catalog 애셋을 보려면 system=DATABRICKS를 입력합니다.

리소스 검색에 대한 자세한 내용은 Knowledge Catalog에서 리소스 검색을 참조하세요. 검색창에서 사용할 수 있는 표현식에 대한 자세한 내용은 Knowledge Catalog 검색 문법을 참조하세요.

LookupContext API를 사용하여 특정 Databricks Unity Catalog 리소스의 LLM 컨텍스트를 검색할 수도 있습니다. 자세한 내용은 데이터 애셋의 컨텍스트 검색을 참조하세요.

다음 단계

커넥터 작업 관리 방법 알아보기

Databricks Unity Catalog에서 메타데이터 가져오기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

제한사항

시작하기 전에

IAM 역할 및 권한

API 사용 설정

Databricks Unity Catalog 기본 요건

네트워킹 기본 요건

Databricks Unity Catalog 커넥터 구성

콘솔

REST

Databricks Unity Catalog 커넥터 작업 모니터링

콘솔

REST

Databricks Unity Catalog 메타데이터 검색 및 보기

다음 단계

Databricks Unity Catalog에서 메타데이터 가져오기