데이터 스튜디오를 BigQuery에 연결할 때 시간 초과, SQL 문법 제한, 할당량 한도 또는 VPC 서비스 제어 오류가 발생할 수 있습니다. 이 가이드에서는 BigQuery 커넥터 전반의 일반적인 문제를 설명합니다. 해결 단계를 펼쳐 문제를 조사하고 해결합니다.
쿼리 및 SQL 문법 오류
데이터 스튜디오의 맞춤 SQL 쿼리에는 특정 제한사항이 있습니다. 쿼리가 이러한 한도를 위반하면 오류가 발생할 수 있습니다.
Field is ambiguous 조인 오류
커스텀 쿼리에 중복된 열 이름이 포함된 경우 차트에 다음 오류가 표시됩니다.
User Configuration Error: Field is ambiguous
원인: 조인된 테이블(JOIN)은 중복된 열 이름을 공유할 수 없습니다. 예를 들어 Criteria_ID 필드에서 스키마가 동일한 두 테이블을 조인하면 결과 가상 테이블에 중복 열(Criteria_ID, Parent_ID, Name)이 생겨 모호성 오류가 발생합니다.
해결 단계
AS 키워드 또는 EXCEPT 절을 사용하여 모든 열 이름을 고유하게 만듭니다.
옵션 1: 별칭을 사용하여 중복된 필드의 이름을 명시적으로 바꾸기
SELECT * FROM ( SELECT Criteria_ID AS Criteria_ID_1, Parent_ID AS Parent_ID_1, Name AS NAME_1 FROM `project.dataset.table_1` ) AS table_1 LEFT JOIN ( SELECT Criteria_ID AS Criteria_ID_2, Parent_ID AS Parent_ID_2, Name AS NAME_2 FROM `project.dataset.table_2` ) AS table_2 ON table_1.Criteria_ID_1 = table_2.Criteria_ID_2;
옵션 2: EXCEPT를 사용하여 특정 필드 제외 및 이름 바꾸기
나머지 필드는 유지하면서 소수의 필드 이름만 변경해야 하는 경우 EXCEPT를 사용합니다.
SELECT * EXCEPT (city), city AS city_1 FROM `project.dataset.table_1`
커스텀 SQL 쿼리 문법 오류(여러 문)
맞춤 SQL 쿼리에 변수 또는 여러 문(DECLARE, SET)이 포함된 경우 실패합니다.
원인: 데이터 스튜디오는 외부 SELECT 쿼리(SELECT * FROM (<your_custom_sql>)) 내에서 SQL을 실행합니다. 따라서 쿼리는 단일 SELECT 문이어야 합니다.
예를 들어 다음 쿼리는 선택하기 전에 변수를 선언하므로 실패합니다.
DECLARE cost_per_tb_in_dollar FLOAT64 DEFAULT 4.2;
SELECT total_bytes_billed / (1024 * 1024) * cost_per_tb_in_dollar / (1024 * 1024) FROM `billing_table`;
해결 단계
공통 테이블 표현식(CTE 또는 WITH 절)을 사용하여 계산을 하나의 SELECT 문으로 결합합니다.
WITH constants AS ( SELECT 4.2 AS cost_per_tb_in_dollar ) SELECT total_bytes_billed / (1024 * 1024) * c.cost_per_tb_in_dollar / (1024 * 1024) AS cost FROM `billing_table`, constants AS c;
성능 및 쿼리 제한 시간
쿼리를 실행하는 데 3~5분 이상 걸리면 데이터 스튜디오에서 결과를 수신하기 전에 시간이 초과되어 HTTP 504 Gateway timeout가 반환됩니다.
HTTP 504 Gateway timeout 또는 장기 실행 쿼리 오류
데이터 스튜디오의 맞춤 쿼리 또는 복잡한 차트 집계는 3~5분 후에 제한 시간이 초과되어 HTTP 504 Gateway timeout 오류를 반환할 수 있습니다.
해결 단계
쿼리가 지속적으로 시간 초과되면 다음 최적화를 사용하세요.
- BigQuery Storage Read API 사용 설정: BigQuery Storage Read API를 사용 설정하여 데이터 처리량을 늘립니다.
- 쿼리 간소화: 불필요한 `JOIN` 명령어를 삭제하고, 더 넓은 기간으로 데이터를 그룹화하고, 필요한 열만 선택합니다.
- BigQuery BI Engine 사용: BigQuery BI Engine으로 용량을 예약하여 1초 미만의 성능을 구현합니다.
- 데이터베이스 뷰 사용: 커스텀 SQL을 BigQuery 뷰 또는 구체화된 뷰로 저장하고 데이터 스튜디오를 해당 뷰에 직접 연결합니다.
- 보고 데이터 표로 사전 집계: BigQuery에서 예약된 쿼리를 사용하여 요약 레코드를 별도의 테이블에 작성하고 요약 테이블을 쿼리합니다.
할당량 및 테이블 제한사항
데이터 세트에 수천 개의 테이블이 포함되어 있거나 수백만 개의 레코드가 반환되면 한도 오류가 발생할 수 있습니다.
테이블이 5,000개 이상인 데이터 세트의 UI 응답성 정지
데이터 스튜디오에서 테이블 선택 목록을 사용하여 BigQuery 데이터 세트에 연결하려고 하면 사용자 인터페이스가 정지되거나 응답하지 않습니다.
원인: 커넥터는 데이터 세트당 최대 5,000개의 테이블을 지원합니다. 데이터 세트가 5,000개 테이블 또는 뷰를 초과하면 테이블 선택 목록이 타임아웃되고 정지됩니다.
해결 단계
테이블 목록을 로드하지 않고 연결하려면 다음 대안 중 하나를 사용하세요.
- 맞춤 쿼리를 사용하여 연결: 맞춤 쿼리를 선택하고 덜 복잡한 `SELECT` 문을 작성합니다.
SELECT * FROM `your_project.your_dataset.your_table`
- BigQuery에서 직접 연결: BigQuery 콘솔에서 테이블을 찾고 내보내기 또는 데이터 탐색을 클릭한 후 Looker Studio로 열기를 선택합니다.
- 데이터 세트 분할 또는 재구성: 보고 데이터 표를 테이블이 5,000개 미만인 더 작은 전용 보고 데이터 세트로 이동합니다.
최대 200만 행 반환 한도
대규모 데이터 세트를 시각화할 때 차트에 데이터 잘림 경고가 표시되거나 레코드 200만 개를 초과하는 행이 생략될 수 있습니다.
원인: 커넥터는 차트 쿼리당 최대 200만 행을 반환합니다. 쿼리가 레코드 2백만 개를 초과하면 차트에서 데이터를 자르고 경고를 표시합니다.
해결 단계
데이터 잘림을 방지하려면 다음 안내를 따르세요.
- 보고서 수준 날짜 필터를 적용하여 쿼리 볼륨을 좁힙니다.
- 파티션 필터가 필요한 날짜 파티션을 나눈 테이블(`DATE`, `DATETIME`, `TIMESTAMP`)을 쿼리합니다(자세히 알아보기).
- 데이터 스튜디오에서 시각화하기 전에 BigQuery 내에서 카디널리티가 높은 측정기준을 그룹화합니다.
MEDIAN 및 PERCENTILE 분산
BigQuery에 연결된 차트에서 정확한 중앙값(MEDIAN) 또는 백분위수(PERCENTILE)를 계산하면 다른 SQL 데이터베이스 또는 CSV 내보내기에서 수행되는 동일한 계산과 출력이 약간 다를 수 있습니다.
원인: BigQuery 쿼리에서 MEDIAN 및 PERCENTILE는 APPROX_QUANTILES 근사치 집계 함수를 사용합니다. 이 기능은 페타바이트 규모의 데이터 세트를 빠르게 처리하지만, 근사치는 CSV 내보내기 또는 다른 SQL 데이터베이스에서 수행된 정확한 계산과 약간 다를 수 있습니다.
데이터 유형 및 암호화 오류
지원되지 않는 열 유형과 조직에서 시행하는 키 암호화 정책을 처리하는 방법을 알아봅니다.
CONDITION_NOT_MET 암호화 오류(CMEK)
데이터 세트를 쿼리하면 차트가 실패하고 다음 오류가 반환됩니다.
User Configuration Error: CONDITION_NOT_MET
원인: 데이터 스튜디오에서 쿼리 작업을 실행하면 BigQuery는 쿼리 결과를 결제 프로젝트의 임시 테이블에 씁니다. 결제 프로젝트의 BigQuery에 constraints/gcp.restrictNonCmekServices 조직 정책 제약 조건이 적용되는 경우 BigQuery는 임시 쿼리 결과 테이블을 포함한 모든 새 테이블에 고객 관리 암호화 키(CMEK)를 요구합니다. 커넥터는 쿼리 작업 요청에서 Cloud Key Management Service 키를 전달하지 않으므로 프로젝트 기본 Cloud KMS 키가 구성되지 않으면 쿼리가 User Configuration Error: CONDITION_NOT_MET 오류와 함께 실패합니다.
해결 단계
BigQuery에서 프로젝트 기본 Cloud KMS 키를 구성하여 BigQuery가 임시 쿼리 결과 테이블을 자동으로 암호화하도록 합니다.
- 결제 프로젝트의 BigQuery 암호화 서비스 계정에 Cloud KMS 키에 대한 Cloud KMS CryptoKey 암호화/복호화(
roles/cloudkms.cryptoKeyEncrypterDecrypter) 역할을 부여합니다. - 쿼리하는 데이터 세트의 위치에 대한 결제 프로젝트에서 프로젝트 기본 Cloud KMS 키를 설정(
region-LOCATION.default_kms_key_name)합니다. 예를 들면 다음과 같습니다.ALTER PROJECT PROJECT_ID SET OPTIONS ( `region-LOCATION.default_kms_key_name` = 'projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY' );
또는 조직 관리자와 협력하여 결제 프로젝트를 constraints/gcp.restrictNonCmekServices 정책에서 제외합니다.
TIME 데이터 유형은 지원되지 않음
TIME 데이터 유형의 열(예: 23:59:59)이 포함된 BigQuery 테이블에 연결하면 Looker Studio에서 필드를 TEXT로 변환하므로 시간 기반 정렬 또는 집계가 불가능합니다.
원인: 데이터 스튜디오는 BigQuery의 TIME 데이터 유형(예: 23:59:59)을 기본적으로 지원하지 않습니다. 커넥터는 수집 시 TIME 열을 TEXT 문자열로 변환하여 시간 기반 정렬을 방지합니다.
해결 단계
다음 해결 방법 중 하나를 사용하여 `TIME` 열을 DATETIME 객체로 변환합니다.
해결 방법 1: 커스텀 SQL 쿼리 사용
SQL에서 직접 `TIME` 필드를 기준 날짜(`1970-01-01`)와 결합합니다.
SELECT *, -- Combine a dummy date (1970-01-01) with your TIME field DATETIME(DATE "1970-01-01", your_time_field) AS time_as_datetime FROM `your_project.your_dataset.your_table`
- 결과: 데이터 스튜디오는 `time_as_datetime` 을 **날짜 및 시간** 필드로 처리합니다.
- 형식 지정: 보고서 차트 속성에서 필드의 **표시 형식** 을 **시간**, **분** 또는 맞춤 시간 형식(`h:mm:ss`)으로 변경하여 시간 부분만 표시합니다(자세히 알아보기).
해결 방법 2: 데이터 스튜디오에서 계산된 필드 만들기
SQL 쿼리를 수정하지 않는 경우 데이터 소스 내에 계산된 필드를 만듭니다.
PARSE_DATETIME("%H:%M:%S", CAST(your_time_field AS TEXT))
- 결과: `PARSE_DATETIME` 함수는 텍스트 문자열을 **날짜 및 시간** 객체로 파싱하며, 기본적으로 캘린더 날짜는 1970년 1월 1일로 설정됩니다(자세히 알아보기).
VPC 서비스 제어 오류
서비스 경계 내에서 작업할 때 액세스 거부 오류 및 백그라운드 프로세스 제한을 해결합니다.
VPN을 사용하지 않고 보고서를 볼 때 Service Control Failure
조직의 VPN 또는 회사 네트워크 외부에서 보고서를 볼 때 일부 또는 모든 차트가 다음 오류와 함께 실패합니다.
Service Control Failure
원인: 커넥터가 보고서 보기 권한 사용자의 IP 주소를 BigQuery에 전달하여 VPC 서비스 제어 IP 기반 액세스 수준을 확인합니다. 보고서를 복사하면 기본 데이터 세트가 외부에 있더라도 복사본 내의 기존 또는 '고스트' 커스텀 SQL 데이터 소스가 서비스 경계 내에서 보호되는 결제 프로젝트를 참조할 수 있습니다.
해결 단계
보고서에서 숨겨진 경계 바인딩 결제 프로젝트를 식별하고 삭제하거나 다시 할당합니다.
- 영향을 받는 보고서의 사본을 만들어 안전하게 문제를 해결합니다.
- 사본의 보고서 편집기에서 리소스 > 추가된 데이터 소스 관리로 이동합니다.
- 보고서에 연결된 모든 삽입된 **BigQuery** 또는 **커스텀 SQL** 데이터 소스를 검토합니다.
- 각 커스텀 SQL 연결을 수정하여 구성된 **결제 프로젝트**를 확인합니다. 데이터 소스가 VPC 서비스 제어 경계로 보호되는 결제 프로젝트를 가리키는 경우 보호되지 않는 결제 프로젝트를 사용하도록 업데이트하거나 더 이상 사용되지 않는 경우 데이터 소스를 삭제하세요.
VPC 서비스 제어로 보호되는 예약된 이메일 전송 또는 차트 알림 실패
VPC 서비스 제어로 보호되는 BigQuery 데이터 세트에 연결된 차트에서 자동 백그라운드 기능(예: 예약된 이메일 전송 또는 차트 알림)이 실행되면 예약된 이메일이 보고서 콘텐츠 또는 첨부파일 없이 전송되거나 알림이 실행되지 않습니다(VPC Service Controls unexpected field in error map).
원인: 자동화된 백그라운드 기능(예: 예약된 이메일 전송 또는 차트 알림)은 최종 사용자 IP 주소 없이 백그라운드 작업으로 실행되므로 VPC 서비스 제어(VPC-SC)는 IP 기반 액세스 수준(VPC Service Controls unexpected field in error map)을 평가할 때 이러한 기능을 차단합니다.
해결 단계
VPC 서비스 제어 경계 내에서 자동 백그라운드 기능을 사용하려면 서비스 계정 사용자 인증 정보를 사용하도록 데이터 소스를 구성하거나 ID 기반 액세스 수준을 만듭니다.
- 사람이 아닌 전용 인증을 구성하려면 데이터 스튜디오의 Google Cloud 서비스 계정 설정하기를 참고하세요.
- 정확한 액세스 수준 요구사항은 VPC 서비스 제어 한도를 참조하세요.