독립형 탐색이라고도 하는 Knowledge Catalog (이전 명칭: Dataplex Universal Catalog) 데이터 탐색을 사용하면 Cloud Storage 버킷을 자동으로 스캔하여 메타데이터를 추출하고 테이블을 BigQuery에 게시할 수 있습니다. BigQuery 및 BigLake 테이블 게시 실패, 폴더 스키마 불일치, 스키마 변경 후 업데이트되지 않는 테이블과 같은 일반적인 탐색 스캔 오류를 해결할 수 있습니다. 자세한 내용은 Cloud Storage 데이터 탐색 및 분류를 참조하세요.
이 문서에서 다루지 않는 문제를 해결하는 데 도움이 필요하면 Cloud Customer Care에 문의하세요.
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 연결 서비스 계정에 스토리지 객체 뷰어(
roles/storage.objectViewer) 또는 Dataplex 탐색 서비스 에이전트(roles/dataplex.discoveryServiceAgent) 역할을 사용하여 Cloud Storage 버킷에 대한 읽기 액세스 권한이 있는지 확인합니다. - 연결 및 데이터 세트 위치 확인: 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_PUBLISHcom.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에서 테이블 라벨을 확인하세요.
- Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.
- 탐색기 창에서 프로젝트를 펼치고 데이터 세트를 선택한 후 영향을 받는 테이블을 클릭합니다.
- 세부정보 탭을 클릭합니다.
- 라벨 섹션에서
metadata-managed-mode키 값을 확인합니다. 탐색 스캔에서 스키마 관리 및 업데이트를 재개하려면 수정 > 세부정보 수정을 클릭하고 값을
discovery_managed로 변경한 후 저장을 클릭합니다.