本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Athena 引擎版本 3 Athena 引擎版本 3 也仍然採用持續整合方法，管理開放原始碼軟體，提高 [Trino](https://trino.io/) 和 [Presto](https://prestodb.io/) 專案的並行數，讓您可以更快速地使用到各種改善後的社群功能，並在 Athena 引擎中執行整合和調整。此次推出的 Athena 引擎版本 3 支援先前的引擎版本的所有功能。本文件會重點說明先前的引擎版本與 Athena 引擎版本 3 之間的主要差異。如需詳細資訊，請參閱 *AWS 大數據部落格*文章「[升級至 Athena 引擎版本 3，以提升查詢效能並存取更多分析功能](https://aws.amazon.com/blogs/big-data/upgrade-to-athena-engine-version-3-to-increase-query-performance-and-access-more-analytics-features/)」。 + [開始使用](#engine-versions-reference-0003-getting-started) + [改善和新功能](#engine-versions-reference-0003-improvements-and-new-features) + [新增功能](#engine-versions-reference-0003-added-features) + [新增的函數](#engine-versions-reference-0003-added-functions) + [效能改進](#engine-versions-reference-0003-performance-improvements) + [可靠性增強功能](#engine-versions-reference-0003-reliability-enhancements) + [查詢語法增強功能](#engine-versions-reference-0003-query-syntax-enhancements) + [資料格式和資料類型增強功能](#engine-versions-reference-0003-data-format-and-data-type-enhancements) + [突破性變更](#engine-versions-reference-0003-breaking-changes) + [查詢語法變更](#engine-versions-reference-0003-syntax-changes) + [資料處理變更](#engine-versions-reference-0003-data-processing-changes) + [時間戳記變更](#engine-versions-reference-0003-timestamp-changes) + [限制](#engine-versions-reference-0003-known-limitations) ## 開始使用若要開始使用，請建立使用 Athena 引擎版本 3 的新 Athena 工作群組，或將現有工作群組設定為使用版本 3。如需詳細資訊，請參閱[變更 Athena 引擎版本](https://docs.aws.amazon.com/athena/latest/ug/engine-versions-changing.html)。 ## 改善和新功能所列之功能和更新內容包括 Athena 本身的功能改進，以及從開放原始碼 Trino 整合的功能改進。如需有關 SQL 查詢運算子和函數的詳盡清單，請參閱 [Trino 文件](https://trino.io/docs/current/functions.html)。 ### 新增功能 #### Apache Spark 歸納演算法支援 Athena 可讀取 Spark 雜湊演算法產生的儲存貯體。若要指定最初由 Spark 雜湊演算法撰寫該資料，請將 `('bucketing_format'='spark')` 放入 `CREATE TABLE` 陳述式的 `TBLPROPERTIES` 子句中。若未指定此屬性，則系統會使用 Hive 雜湊演算法。 ``` CREATE EXTERNAL TABLE `spark_bucket_table`( `id` int, `name` string ) CLUSTERED BY (`name`) INTO 8 BUCKETS STORED AS PARQUET LOCATION 's3://amzn-s3-demo-bucket/to/bucketed/table/' TBLPROPERTIES ('bucketing_format'='spark') ``` ### 新增的函數本節中的函數是 Athena 引擎版本 3 中新增的函數。 #### 彙總函數 **listagg(x, separator)** – 傳回串連的輸入值，由分隔符號字串分開。 ``` SELECT listagg(value, ',') WITHIN GROUP (ORDER BY value) csv_value FROM (VALUES 'a', 'c', 'b') t(value); ``` #### 陣列函數 **contains\$1sequence(x, seq)** – 如果陣列 x 包含所有陣列序列，並作為循序子集 (相同連續順序中的所有值)，則會傳回 true。 ``` SELECT contains_sequence(ARRAY [1,2,3,4,5,6], ARRAY[1,2]); ``` #### 二進位函數 **murmur3(binary)** – 計算二進位的 128 位元 MurmurHash3 雜湊。 ``` SELECT murmur3(from_base64('aaaaaa')); ``` #### 轉換函數 **format\$1number(number)** – 傳回使用單位符號的格式化字串。 ``` SELECT format_number(123456); -- '123K' ``` ``` SELECT format_number(1000000); -- '1M' ``` #### 日期和時間函數 **timezone\$1hour(timestamp)** – 傳回與時間戳記偏離的時區小時數。 ``` SELECT EXTRACT(TIMEZONE_HOUR FROM TIMESTAMP '2020-05-10 12:34:56 +08:35'); ``` **timezone\$1minute(timestamp)** – 傳回與時間戳記偏離的時區分鐘數。 ``` SELECT EXTRACT(TIMEZONE_MINUTE FROM TIMESTAMP '2020-05-10 12:34:56 +08:35'); ``` #### 地理空間函數 **to\$1encoded\$1polyline(Geometry)** – 將 linestring 或 multipoint 編碼為 polyline。 ``` SELECT to_encoded_polyline(ST_GeometryFromText( 'LINESTRING (-120.2 38.5, -120.95 40.7, -126.453 43.252)')); ``` **from\$1encoded\$1polyline(varchar)** – 將 polyline 解碼為 linestring。 ``` SELECT ST_AsText(from_encoded_polyline('_p~iF~ps|U_ulLnnqC_mqNvxq`@')); ``` **to\$1geojson\$1geometry(SphericalGeography)** – 以 GeoJSON 格式傳回指定的球形地理資訊。 ``` SELECT to_geojson_geometry(to_spherical_geography(ST_GeometryFromText( 'LINESTRING (0 0, 1 2, 3 4)'))); ``` **from\$1geojson\$1geometry(varchar)** – 以 GeoJSON 表示法傳回剝離非幾何鍵/值的球形地理類型物件。不支援 `Feature` 和 `FeatureCollection`。 ``` SELECT from_geojson_geometry(to_geojson_geometry(to_spherical_geography(ST_GeometryFromText( 'LINESTRING (0 0, 1 2, 3 4)')))); ``` **geometry\$1nearest\$1points(Geometry, Geometry)** – 傳回每個幾何形狀上互相最近的點。如果任一幾何形狀為空，則會傳回 NULL。否則，便會傳回由兩個 `Point` 物件組成的資料列，這兩個物件與幾何形狀上任兩點的距離為最小距離。第一個點來自第一個 Geometry 引數，第二個點來自第二個 Geometry 引數。如果有多個具有相同最小距離的配對，則會任意選擇一對。 ``` SELECT geometry_nearest_points(ST_GeometryFromText( 'LINESTRING (50 100, 50 200)'), ST_GeometryFromText( 'LINESTRING (10 10, 20 20)')); ``` #### Set Digest 函數 **make\$1set\$1digest(x)** – 將 x 的所有輸入值撰寫成一個 Setdigest。 ``` SELECT make_set_digest(value) FROM (VALUES 1, 2, 3) T(value); ``` #### 字串函數 **soundex(char)** – 傳回包含字元音標表示法的字元串。 ``` SELECT name FROM nation WHERE SOUNDEX(name) = SOUNDEX('CHYNA'); -- CHINA ``` **concat\$1ws(string0, string1, ..., stringN)** – 傳回串連的 `string1, string2, ..., stringN` (使用 `string0` 作分隔符號)。如果 `string0` 為 NULL，則傳回值為 NULL。系統會略過在分隔符號後以引數方式提供的任何 Null 值。 ``` SELECT concat_ws(',', 'def', 'pqr', 'mno'); ``` #### 範圍函數 **GROUPS** – 新增對群組型範圍框的支援。 ``` SELECT array_agg(a) OVER( ORDER BY a ASC NULLS FIRST GROUPS BETWEEN 1 PRECEDING AND 2 FOLLOWING) FROM (VALUES 3, 3, 3, 2, 2, 1, null, null) T(a); ``` ### 效能改進 Athena 引擎版本 3 的效能改進包含以下內容。 + **更快速的 AWS Glue 資料表中繼資料擷取** – 涉及多個資料表的查詢將縮短查詢規劃時間。 + **RIGHT JOIN 的動態篩選** – 現可針對具有相等聯結條件的右端聯結啟用動態篩選，如以下範例所示。 ``` SELECT * FROM lineitem RIGHT JOIN tpch.tiny.supplier ON lineitem.suppkey = supplier.suppkey WHERE supplier.name = 'abc'; ``` + **大型預備陳述式** – 預設 HTTP 請求/回應標頭大小已增加至 2 MB，以允許使用大型預備陳述式。 + **approx\$1percentile()** – `approx_percentile` 函數現在使用 `tdigest` 而不是 `qdigest` 來從分佈擷取近似分位數值。這會導致更高的效能以及更低的記憶體使用量。請注意，由於此變更，函式傳回的結果與先前的引擎版本中的結果不同。如需詳細資訊，請參閱[approx\$1percentile 函數會傳回不同的結果](#engine-versions-reference-0003-approx-percentile-function)。 ### 可靠性增強功能 Athena 引擎版本 3 的一般引擎記憶體用量和追蹤功能已改進。大型查詢較不易因節點當機而失敗。 ### 查詢語法增強功能 **INTERSECT ALL** – 已新增對 `INTERSECT ALL` 的支援。 ``` SELECT * FROM (VALUES 1, 2, 3, 4) INTERSECT ALL SELECT * FROM (VALUES 3, 4); ``` **EXCEPT ALL** – 已新增對 `EXCEPT ALL` 的支援。 ``` SELECT * FROM (VALUES 1, 2, 3, 4) EXCEPT ALL SELECT * FROM (VALUES 3, 4); ``` **RANGE PRECEDING** – 已新增對範圍函數中 `RANGE PRECEDING` 的支援。 ``` SELECT sum(x) over (order by x range 1 preceding) FROM (values (1), (1), (2), (2)) t(x); ``` **MATCH\$1RECOGNIZE** – 已新增對資料列模式比對的支援，如以下範例所示。 ``` SELECT m.id AS row_id, m.match, m.val, m.label FROM (VALUES(1, 90),(2, 80),(3, 70),(4, 70)) t(id, value) MATCH_RECOGNIZE ( ORDER BY id MEASURES match_number() AS match, RUNNING LAST(value) AS val, classifier() AS label ALL ROWS PER MATCH AFTER MATCH SKIP PAST LAST ROW PATTERN (() | A) DEFINE A AS true ) AS m; ``` ### 資料格式和資料類型增強功能 Athena 引擎版本 3 具有以下資料格式和資料類型增強功能。 + **LZ4 和 ZSTD** – 已新增對讀取 LZ4 和 ZSTD 壓縮 Parquet 資料的支援。已新增對寫入 ZSTD 壓縮 ORC 資料的支援。 + **符號連結型資料表** – 已新增對在 Avro 檔案上建立符號連結型資料表的支援。範例如下。 ``` CREATE TABLE test_avro_symlink ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.avro.AvroSerDe' ... INPUTFORMAT 'org.apache.hadoop.hive.ql.io.SymlinkTextInputFormat' ``` + **SphericalGeography** – SphericalGeography 類型對地理座標 (有時稱為測地座標、緯度/經度或緯度/經度) 上所表示的空間特徵提供原生支援。地理座標是以角度單位 (度) 來表示的球面座標。 `to_spherical_geography` 函數會從幾何 (平面) 座標傳回地理 (球形) 座標，如以下範例所示。 ``` SELECT to_spherical_geography(ST_GeometryFromText( 'LINESTRING (-40.2 28.9, -40.2 31.9, -37.2 31.9)')); ``` ## 突破性變更從先前的引擎版本移轉至 Athena 引擎版本 3 時，特定變更可能會影響資料表結構描述、語法或資料類型用量。本節會列出相關的錯誤訊息，並提供建議的因應措施。 ### 查詢語法變更 #### IGNORE NULLS 不能與非值視窗函數一起使用 **錯誤訊息**：無法為 `bool_or` 函數指定 Null 處理方式子句。 **原因**：`IGNORE NULLS` 現在只能與[值函數](https://trino.io/docs/current/functions/window.html#value-functions) `first_value`、`last_value`、`nth_value`、`lead` 和 `lag` 一起使用。此變更之目的是符合 ANSI SQL 規格。 **建議的解決方案**：從查詢字符串中的非值視窗函數中移除 `IGNORE NULLS`。 #### CONCAT 函數必須有兩個或多個引數 **錯誤信息**：INVALID\$1FUNCTION\$1ARGUMENT: There must be two or more concatenation arguments (NVALID\$1FUNCTION\$1ARGUMENT：必須有兩個或多個串聯參數) **原因**：先前，`CONCAT` 字串函數接受了單一引數。在 Athena 引擎版本 3 中，`CONCAT` 函數需要至少兩個引數。 **建議的解決方案**：將出現次數從 `CONCAT(str)` 變更為 `CONCAT(str, '')`。在 Athena 引擎版本 3 中，函數中不可超過 127 個引數。如需詳細資訊，請參閱[函數呼叫的引數過多](troubleshooting-athena.md#troubleshooting-athena-too-many-arguments)。 #### approx\$1percentile 函數會傳回不同的結果 `approx_percentile` 函式會在 Athena 引擎版本 3 中傳回的結果與先前的引擎版本中傳回的結果不同。 **錯誤訊息**：無。 **原因**：`approx_percentile` 函數可能因版本變更而變更。 **重要** 由於 `approx_percentile` 函數的輸出是近似值，並且近似值可能會從一個版本變更為下一個版本，因此關鍵應用程式不得倚賴 `approx_percentile` 函數。 **建議的解決方案**：若要將先前的引擎版本行為估算為 `approx_percentile`，您可以在 Athena 引擎版本 3 中使用不同的函式組。例如，假設您在先前的引擎版本中有下列查詢： ``` SELECT approx_percentile(somecol, 2E-1) ``` 若要估計 Athena 引擎版本 3 中的相同輸出，您可以嘗試使用 `qdigest_agg` 和 `value_at_quantile` 函數，如下列範例所示。請注意，即使使用此解決方法，也不能保證行為相同。 ``` SELECT value_at_quantile(qdigest_agg(somecol, 1), 2E-1) ``` #### 地理空間函數不支援 varbinary 輸入 **錯誤訊息**：FUNCTION\$1NOT\$1FOUND for st\$1XXX **原因**：一些地理空間函數不再支援舊版 `VARBINARY` 輸入類型或與文字相關的函數簽章。 **建議的解決方案**：使用地理空間函數將輸入類型轉換為受支援的類型。錯誤訊息會指出受支援的輸入類型。 #### 在 GROUP BY 子句中，巢狀資料欄必須使用雙引號 **錯誤訊息**："*column\$1name*"."*nested\$1column*" 必須是彙總表達式，或出現在 GROUP BY 子句中 **原因**：Athena 引擎版本 3 要求 `GROUP BY` 子句中的巢狀資料欄名稱必須加上雙引號。例如，下列查詢會產生錯誤，因為在 `GROUP BY` 子句中，`user.name` 未使用雙引號。 ``` SELECT "user"."name" FROM dataset GROUP BY user.name ``` **建議的解決方案**：在 `GROUP BY` 子句中的巢狀資料欄名稱周圍使用雙引號，如下列範例所示。 ``` SELECT "user"."name" FROM dataset GROUP BY "user"."name" ``` #### 在 Iceberg 資料表上使用 OPTIMIZE 時發生未預期的 FilterNode 錯誤 **錯誤訊息**：計畫中發現未預期的 FilterNode；可能是連接器無法處理提供的 WHERE 表達式。 **原因**：在 Iceberg 資料表上執行的 `OPTIMIZE` 陳述式使用了 `WHERE` 子句，其中該子句在其篩選條件表達式中包含了非分割區資料欄。 **建議的解決方案**：`OPTIMIZE` 陳述式僅支援依分割區來進行篩選。當您在已分割的資料表上執行 `OPTIMIZE` 時，請在 `WHERE` 子句中僅包含分割區資料欄。如果您在未分割的資料表上執行 `OPTIMIZE`，請勿指定 `WHERE` 子句。 #### Log() 函數引數的順序在 Athena 引擎版本 3 中，`log()` 函式的引數順序已變更為 `log(base, value)`，以符合 SQL 標準。 #### Minute() 函數不支援 interval year to month **錯誤訊息**：Unexpected parameters (interval year to month) for function minute.(Minute 函數的意外參數 (間隔使用年份和月份)。) Expected: minute(timestamp with time zone) , minute(time with time zone) , minute(timestamp) , minute(time) , minute(interval day to second). (函數 minute 出現未預期參數 (interval year to month)。預期：minute(timestamp with time zone)、minute(time with time zone)、minute(timestamp)、minute(time)、minute(interval day to second)。) **原因**：在 Athena 引擎版本 3 中，已依據 ANSI SQL 規格，更精確地為 `EXTRACT` 執行類型檢查。 **建議的解決方案**：更新查詢，以確保類型與建議的函數簽章相符。 #### ORDER BY 表達式必須出現在 SELECT 清單中。 **錯誤訊息**：For SELECT DISTINCT, ORDER BY expressions must appear in SELECT list (若為 SELECT DISTINCT，ORDER BY 表達式必須出現在 SELECT 清單中) **原因**：`SELECT` 子句中使用了不正確的資料表別名方式。 **建議的解決方案**：再次檢查 `ORDER BY` 表達式中的所有資料欄是否在 `SELECT DISTINCT` 子句中皆具有正確參考。 #### 比較從子查詢傳回的多個資料欄時，查詢失敗 **範例錯誤訊息**：值表達式和子查詢的結果必須是相同的類型：資料列(varchar, varchar) 與資料列(row(varchar, varchar)) **原因**：由於 Athena 引擎版本 3 中的語法更新，當查詢嘗試比較子查詢傳回的多個值，而子查詢 `SELECT` 陳述式會包括其資料欄清單 (用括號) 時，就會發生此錯誤，如下列範例所示。 ``` SELECT * FROM table1 WHERE (t1_col1, t1_col2) IN (SELECT (t2_col1, t2_col2) FROM table2) ``` **解決方案**：在 Athena 引擎版本 3 中，移除子查詢 `SELECT` 陳述式中資料欄清單周圍的括號，如下列更新的範例查詢所示。 ``` SELECT * FROM table1 WHERE (t1_col1, t1_col2) IN (SELECT t2_col1, t2_col2 FROM table2) ``` #### SKIP 是 DML 查詢的保留字詞單字 `SKIP` 是 DML 查詢的保留字詞，例如 `SELECT`。若要在 DML 查詢中將 `SKIP` 用作識別符，請將其括在雙引號中。如需有關 Athena 中保留字詞的詳細資訊，請參閱 [在查詢中逸出預留關鍵字](reserved-words.md)。 #### 時間歷程已取代 SYSTEM\$1TIME 和 SYSTEM\$1VERSION 子句。 **錯誤訊息**：mismatched input 'SYSTEM\$1TIME'. (不相符的輸入 'SYSTEM\$1TIME'。) 預期：'TIMESTAMP'、'VERSION' **原因**：在先前的引擎版本中，Iceberg 資料表使用了 `FOR SYSTEM_TIME AS OF` 和 `FOR SYSTEM_VERSION AS OF` 子句作為時間戳記和版本時間歷程。Athena 引擎版本 3 使用了 `FOR TIMESTAMP AS OF` 和 `FOR VERSION AS OF` 子句。 **建議的解決方案**：更新 SQL 查詢，以使用 `TIMESTAMP AS OF` 和 `VERSION AS OF` 子句作為時間歷程操作，如下列範例所示。依時間戳記的時間歷程： ``` SELECT * FROM TABLE FOR TIMESTAMP AS OF (current_timestamp - interval '1' day) ``` 依版本的時間歷程： ``` SELECT * FROM TABLE FOR VERSION AS OF 949530903748831860 ``` #### 陣列建構的引數過多 **錯誤訊息**：TOO\$1MANY\$1ARGUMENTS：陣列建構的引數過多。 **原因**：陣列建構中的元素數目上限現已設定為 254。 **建議的解決方案**：將元素分解為多個陣列，每個陣列具有 254 個或更少的元素，並使用 `CONCAT` 函數來串連陣列，如下列範例所示。 ``` CONCAT( ARRAY[x1,x2,x3...x254], ARRAY[y1,y2,y3...y254], ... ) ``` #### 不允許使用零長度分隔的識別碼 **錯誤訊息**：Zero-length delimited identifier not allowed. (不允許使用零長度分隔的識別碼。) **原因**：查詢使用了空白字串作為資料欄別名。 **建議的解決方案**：更新查詢以使用非空白的資料欄別名。 ### 資料處理變更 #### 儲存貯體驗證 **錯誤訊息**：HIVE\$1INVALID\$1BUCKET\$1FILES：Hive 資料表已損壞。 **原因**：該資料表可能已損壞。為確定歸納資料表的查詢正確性，Athena 引擎版本 3 會在歸納資料上啟用額外的驗證，以確保查詢的正確性並避免執行期發生非預期的失敗。 **建議的解決方案**：使用 Athena 引擎版本 3 重新建立資料表。 #### 現在，將結構轉換為 JSON，會傳回欄位名稱當您在 Athena 引擎第 3 版的 `SELECT` 查詢中將 `struct` 轉換為 JSON 時，該轉換現在會傳回欄位名稱和值 (例如 "`useragent":null`) 而非只是值 (例如，`null`)。 #### Iceberg 資料表資料欄層級安全性強制執行變更 **錯誤信息**：Access Denied: Cannot select from columns (存取遭拒：無法從資料欄中選取) **原因**：Iceberg 資料表是在 Athena 之外建立的，並使用早於 0.13.0 的 [Apache Iceberg SDK](https://iceberg.apache.org/releases/) 版本。由於舊版 SDK 不會在中填入資料欄 AWS Glue，Lake Formation 無法判斷授權存取的資料欄。 **建議的解決方案**：使用 Athena [ALTER TABLE SET TBLPROPERTIES](querying-iceberg-alter-table-set-properties.md) 陳述式執行更新，或使用最新的 Iceberg SDK 來修正資料表並更新 AWS Glue中的資料欄資訊。 #### List 資料類型中的 Null 值現已傳播至 UDF **錯誤訊息**：Null Pointer Exception (Null 指標異常情形) **原因**：如果您使用 UDF 連接器並已執行使用者定義的 Lambda 函數，則此問題可能會對您產生影響。先前的引擎版本會篩選出 List 資料類型中已傳遞給使用者定義函式的 Null 值。在 Athena 引擎版本 3 中，會保留 Null 值並傳遞給 UDF。如果 UDF 嘗試在未檢查的情況下取消參考 Null 元素，這可能會導致 Null 指標異常情形。例如，若您在如 DynamoDB 等原始資料來源中具有資料 `[null, 1, null, 2, 3, 4]`，則系統會將以下項目傳遞至使用者定義的 Lambda 函數： **Athena 引擎版本 3**：`[null, 1, null, 2, 3, 4]` **建議的解決方案**：確保使用者定義的 Lambda 函數會處理 List 資料類型中的 Null 元素。 #### 字元陣列中的子字串不再包含已填補的空格 **錯誤訊息**：No error is thrown, but the string returned no longer contains padded spaces. (未擲回任何錯誤，但傳回的字串不再包含已填補的空格。) 例如，`substr(char[20],1,100)` 現在會傳回長度為 20 而非 100 的字串。 **建議的解決方案**：無需採取任何動作。 #### 不支援的十進位資料欄類型強制轉換 **錯誤訊息**：HIVE\$1CURSOR\$1ERROR：讀取 Parquet 檔案失敗：s3://amzn-s3-demo-bucket/*path*/*file\$1name*.parquet 或 Parquet 資料欄有不支援的資料欄類型 (varchar) ([*column\$1name*] **原因**：當嘗試將資料類型強制從 `varchar` 轉換為 decimal 時，Athena 引擎版本 2 偶有成功 (但經常失敗)。由於 Athena 引擎版本 3 會有類型驗證，即會在嘗試讀取值之前先檢查類型是否相容，因此類型嘗試強制執行現在總會失敗。 **建議的解決方案**：對於 Athena 引擎第 3 版，在中修改結構描述 AWS Glue ，以使用數值資料類型，而不是 Parquet 檔案中`varchar`的小數資料欄。重新編目資料並確定新的資料欄資料類型為 decimal 類型，或在 Athena 中手動重新建立資料表，然後使用語法 `decimal(precision, scale)` 指定資料欄的 [decimal](data-types.md#data-types-decimal) 資料類型。 #### Float 或 double NaN 值不能再轉換為 bigint **錯誤訊息**：INVALID\$1CAST\$1ARGUMENT：無法將 real/double NaN 轉換為 bigint **原因**：在 Athena 引擎版本 3 中，`NaN` 無法再以 `bigint` 的形式轉換為 0。 **建議的解決方案**：當您轉換為 `bigint` 時，請確保 `NaN` 值不存在於 `float` 或 `double` 資料欄。 #### uuid() 函數傳回類型變更下列問題會影響資料表和檢視。 **錯誤訊息**：不支援的 Hive 類型：uuid **原因**：在先前的引擎版本中，`uuid()` 函式傳回了一個字串，但在 Athena 引擎版本 3 中，它會傳回一個偽隨機產生的 UUID (類型 4)。由於 Athena 中不支援 UUID 資料欄資料類型，因此無法在 CTAS 查詢中直接使用 `uuid()` 函數，以在 Athena 引擎版本 3 中產生 UUID 資料欄。例如，下列 `CREATE TABLE` 陳述式在先前的引擎版本中成功完成；但在 Athena 引擎版本 3 中，則會傳回 NOT\$1SUPPORTED：不支援的 Hive 類型：uuid： ``` CREATE TABLE uuid_table AS SELECT uuid() AS myuuid ``` 同樣地，下列 `CREATE VIEW` 陳述式在 Athena 引擎版本 2 中已成功完成；但在 Athena 引擎版本 3 中，則會傳回資料欄 myuuid 的資料欄類型無效：不支援的 Hive 類型：uuid： ``` CREATE VIEW uuid_view AS SELECT uuid() AS myuuid ``` 在 Athena 引擎版本 3 中查詢在先前的引擎版本中建立的檢視時，會發生類似下列情況的錯誤： VIEW\$1IS\$1STALE：行 1:15:：檢視 'awsdatacatalog.mydatabase.uuid\$1view' 已過時或處於無效狀態：從位置 0 查詢檢視投影之 uuid 類型的資料欄 [myuuid] 無法強制轉換為儲存在檢視定義中的 varchar 類型的資料欄 [myuuid] **建議的解決方案**：建立資料表或檢視時，請使用 `cast()` 函數將 `uuid()` 的輸出轉換為 `varchar`，如下列範例所示： ``` CREATE TABLE uuid_table AS SELECT CAST(uuid() AS VARCHAR) AS myuuid ``` ``` CREATE VIEW uuid_view AS SELECT CAST(uuid() AS VARCHAR) AS myuuid ``` #### CHAR 和 VARCHAR 強制問題如果您在 Athena 引擎版本 3 中遇到 `varchar` 和 `char` 強制問題，請使用本節的解決方法。如果您無法使用這些解決方法，請聯絡支援。 ##### 混合 CHAR 和 VARCHAR 輸入的 CONCAT 函數失敗 **問題**：Athena 引擎版本 2 會成功執行下列查詢。 ``` SELECT concat(CAST('abc' AS VARCHAR(20)), '12', CAST('a' AS CHAR(1))) ``` 但是，在 Athena 引擎版本 3 上，相同的查詢會失敗，並顯示下列情況： **錯誤訊息**：FUNCTION\$1NOT\$1FOUND：行 1:8：函數 concat 的意外參數 (varchar(20), varchar(2), char(1))。預期：concat(char(x), char(y)), concat(array(E), E) E、concat(E, array(E)) E、concat(array(E)) E、concat(varchar)、concat(varbinary) **建議的解決方案**：使用 `concat` 函數時`varchar`，可轉換為 `char` 或，但不能混合兩者。 ##### SQL \$1\$1 CHAR 和 VARCHAR 輸入的串聯失敗在 Athena 引擎版本 3 中，雙垂直長條圖 `||` 串聯操作員要求 `varchar` 做為輸入。輸入不能是 `varchar` 和 `char` 類型的組合。 **錯誤訊息**：TYPE\$1NOT\$1FOUND：行 1:26：未知類型：char(65537) **原因**：使用 `||` 來串連 `char` 和 `varchar` 的查詢可能會產生錯誤，如下列範例所示。 ``` SELECT CAST('a' AS CHAR) || CAST('b' AS VARCHAR) ``` **建議的解決方案**：串連 `varchar` 和 `varchar`，如下列範例所示。 ``` SELECT CAST('a' AS VARCHAR) || CAST('b' AS VARCHAR) ``` ##### CHAR 和 VARCHAR UNION 查詢失敗 **錯誤訊息**：NOT\$1SUPPORTED：不支援的 Hive 類型：char(65536)。支援的 CHAR 類型：CHAR(<=255) **原因**：嘗試合併 `char` 和 `varchar` 的查詢，如下列範例所示： ``` CREATE TABLE t1 (c1) AS SELECT CAST('a' as CHAR) as c1 UNION ALL SELECT CAST('b' AS VARCHAR) AS c1 ``` **建議的解決方案**：在範例查詢中，將 `'a'` 轉換為 `varchar` 而不是 `char`。 ##### CHAR 或 VARCHAR 強制後不需要的空白空格在 Athena 引擎版本 3 中，當 `char(X)` 和 `varchar` 資料在形成陣列或單一資料欄時強制轉換為單一類型，則 `char(65535)` 是目標類型，而且每個欄位都包含許多不需要的尾隨空格。 **原因**：Athena 引擎版本 3 強制將 `varchar` 和 `char(X)` 轉換為 `char(65535)`，然後右邊填補了空格的資料。 **建議的解決方案**：明確地將每個欄位轉換為 `varchar`。 ### 時間戳記變更 #### 日期時間戳記溢出會擲出錯誤 **錯誤訊息**：Millis overflow: XXX (毫秒溢出：XXX) **原因**：由於在先前的引擎版本中未檢查 ISO 8601 日期是否溢出，因此部分日期會產生負數時間戳記。Athena 引擎版本 3 會檢查此溢出，並擲出例外狀況。 **建議的解決方案**：確保時間戳記在範圍內。 #### 不支援具有 TIME 的政治時區 **錯誤訊息**：INVALID LITERAL (無效常值) **原因**：如 `SELECT TIME '13:21:32.424 America/Los_Angeles'` 等查詢。 **建議的解決方案**：避免使用具有 `TIME` 的政治時區。 #### Timestamp 資料欄中的精確度不符會造成序列化錯誤 **錯誤訊息**：SERIALIZATION\$1ERROR: Could not serialize column '*COLUMNZ*' of type 'timestamp(3)' at position *X*:*Y* (SERIALIZATION\$1ERROR：無法在位置 X:Y 處序列化類型為 'timestamp(3)' 的資料欄 'COLUMNZ') *COLUMNZ* 是造成該問題之資料欄的輸出名稱。數字 *X*:*Y* 表示資料欄在輸出中的位置。 **原因**：Athena 引擎版本 3 會執行檢查，以確保資料中時間戳記的精確度與資料表規格中資料欄資料類型指定的精確度相同。目前，此精確度一直是 3。如果資料的精確度大於此值，則查詢會失敗，且系統會指出錯誤。 **建議的解決方案**：檢查您的資料，以確保您的時間戳記為毫秒精確度。 #### Iceberg 表的 UNLOAD 和 CTAS 查詢中的時間戳記精度不正確 **錯誤訊息**：時間戳記 (6) 的時間戳記精確度不正確；設定的精確度為毫秒 **原因**：Athena 引擎版本 3 會執行檢查，以確保資料中時間戳記的精確度與資料表規格中資料欄資料類型指定的精確度相同。目前，此精確度一直是 3。如果資料的精確度大於此值 (例如以微秒而非毫秒)，則查詢會失敗且系統會指出錯誤。 **解決方案**：若要解決此問題，請先將時間戳記精確度 `CAST` 為 6，如下列建立 Iceberg 資料表的 CTAS 範例所示。請注意，必須將精確度指定為 6 而不是 3，以避免錯誤：Iceberg 不支援時間戳記精度 (3)。 ``` CREATE TABLE my_iceberg_ctas WITH (table_type = 'ICEBERG', location = 's3://amzn-s3-demo-bucket/table_ctas/', format = 'PARQUET') AS SELECT id, CAST(dt AS timestamp(6)) AS "dt" FROM my_iceberg ``` 然後，由於 Athena 不支援時間戳記 6，因此請將值再次轉換為時間戳記 (例如，在檢視中)。下列範例從 `my_iceberg_ctas` 資料表建立檢視。 ``` CREATE OR REPLACE VIEW my_iceberg_ctas_view AS SELECT cast(dt AS timestamp) AS dt FROM my_iceberg_ctas ``` #### 現在，將 ORC 檔案中的 Long 類型讀取為 Timestamp 會造成不正確的 ORC 檔案錯誤，反之亦然 **錯誤訊息**：Error opening Hive split ‘FILE (SPLIT POSITION)’ Malformed ORC file. (開啟 Hive 分割 ‘FILE (SPLIT POSITION)’ 格式不正確的 ORC 檔案時發生錯誤。) Cannot read SQL type timestamp from ORC stream .long\$1type of type LONG (開啟 Hive 分割 ‘FILE (SPLIT POSITION)’ 不正確的 ORC 檔案時發生錯誤。無法從 LONG 類型的 ORC 串流 .long\$1type 讀取 SQL 類型的時間戳記) **原因**：Athena 引擎版本 3 現在會拒絕從 `Long` 資料類型隱含強制轉換至 `Timestamp`，或從 `Timestamp` 轉換至 `Long`。過去，若 `Long` 值為 epoch 毫秒，便會被隱含強制轉換為時間戳記。 **建議的解決方案**：使用 `from_unixtime` 函數來明確轉換資料欄，或者使用 `from_unixtime` 函數為以後的查詢建立一個額外的資料欄。 #### 不支援 time 和 interval year to month **錯誤訊息**：TYPE MISMATCH (類型不相符) **原因**：Athena 引擎版本 3 不支援 time 和 interval year to month (例如 `SELECT TIME '01:00' + INTERVAL '3' MONTH`)。 #### Int96 Parquet 格式的時間戳記溢出 **錯誤訊息**：Invalid timeOfDayNanos (無效的 timeOfDayNanos) **原因**：`int96` Parquet 格式的時間戳記溢出。 **建議的解決方案**：辨識發生問題的特定檔案。然後使用最新且知名的 Parquet 程式庫再次產生資料檔案，或使用 Athena CTAS。如果問題仍持續發生，請聯絡 Athena 支援，並告知我們產生資料檔案的方法。 #### 從字串轉換為時間戳記時，日期和時間值之間需要的空格 **錯誤訊息**：INVALID\$1CAST\$1ARGUMENT：值無法轉換為時間戳記。 **原因**：Athena 引擎版本 3 不再接受連字號做為輸入字串中日期和時間值之間的有效分隔符。`cast`例如，下列查詢在 Athena 引擎版本 3 中無法運作： ``` SELECT CAST('2021-06-06-23:38:46' AS timestamp) AS this_time ``` **建議的解決方案**：在 Athena 引擎版本 3 中，將日期與時間之間的連字號取代為空格，如下列範例所示。 ``` SELECT CAST('2021-06-06 23:38:46' AS timestamp) AS this_time ``` #### to\$1iso8601() 時間戳記傳回值變更 **錯誤訊息**：無 **原因**：在先前的引擎版本中，即使傳遞給 `to_iso8601` 函式的值不包含時區，該函式也會傳回帶有時區的時間戳記。在 Athena 引擎版本 3 中，只有當傳遞的引數包含時區時，`to_iso8601` 函數才會傳回時間戳記與時區。例如，下列查詢會將目前日期傳遞給 `to_iso8601` 函數兩次：首先是做為具有時區的時間戳記，然後是做為時間戳記。 ``` SELECT TO_ISO8601(CAST(CURRENT_DATE AS TIMESTAMP WITH TIME ZONE)), TO_ISO8601(CAST(CURRENT_DATE AS TIMESTAMP)) ``` 下列輸出會顯示 Athena 引擎版本 3 中的查詢結果。在先前的引擎版本中： **** | \$1 | \$1col0 | \$1col1 | | --- | --- | --- | | 1 | `2023-02-24T00:00:00.000Z ` | `2023-02-24T00:00:00.000Z` | Athena 引擎版本 3： **** | \$1 | \$1col0 | \$1col1 | | --- | --- | --- | | 1 | `2023-02-24T00:00:00.000Z` | `2023-02-24T00:00:00.000` | **建議的解決方案**：要複製先前的行為，您可以先將時間戳記值傳遞至 `with_timezone` 函數，然後再將其傳遞給 `to_iso8601`，如下列範例所示： ``` SELECT to_iso8601(with_timezone(TIMESTAMP '2023-01-01 00:00:00.000', 'UTC')) ``` 結果 **** | \$1 | \$1col0 | | --- | --- | | 1 | 2023-01-01T00:00:00.000Z | #### at\$1timezone() 第一個參數必須指定一個日期 **問題**：在 Athena 引擎版本 3 中，`at_timezone` 函數無法將 `time_with_timezone` 值做為第一個參數。 **原因**：如果沒有日期資訊，則無法判斷傳遞的值是夏令時間還是標準時間。例如，`at_timezone('12:00:00 UTC', 'America/Los_Angeles')` 並不明確，因為無法判斷傳遞的值是太平洋夏令時間 (PDT) 還是太平洋標準時間 (PST)。 ## 限制 Athena 引擎版本 3 有以下限制。 + **查詢效能** – 許多查詢在 Athena 引擎版本 3 上的執行速度更快，但部分查詢計畫可能與先前的引擎版本不同。因此，部分查詢的延遲或成本可能有所不同。 + **Trino 和 Presto 連接器** – 不支援 [Trino](https://trino.io/docs/current/connector.html) 和 [Presto](https://prestodb.io/docs/current/connector.html) 連接器。使用 Amazon Athena 聯合查詢來連接資料來源。如需詳細資訊，請參閱[使用 Amazon Athena 聯合查詢](federated-queries.md)。 + **容錯執行** – 不支援 Trino [容錯執行](https://trino.io/docs/current/admin/fault-tolerant-execution.html) (Trino Tardigrade)。 + **函數參數限制** – 函數使用的參數不能超過 127 個。如需詳細資訊，請參閱[函數呼叫的引數過多](troubleshooting-athena.md#troubleshooting-athena-too-many-arguments)。 Athena 引擎版本 2 中引入了下列限制，以確保查詢不會因資源限制而失敗。使用者無法設定這些限制。 + **結果元素的數量** – 下列函數的結果元素 `n` 的數量限制為 10,000 或更少：`min(col, n)`、`max(col, n)`、`min_by(col1, col2, n)` 以及 `max_by(col1, col2, n)`。 + **GROUPING SETS** – 分組集中的配量數目上限為 2048。 + **文字檔案一行長度上限** – 文字檔案預設的一行長度上限為 200 MB。 + **序列函數結果大小上限** – 序列函數的結果大小上限為 50,000 個項目。例如：`SELECT sequence(0,45000,1)` 成功，但 `SELECT sequence(0,55000,1)` 失敗並顯示錯誤訊息 The result of the sequence function must not have more than 50000 entries (序列函數的結果不能有 50,000 個以上項目)。此限制適用於序列函數 (包括時間戳記) 的所有輸入類型。