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

스키마 오류 문제 해결

이 문서는 BigQuery 테이블 스키마를 수정하거나 깊게 중첩된 스키마 구조를 정의하거나 로드할 때 발생하는 HTTP 400 Bad Request 오류를 진단하고 해결하는 데 도움이 됩니다. INFORMATION_SCHEMA 뷰를 사용하여 BigQuery 성능 문제를 해결하는 방법은 정보 스키마로 문제 해결을 참조하세요.

스키마 불일치 오류 문제 해결하기

다음 작업 중 하나가 대상 테이블의 기존 스키마와 충돌하는 스키마를 제공하면 BigQuery에서 Provided Schema does not match Table 오류(reason: invalid)를 반환합니다.

로드 작업
대상 테이블이 있는 쿼리 작업
복사 작업
ALTER TABLE DDL 문
테이블 메타데이터 업데이트 (tables.update 또는 tables.patch)

구체적인 원인과 해결 방법을 파악하려면 오류 메시지를 다음 시나리오 중 하나와 일치시킵니다.

새 스키마에 필드가 누락됨

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Field FIELD_NAME is missing in new schema

진단

다음 작업 중 하나는 대상 테이블에 이미 있는 하나 이상의 열을 생략하는 스키마 정의를 제공합니다.

로드 작업
DataFrame 쓰기 작업
tables.update 또는 tables.patch API 호출

해결 방법

BigQuery에서는 API 스키마 페이로드 또는 로드 작업 구성에서 열을 생략하여 암시적으로 열을 삭제할 수 없습니다. 이 오류를 해결하려면 다음 중 한 가지를 따르세요.

제공된 스키마에 대상 테이블의 모든 기존 열이 포함되도록 파이프라인 또는 API 요청을 업데이트하세요.
테이블에서 열을 삭제하려면 로드 또는 패치 요청에서 열을 생략하는 대신 DROP COLUMN DDL 문을 실행합니다.
```
ALTER TABLE `PROJECT_ID.DATASET.TABLE`
DROP COLUMN FIELD_NAME;
```
다음을 바꿉니다.
- PROJECT_ID: 테이블이 포함된 프로젝트의 ID입니다.
- DATASET: 테이블이 포함된 데이터 세트의 이름입니다.
- TABLE: 테이블의 이름입니다.
- FIELD_NAME: 삭제할 열의 이름입니다.

필드 유형이 변경됨

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Field FIELD_NAME has changed type from EXISTING_TYPE to NEW_TYPE

진단

요청이 로드 작업 또는 스키마 업데이트 중에 기존 열의 데이터 유형 (예: STRING에서 INT64)을 변경하려고 시도합니다.

해결 방법

이 오류를 해결하려면 다음 중 한 가지를 따르세요.

유형 변경이 지원되는 열 데이터 유형 변환(예: INT64에서 NUMERIC, INT64에서 FLOAT64, NUMERIC에서 BIGNUMERIC)인 경우 ALTER TABLE ... ALTER COLUMN DDL 문을 사용합니다.
```
ALTER TABLE `PROJECT_ID.DATASET.TABLE`
ALTER COLUMN FIELD_NAME SET DATA TYPE NEW_TYPE;
```
다음을 바꿉니다.
- PROJECT_ID: 테이블이 포함된 프로젝트의 ID입니다.
- DATASET: 테이블이 포함된 데이터 세트의 이름입니다.
- TABLE: 테이블의 이름입니다.
- FIELD_NAME: 수정할 열의 이름입니다.
- NEW_TYPE: 대상 데이터 유형입니다.
유형 변환이 제자리에서 지원되지 않는 경우 명시적 CAST 표현식으로 기존 데이터를 쿼리하고 결과를 새 테이블에 쓰거나 기존 테이블을 덮어씁니다. 자세한 내용은 열의 데이터 유형 변경을 참조하세요.

필드 모드가 변경됨

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Field FIELD_NAME has changed mode from EXISTING_MODE to NEW_MODE

진단

요청에서 지원되지 않는 열 모드 변경을 시도합니다 (예: NULLABLE를 REQUIRED로 변경하거나 REPEATED를 NULLABLE로 변경). 이 오류는 REPEATED 열이 포함된 테이블에서 REQUIRED 열을 완화할 때 bq 명령줄 도구에서 인라인 스키마 정의를 사용하는 경우에도 발생합니다. bq 명령줄 도구의 인라인 스키마 정의는 REPEATED 열이 있는 테이블 수정을 지원하지 않기 때문입니다.

해결 방법

인플레이스 BigQuery 스키마 업데이트에서 지원되는 유일한 모드 변경은 열 모드를 REQUIRED에서 NULLABLE로 완화하는 것입니다. 이 오류를 해결하려면 다음 중 한 가지를 따르세요.

열을 REQUIRED에서 NULLABLE로 완화하는 경우 GoogleSQL에서 ALTER TABLE ... ALTER COLUMN ... DROP NOT NULL DDL 문을 실행하거나 bq update 명령어 또는 tables.patch API 메서드를 사용하여 스키마를 업데이트하는 경우 JSON 스키마 파일을 제공합니다. 자세한 내용은 열 모드 변경을 참조하세요.
열의 모드를 NULLABLE에서 REQUIRED로 또는 REPEATED에서 NULLABLE로 변경하려면 업데이트된 스키마로 새 테이블을 만들고 데이터를 새 테이블에 복사하거나 로드합니다. 자세한 내용은 테이블 스키마 수정을 참조하세요.

필드를 추가할 수 없음

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Cannot add fields (field: FIELD_NAME)

진단

로드 작업 또는 쿼리 작업에 대상 테이블에 없는 열 (FIELD_NAME)이 포함되어 있으며 작업 구성에서 스키마 추가가 사용 설정되지 않았습니다.

해결 방법

로드 또는 쿼리 작업에서 스키마 추가를 사용 설정합니다.

REST API 또는 클라이언트 라이브러리에서 로드 또는 쿼리 작업 구성의 schemaUpdateOptions 속성에 ALLOW_FIELD_ADDITION를 포함합니다.
bq 명령줄 도구에서 --schema_update_option=ALLOW_FIELD_ADDITION 플래그를 전달합니다.
또는 ALTER TABLE ... ADD COLUMN를 사용하여 작업을 실행하기 전에 열을 추가합니다.

기존 스키마에 필수 필드를 추가할 수 없음

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Cannot add required fields to an existing schema. (field: FIELD_NAME)

진단

요청은 열 모드가 REQUIRED (NOT NULL)로 설정된 기존 테이블에 새 열을 추가합니다. 테이블의 기존 행은 새로 추가된 열에 대해 NULL 값을 수신하므로 BigQuery는 스키마 업데이트를 통해 REQUIRED 열을 직접 추가하는 것을 거부합니다.

해결 방법

이 오류를 해결하려면 다음 중 한 가지를 따르세요.

REQUIRED 대신 NULLABLE 모드로 새 열을 추가한 후 DML UPDATE 문을 실행하여 기존 행의 값을 채웁니다.
열을 추가하고 기본값을 할당하려면 다음 단계를 완료합니다.
1. 열을 NULLABLE 열로 추가합니다.
2. 향후 삽입 시 자동으로 값을 수신하도록 열의 기본값을 설정합니다.
3. 기존 행을 업데이트하여 기본값을 채웁니다.
```
ALTER TABLE `PROJECT_ID.DATASET.TABLE`
ADD COLUMN FIELD_NAME DATA_TYPE;

ALTER TABLE `PROJECT_ID.DATASET.TABLE`
ALTER COLUMN FIELD_NAME SET DEFAULT DEFAULT_EXPRESSION;

UPDATE `PROJECT_ID.DATASET.TABLE`
SET FIELD_NAME = DEFAULT_EXPRESSION
WHERE TRUE;
```
  다음을 바꿉니다.
  - PROJECT_ID: 테이블이 포함된 프로젝트의 ID입니다.
  - DATASET: 테이블이 포함된 데이터 세트의 이름입니다.
  - TABLE: 테이블의 이름입니다.
  - FIELD_NAME: 새 열의 이름입니다.
  - DATA_TYPE: 열의 데이터 유형입니다.
  - DEFAULT_EXPRESSION: 열의 기본값 표현식입니다.

스키마에 이미 있는 필드입니다.

오류 메시지

Field FIELD_NAME already exists in schema

진단

API 요청, JSON 스키마 파일 또는 소스 파일 헤더(예: CSV 또는 Parquet)에 제공된 스키마에 중복된 열 이름이 포함되어 있습니다. BigQuery의 열 이름은 대소문자를 구분하지 않으므로 동일한 스키마에 Field_A과 field_a을 모두 지정하면 이 오류가 트리거됩니다.

해결 방법

소스 스키마를 검사하고 대소문자를 구분하지 않는 이름 충돌을 포함하여 중복된 열 이름을 삭제하거나 이름을 바꿉니다.

필드 콜레이션 업데이트는 지원되지 않습니다.

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Invalid schema update. Updating field collation is not supported. Field FIELD_NAME has changed collation from "EXISTING_COLLATION" to "NEW_COLLATION"

진단

스키마 업데이트 중에 기존 열의 콜레이션 사양을 수정하거나 삭제할 수 없습니다. 이 오류는 일반적으로 애플리케이션이 테이블의 스키마를 가져오고, 다른 필드를 수정하고, collation 필드 속성을 보존하지 않는 이전 클라이언트 라이브러리 버전을 사용하여 스키마를 다시 작성할 때 발생합니다 ("und:ci" 대신 "" 전송).

해결 방법

이 오류를 해결하려면 다음 안내를 따르세요.

테이블 메타데이터를 읽고 패치할 때 기존 collation 속성이 유지되도록 BigQuery 클라이언트 라이브러리를 최신 버전으로 업그레이드합니다.
JSON 스키마 페이로드를 수동으로 구성하는 경우 기존 열의 collation 속성이 테이블의 현재 스키마와 일치하는지 확인합니다.

유형 매개변수 축소는 호환되지 않음

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Narrowing type parameters is not compatible

진단

ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE 문이 매개변수화된 데이터 유형의 최대 길이, 정밀도 또는 소수 자릿수를 줄이려고 시도합니다(예: STRING(100)를 STRING(50)로 변경하거나 NUMERIC(P, S) 매개변수 줄이기).

해결 방법

BigQuery에서는 기존 열에서 유형 매개변수를 확장하는 것만 허용합니다 (예: STRING(50)를 STRING(100)로 늘리기). 더 좁은 유형 매개변수를 적용하려면 더 좁은 유형 매개변수로 정의된 새 테이블을 만들고 값을 더 좁은 유형에 맞게 만드는 SELECT 쿼리를 사용하여 데이터를 새 테이블에 복사하거나 로드합니다 (예: STRING 열의 경우 LEFT(FIELD_NAME, 50)). 열의 최대 길이보다 긴 STRING 또는 BYTES 값이나 정밀도에서 허용하는 것보다 많은 자릿수의 NUMERIC 값을 작성하면 오류가 반환됩니다. NUMERIC 열의 소수 자릿수보다 소수 자릿수가 많은 값은 반올림됩니다. 자세한 내용은 테이블 스키마 수정을 참조하세요.

기본값을 사용한 필드 추가는 지원되지 않습니다.

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Add field with default value to an existing table schema is not supported; Field: FIELD_NAME. ...

진단

로드 작업 또는 tables.patch 또는 tables.update API 요청이 API 스키마 페이로드에 defaultValueExpression를 지정하면서 기존 테이블에 새 열을 추가하려고 합니다. 단일 API 스키마 업데이트에서 기존 테이블에 기본값이 있는 새 열을 추가할 수 없습니다.

해결 방법

API 요청에서 열을 추가할 때 defaultValueExpression를 지정하는 대신 열을 먼저 추가한 후 기본값을 설정합니다. 자세한 내용은 제한사항을 참조하세요.

아직 열을 추가하지 않은 경우 다음 문을 실행한 후 defaultValueExpression 없이 로드를 재개합니다.
```
ALTER TABLE `PROJECT_ID.DATASET.TABLE`
ADD COLUMN FIELD_NAME DATA_TYPE;

ALTER TABLE `PROJECT_ID.DATASET.TABLE`
ALTER COLUMN FIELD_NAME SET DEFAULT DEFAULT_EXPRESSION;

UPDATE `PROJECT_ID.DATASET.TABLE`
SET FIELD_NAME = DEFAULT_EXPRESSION
WHERE TRUE;
```
다음을 바꿉니다.
- PROJECT_ID: 테이블이 포함된 프로젝트의 ID입니다.
- DATASET: 테이블이 포함된 데이터 세트의 이름입니다.
- TABLE: 테이블의 이름입니다.
- FIELD_NAME: 새 열의 이름입니다.
- DATA_TYPE: 열의 데이터 유형입니다.
- DEFAULT_EXPRESSION: 열의 기본값 표현식입니다.
defaultValueExpression 없이 요청을 다시 제출하여 이미 열을 추가한 경우 이전 예시에서 ALTER COLUMN ... SET DEFAULT 및 UPDATE 문만 실행합니다.

기존 ID 열의 속성 업데이트는 지원되지 않습니다.

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Updating an existing identity column's attributes is not supported. Field FIELD_NAME already has identity column info.

진단

스키마 업데이트 또는 API 패치를 통해 기존 ID 열의 속성을 수정하려고 합니다.

해결 방법

ID 열 속성은 생성 후 제자리에서 수정할 수 없습니다. 스키마 업데이트 페이로드에서 기존 ID 열 정의를 변경하지 않고 유지하거나 업데이트된 ID 열 구성으로 새 테이블을 만들고 데이터를 새 테이블에 복사하거나 로드합니다. 자세한 내용은 테이블 스키마 수정을 참조하세요.

RECORD 열 내 호환되지 않는 필드 변경

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Incompatible field change within RECORD column

진단

ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE 문이 열의 기존 유형과 호환되지 않는 STRUCT 유형을 지정합니다. 예를 들어 새 유형은 하위 필드를 추가 또는 삭제하거나, 하위 필드를 지원되지 않는 유형으로 변경하거나, 하위 필드의 유형 매개변수를 좁힙니다.

해결 방법

ALTER TABLE 문의 STRUCT 유형을 열의 기존 스키마와 비교한 후 다음 중 하나를 수행합니다.

동일한 하위 필드를 동일한 순서로 유지하고 열 데이터 유형 변경에 지원되는 방식으로만 하위 필드 유형을 변경합니다.
DDL은 기존 RECORD 열에 중첩된 하위 필드를 추가할 수 없습니다. 대신 bq update 또는 tables.patch 메서드와 함께 JSON 스키마 파일을 사용하여 스키마를 업데이트합니다. 자세한 내용은 RECORD 열에 중첩 열 추가를 참조하세요.
중첩된 하위 필드를 삭제하거나 재구성하려면 중첩된 열 유형 수정을 참조하세요.

분기되는 실제 스키마의 최대 한도에 도달했습니다.

오류 메시지

Provided Schema does not match Table PROJECT_ID:DATASET.TABLE. Maximum limit on diverging physical schemas reached.

진단

열 삭제 또는 이름 변경과 같은 특정 테이블 스키마 수정 시 테이블의 API 논리적 스키마는 동일하지만 기본 물리적 스키마 표현이 다를 수 있습니다. 너무 많은 다양한 물리적 스키마 버전에 걸쳐 데이터를 대상 테이블에 복사하면 테이블 복사 작업이 이 오류와 함께 실패할 수 있습니다. 자세한 내용은 테이블 복사 제한사항을 참조하세요.

해결 방법

CREATE TABLE LIKE DDL 문을 사용하여 물리적 스키마 표현이 소스 테이블의 스키마와 일치하도록 대상 테이블을 다시 만든 다음 데이터를 복사하거나 삽입합니다.

CREATE OR REPLACE TABLE `PROJECT_ID.DATASET.DESTINATION_TABLE`
LIKE `PROJECT_ID.DATASET.SOURCE_TABLE`;

INSERT INTO `PROJECT_ID.DATASET.DESTINATION_TABLE`
SELECT * FROM `PROJECT_ID.DATASET.SOURCE_TABLE`;

다음을 바꿉니다.

PROJECT_ID: 테이블이 포함된 프로젝트의 ID입니다.
DATASET: 테이블이 포함된 데이터 세트의 이름입니다.
DESTINATION_TABLE: 다시 만들 대상 테이블의 이름입니다.
SOURCE_TABLE: 소스 테이블 이름입니다.

스키마, 파일, 루틴 중첩 한도 오류 문제 해결

BigQuery는 STRUCT (RECORD) 열, 구조화된 로드 파일, 중첩된 루틴 인수, 반환 유형에 최대 중첩 깊이 15를 적용합니다. 이 15단계 한도를 초과하면 다음 메시지 중 하나와 함께 HTTP 400 Bad Request 오류가 반환됩니다 (여기서 MAX_DEPTH 및 MAX_LEVEL는 15). 논리적 뷰 또는 영구 사용자 정의 함수 (UDF)에서 16단계 중첩 한도를 초과하여 발생하는 오류는 중첩된 뷰 또는 영구 사용자 정의 함수가 너무 많음을 참조하세요.

오류 메시지

Schema nested too deeply.
Schema nested too deeply for field FIELD_NAME, maximum allowed depth is MAX_DEPTH.
Field 'FIELD_NAME' is nested too deeply. It has definition level LEVEL while maximum allowed definition level is MAX_LEVEL.
Schema nested too deeply, at least LEVEL compared to the maximum allowed level of 15.
Routine TYPE_DESCRIPTION nested too deeply; max allowed depth: MAX_DEPTH

진단

STRUCT (RECORD) 유형의 열에는 필드가 스칼라 (NULLABLE 또는 REQUIRED)인지 배열 기반 (REPEATED)인지에 관계없이 최대 15수준의 중첩된 RECORD 필드가 포함될 수 있습니다. 마찬가지로 JSON, Parquet, Avro 로드 작업 및 외부 테이블은 중첩된 구조를 파싱할 때 중첩 한도를 적용합니다. Parquet 파일의 경우 한도는 최대 정의 수준 및 최대 반복 수준으로 표현됩니다.

루틴 오류에서 TYPE_DESCRIPTION는 중첩된 유형(argument type, return type 또는 return table type)을 식별합니다.

해결 방법

이 한도는 늘릴 수 없습니다. 이 오류를 해결하려면 다음 중 한 가지를 따르세요.

스키마 또는 루틴 유형 정의를 평탄화합니다. 테이블 스키마 또는 루틴 인수 및 반환 유형에서 깊게 중첩된 STRUCT 또는 ARRAY 계층 구조를 별도의 관련 테이블로 분할하고 쿼리 시 조인하거나 깊게 중첩된 속성을 상위 수준 열로 승격합니다.
기본 제공되는 JSON 데이터 유형을 사용합니다. 데이터에 15개 이상의 중첩 수준이 필요한 경우 깊게 중첩된 하위 트리를 JSON (또는 STRING) 유형의 열에 저장합니다. JSON 열은 테이블 스키마에 단일 열로 저장되므로 15개 수준의 RECORD 스키마 한도를 피하면서 JSON 필드 액세스 연산자와 함수를 사용하여 쿼리 시 깊게 중첩된 경로를 추출할 수 있습니다.
로드하기 전에 입력 파일을 사전 처리합니다. Cloud Storage의 JSON, Parquet 또는 Avro 파일에서 로드 작업 중에 오류가 발생하면 업스트림 전처리 단계를 추가하여 15개 수준보다 깊은 구조를 평면화하거나 직렬화한 후 BigQuery에 로드합니다.