从补丁 198 开始，Amazon Redshift 将不再支持创建新的 Python UDF。现有的 Python UDF 将继续正常运行至 2026 年 6 月 30 日。有关更多信息，请参阅[博客文章](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)。
# Amazon Redshift Spectrum 中的查询故障排除
本主题是您在进行 Amazon Redshift Spectrum 查询时可能遇到的常见问题的参考。
要查看 Redshift Spectrum 查询生成的错误，请查询 [SVL\$1S3LOG](r_SVL_S3LOG.md) 系统表。
**Topics**
+ [超过了重试次数](#spectrum-troubleshooting-retries-exceeded)
+ [访问受限制](#spectrum-troubleshooting-access-throttled)
+ [超出资源限制](#spectrum-troubleshooting-resource-limit-exceeded)
+ [未返回分区表的行](#spectrum-troubleshooting-no-rows-partitioned-table)
+ [未授权错误](#spectrum-troubleshooting-not-authorized-error)
+ [数据格式不兼容](#spectrum-troubleshooting-incompatible-data-format)
+ [在 Amazon Redshift 中使用 Hive DDL 时遇到语法错误](#spectrum-troubleshooting-syntax-error-using-hive-ddl)
+ [创建临时表的权限](#spectrum-troubleshooting-permission-to-create-temp-tables)
+ [范围无效](#spectrum-troubleshooting-invalid-range)
+ [Parquet 版本号无效。](#spectrum-troubleshooting-invalid-parquet-version)
+ [外部分区信息中缺少必需的字段](#spectrum-troubleshooting-required-field-missing)
## 超过了重试次数
如果 Amazon Redshift Spectrum 请求超时，将取消并重新提交请求。在 5 次重试失败之后，查询将失败并返回以下错误。
```
error: Spectrum Scan Error: Retries exceeded
```
可能的原因包括：
+ 文件大小过大 (大于 1 GB)。检查您在 Amazon S3 中的文件大小并查找大文件和文件大小偏斜。将大文件分成若干个大小在 100 MB 和 1 GB 之间的小文件。尝试使文件的大小大致相同。
+ 网络吞吐量低。稍后尝试您的查询。
## 访问受限制
Amazon Redshift Spectrum 受其他 AWS 服务的服务配额的限制。在高使用率下，Redshift Spectrum 请求可能需要降低速度，这会导致以下错误。
```
error: Spectrum Scan Error: Access throttled
```
可能存在两种类型的限制：
+ Amazon S3 限制的访问权限。
+ 访问受 AWS KMS 限制。
错误上下文提供了有关限制类型的更多详细信息。在下文中，您可以找到此限制的原因和可能的解决方案。
### Amazon S3 限制的访问权限
如果对某个[前缀](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html#keyprefix)的读取请求速率太高，Amazon S3 可能会限制 Redshift Spectrum 请求。有关您可以在 Amazon S3 中达到的 GET/HEAD 请求速率的信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[优化 Amazon S3 性能](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html)。Amazon S3 GET/HEAD 请求速率会考虑前缀上的所有 GET/HEAD 请求，因此，访问同一前缀的不同应用程序共享总请求速率。
如果 Redshift Spectrum 请求经常受到 Amazon S3 的限制，请减少 Redshift Spectrum 向 Amazon S3 发出的 Amazon S3 GET/HEAD 请求的数量。为此，请尝试将小文件合并为大文件。我们建议使用大小为 64 MB 或更大的文件。
还可以考虑对 Redshift Spectrum 表进行分区，以便从早期筛选中受益，并减少在 Amazon S3 中访问的文件数。有关更多信息，请参阅 [对 Redshift Spectrum 外部表进行分区](c-spectrum-external-tables.md#c-spectrum-external-tables-partitioning)。
### 访问受 AWS KMS 限制
如果您使用服务器端加密（SSE-S3 或 SSE-KMS）将数据存储在 Amazon S3 中，则 Amazon S3 将为 Redshift Spectrum 访问的每个文件向 AWS KMS 发起 API 操作。这些请求将计入您的加密操作配额；有关更多信息，请参阅 [AWS KMS 请求配额](https://docs.aws.amazon.com/kms/latest/developerguide/requests-per-second.html)。有关 SSE-S3 和 SSE-KMS 的更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[使用服务器端加密保护数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html)和[使用在 AWS KMS 中存储 KMS 密钥的服务器端加密保护数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html)。
减少 Redshift Spectrum 向 AWS KMS 发出的请求数的第一步是减少访问的文件数。为此，请尝试将小文件合并为大文件。我们建议使用大小为 64 MB 或更大的文件。
如果您的 Redshift Spectrum 请求经常受到 AWS KMS 的限制，请考虑请求增加加密操作的 AWS KMS 请求速率的配额。要请求提高限额，请参阅《Amazon Web Services 一般参考》**中的[AWS 服务限制](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html)。
## 超出资源限制
Redshift Spectrum 对请求可使用的内存量强制实施上限。需要更多内存的 Redshift Spectrum 请求将失败，并导致以下错误。
```
error: Spectrum Scan Error: Resource limit exceeded
```
以下两个常见原因可能会导致 Redshift Spectrum 请求超出其内存限额：
+ Redshift Spectrum 处理大量无法拆分成小型数据块的数据。
+ 大型聚合步骤由 Redshift Spectrum 处理。
我们建议使用支持拆分大小为 128 MB 或更小的并行读取的文件格式。请参阅[Amazon Redshift Spectrum 中用于查询的数据文件](c-spectrum-data-files.md)以了解支持的文件格式以及数据文件创建的通用指南。在使用不支持并行读取的文件格式或压缩算法时，我们建议将文件大小保持在 64 MB 和 128 MB 之间。
## 未返回分区表的行
如果您的查询未返回已分区外部表中的任何行，请检查是否已为此外部表添加分区。Redshift Spectrum 仅扫描位于已使用 `ALTER TABLE … ADD PARTITION` 显式添加的 Amazon S3 位置的文件。查询 [SVV\$1EXTERNAL\$1PARTITIONS](r_SVV_EXTERNAL_PARTITIONS.md) 视图以查找现有分区。为每个丢失的分区运行 `ALTER TABLE … ADD PARTITION`。
## 未授权错误
验证集群的 IAM 角色是否允许访问 Amazon S3 文件对象。如果您的外部数据库在 Amazon Athena 上，请验证 IAM 角色是否允许访问 Athena 资源。有关更多信息，请参阅 [适用于 Amazon Redshift Spectrum 的 IAM 策略](c-spectrum-iam-policies.md)。
## 数据格式不兼容
对于列式文件格式（例如 Apache Parquet）列类型嵌有数据。CREATE EXTERNAL TABLE 定义中的列类型必须与数据文件的列类型匹配。如果存在不匹配的情况，您会收到类似以下内容的错误：
```
File 'https://s3bucket/location/file has an incompatible Parquet schema
for column ‘s3://s3bucket/location.col1'. Column type: VARCHAR, Par
```
由于消息长度存在限制，错误消息可能会被截断。要检索完整的错误消息 (包括列名和列类型)，请查询 [SVL\$1S3LOG](r_SVL_S3LOG.md) 系统视图。
以下示例查询上次完成的查询的 SVL\$1S3LOG。
```
select message
from svl_s3log
where query = pg_last_query_id()
order by query,segment,slice;
```
以下是显示完整错误消息的结果的示例。
```
message
–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––-
Spectrum Scan Error. File 'https://s3bucket/location/file has an incompatible
Parquet schema for column ' s3bucket/location.col1'.
Column type: VARCHAR, Parquet schema:\noptional int64 l_orderkey [i:0 d:1 r:0]\n
```
要更正该错误，请将外部表修改为与 Parquet 文件的列类型匹配。
## 在 Amazon Redshift 中使用 Hive DDL 时遇到语法错误
对于 CREATE EXTERNAL TABLE，Amazon Redshift 支持与 Hive DDL 类似的数据定义语言 (DDL)。但是，这两种类型的 DDL 并不总是完全相同。如果您复制 Hive DDL 以创建或修改 Amazon Redshift 外部表，则可能遇到语法错误。下面是 Amazon Redshift 和 Hive DDL 之间的差别的示例：
+ Amazon Redshift 需要单引号 (')，而 Hive DDL 支持双引号 (")。
+ Amazon Redshift 不支持 STRING 数据类型。请改用 VARCHAR。
## 创建临时表的权限
要运行 Redshift Spectrum 查询，数据库用户必须有权在数据库中创建临时表。以下示例将数据库 `spectrumdb` 的临时权限授予 `spectrumusers` 用户组。
```
grant temp on database spectrumdb to group spectrumusers;
```
有关更多信息，请参阅 [GRANT](r_GRANT.md)。
## 范围无效
Redshift Spectrum 预计 Amazon S3 中属于外部表的文件在查询期间不会被覆盖。如果被覆盖，则可能会导致以下错误。
```
Error: HTTP response error code: 416 Message: InvalidRange The requested range is not satisfiable
```
为避免出现错误，请确保 Amazon S3 文件在使用 Redshift Spectrum 查询时不会被覆盖。
## Parquet 版本号无效。
Redshift Spectrum 会检查它访问的每个 Apache Parquet 文件的元数据。如果检查失败，则可能会导致与以下内容相似的错误：
```
File 'https://s3.region.amazonaws.com/s3bucket/location/file has an invalid version number
```
导致检查失败的两个常见原因如下：
+ Parquet 文件在查询过程中已被覆盖（请参阅[范围无效](#spectrum-troubleshooting-invalid-range))。
+ Parquet 文件损坏。
## 外部分区信息中缺少必需的字段
当尝试向外部目录中的外部表添加分区时，可能会收到以下错误：
```
Error: The required field () is missing from the external partition information. Add missing field in partition and retry. Partition location:
```
此错误意味着查询中使用的外部表中的分区之一缺少分区元数据信息。此错误会在以下情况下发生：
+ 您向外部目录（例如 AWS Glue Data Catalog）中的外部表添加了一个分区，其中包含部分信息。
+ 您在 Amazon Redshift 中查询了一个分区表，同时为外部目录（例如 AWS Glue Data Catalog）中的相应表添加或更新了分区。
以下是从 AWS Glue Data Catalog 中检索分区时必须填写的字段：
+ StorageDescriptor
+ InputFormat
+ OutputFormat
+ SerDeInfo
+ 值
可以查询 [SVV\$1EXTERNAL\$1PARTITIONS](r_SVV_EXTERNAL_PARTITIONS.md) 来查找现有分区并查看有关其字段的详细信息。
有关 AWS Glue Data Catalog 分区字段的完整列表，请参阅《AWS Glue Web API Reference》**中的 [Partition](https://docs.aws.amazon.com/glue/latest/webapi/API_Partition.html)。