Knowledge Catalog 데이터 검색 문제 해결

이 가이드는 테이블 게시 실패 및 스키마 비호환성 오류를 비롯하여 Knowledge Catalog 데이터 탐색 스캔 (독립형 탐색이라고도 함)과 관련된 일반적인 문제를 해결하는 데 도움이 됩니다.

BigQuery 테이블 게시 실패 (FAILED_BIGQUERY_TABLE_PUBLISH)

탐색 스캔이 실행될 때 BigQuery에 테이블을 게시하지 못할 수 있습니다. 이 경우 스캔은 Cloud Logging에 FAILED_BIGQUERY_TABLE_PUBLISH 작업을 로깅합니다.

이 문제는 다음과 같은 조건으로 인해 발생합니다.

  • IAM 권한 부족: Knowledge Catalog 서비스 계정 또는 BigQuery 연결 서비스 계정에 연결 위임, Cloud Storage 액세스 또는 대상 데이터 세트에 쓰기하는 데 필요한 역할이 없습니다.
  • BigQuery 연결 또는 데이터 세트 불일치: 지정된 연결 ID가 잘못되었거나 연결 및 대상 데이터 세트가 서로 다른 리전에 있습니다.
  • 테이블 구성 오류: 테이블 생성 또는 수정 시 잘못되거나 지원되지 않는 설정이 적용됩니다.

이 문제를 해결하려면 다음 검사를 수행하세요.

  • 서비스 계정 역할 확인: Knowledge Catalog 서비스 계정 service-PROJECT_NUMBER@gcp-sa-dataplex. 에 Dataplex 탐색 BigLake 게시 서비스 에이전트 (roles/dataplex.discoveryBigLakePublishingServiceAgent) 역할이 있는지 확인합니다.
  • 연결 권한 확인: BigLake 테이블을 만드는 경우 BigQuery 연결 서비스 계정에 Cloud Storage 버킷에 대한 읽기 액세스 권한이 있는지 확인합니다 (roles/storage.objectViewer 또는 roles/dataplex.discoveryServiceAgent 사용).
  • 연결 및 데이터 세트 위치 확인: BigQuery 연결 및 BigQuery 데이터 세트가 동일한 리전에 있고 Cloud Storage 버킷의 위치와 호환되는지 확인합니다.
  • 세부정보를 보려면 로그 검사: Cloud Logging에서 DataScan 작업 로그를 살펴봅니다. 오류에 BigQuery: Permission denied가 포함되어 있으면 서비스 계정 권한을 확인합니다. TABLE_CONFIG가 포함되어 있으면 데이터 파일이 BigQuery 요구사항을 준수하는지 확인합니다.

대규모 Cloud Storage 버킷의 BigLake 테이블 생성 실패

탐색 스캔이 대량의 데이터 또는 대용량 개별 파일 (예: 30MB보다 큰 Avro 파일)이 포함된 Cloud Storage 버킷을 처리할 때 스캔은 BigQuery 데이터 세트를 만들 수 있지만 BigLake 테이블을 게시하지 못할 수 있습니다.

이 경우 Cloud Logging에 다음과 같은 오류가 표시될 수 있습니다.

  • FAILED_BIGQUERY_TABLE_PUBLISH
  • com.google.cloud.bigquery.BigQueryException: Read timed out

이 문제는 알려진 확장성 제한사항입니다. 테이블을 즉시 프로비저닝해야 하는 경우 버킷 데이터의 더 작은 필터링된 하위 집합을 포함하도록 탐색 스캔을 구성합니다.

Cloud Storage 폴더 스키마 불일치

데이터 탐색 스캔이 외부 테이블을 등록하지 못하거나 특정 폴더에서 파일을 감지하지 못합니다.

이 문제는 Cloud Storage 폴더에 호환되지 않는 스키마 또는 형식이 다른 파일이 포함되어 있는 경우 발생합니다. 탐색 스캔은 파일이 동일한 폴더에 있고 호환되는 스키마가 있는 경우에만 파일을 단일 테이블로 그룹화합니다.

데이터 탐색 스캔이 Cloud Storage 경로를 분석할 때 폴더 내의 파일과 폴더 간의 파티션 구조가 일관될 것으로 예상합니다. 스캔은 다음 중 하나라도 감지되면 작업을 플래그 지정합니다.

  • 잘못된 데이터 형식 (INVALID_DATA_FORMAT): 동일한 폴더 내 또는 파티션 간에 일관되지 않은 데이터 형식이 발견됩니다 (예: 동일한 디렉터리에서 .csv 및 .parquet 파일 혼합).
  • 잘못된 파티션 정의 (INVALID_PARTITION_DEFINITION): 파티션 키가 일관되지 않거나 누락되었습니다. 예를 들어 한 경로에서 Year=2023/Mon=Jan을 사용하고 다른 경로에서 Year=2023/Dept=Sales를 사용합니다.
  • 호환되지 않는 데이터 스키마 (INCOMPATIBLE_DATA_SCHEMA): 동일한 폴더 또는 테이블 내의 파일에서 일관되지 않거나 호환되지 않는 스키마가 감지됩니다.

Avro 및 Parquet과 같은 강력한 유형의 형식의 경우 스키마 불일치는 다음과 같은 이유로 발생합니다.

  • 호환되지 않는 데이터 유형: 한 파일의 열에 string 유형이 있고 다른 파일의 열에 int 또는 boolean 유형이 있습니다.
  • 기본값 누락: 스키마 정의에서 기본값을 지정하지 않고 새 파일에 새 필드가 추가되거나 삭제되어 올바른 스키마 발전을 방해합니다.
  • 손상된 파일 형식: 하나 이상의 파일이 잘못되었거나 손상되어 스캔이 스키마를 읽고 추출하지 못합니다.

이 문제를 해결하려면 파일 구조 및 스키마 정의를 확인하세요.

  • 스키마 및 형식별로 파일 구성: 단일 폴더의 모든 파일이 동일한 형식과 스키마 구조를 공유하는지 확인합니다. 별도의 테이블로 등록할 수 있도록 열, 기본 유형 또는 형식이 다른 파일을 별도의 폴더 또는 프리픽스로 이동합니다.
  • 일관된 파티션 정의 사용: 모든 파티션 폴더에서 파티션 키와 구조가 일관되도록 합니다 (예: Year=YYYY/Month=MM/을 일관되게 사용).
  • 스키마 발전 규칙 준수: 스키마를 업데이트할 때 (예: Avro 파일에서 필드 추가 또는 삭제) 탐색 서비스가 스키마 변형을 성공적으로 병합할 수 있도록 항상 기본값을 정의합니다.
  • 손상된 파일 식별: 스캔 출력 또는 로그를 확인하여 특정 파일의 디코딩이 실패하는지 확인합니다. 특정 파일로 인해 스캔이 실패하는지 확인하려면 파일을 일시적으로 이동합니다.

스키마 변경사항으로 발견된 테이블이 업데이트되지 않음

Cloud Storage에서 파일을 수정하거나 새 스캔을 실행한 후 업데이트된 스키마가 게시된 BigQuery 테이블에 반영되지 않습니다.

이 문제는 게시된 테이블에 metadata-managed-mode 라벨이 user_managed로 설정되어 있는 경우 발생합니다. 기본적으로 탐색은 테이블을 discovery_managed로 게시합니다. 사용자 또는 다른 사용자가 테이블 스키마 속성을 수동으로 수정하는 경우 자동 업데이트를 차단하려면 라벨을 user_managed로 변경해야 합니다.

이 문제를 해결하려면 BigQuery에서 테이블 라벨을 확인하세요.

  1. 콘솔에서 Google Cloud BigQuery 페이지로 이동합니다.
  2. 탐색기 창에서 프로젝트를 펼치고 데이터 세트를 선택한 후 영향을 받는 테이블을 클릭합니다.
  3. 세부정보 탭을 클릭합니다.
  4. 라벨 섹션에서 metadata-managed-mode 키의 값을 확인합니다.

  5. 탐색 스캔이 스키마 관리를 재개하고 업데이트하도록 하려면 세부정보 수정을 클릭하고 값을 discovery_managed로 변경합니다.

지원 받기

이 문서에서 다루지 않는 문제를 해결하는 데 도움이 필요하면, Cloud Customer Care에 문의하세요.