本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# SQL 函數參考
<a name="aurora-analytics-sql-functions-reference"></a>

這些函數可讓您檢查分析查詢效能、資源用量和快取狀態，以及管理外部資料表定義。使用它們之前，請安裝 擴充功能。`CREATE EXTENSION aurora_analytics` 在您要使用分析的每個資料庫中執行 。

**Topics**
+ [aurora\_analytics\_stat\_statements()](#aurora-analytics-func-stat-statements)
+ [aurora\_analytics\_stat\_resource\_usage()](#aurora-analytics-func-stat-resource-usage)
+ [aurora\_analytics\_instance\_metrics()](#aurora-analytics-func-instance-metrics)
+ [aurora\_analytics\_cache\_size()](#aurora-analytics-func-cache-size)
+ [aurora\_analytics\_clear\_cache()](#aurora-analytics-func-clear-cache)
+ [aurora\_analytics\_refresh\_foreign\_table()](#aurora-analytics-func-refresh-foreign-table)
+ [aurora\_analytics\_available\_features()](#aurora-analytics-func-available-features)
+ [aurora\_analytics\_stats\_duckdb\_memory()](#aurora-analytics-func-stats-duckdb-memory)
+ [aurora\_analytics\_remote\_tables()](#aurora-analytics-func-remote-tables)
+ [aurora\_analytics\_iceberg\_snapshots()](#aurora-analytics-func-iceberg-snapshots)
+ [aurora\_analytics\_iceberg\_metadata()](#aurora-analytics-func-iceberg-metadata)
+ [aurora\_analytics\_iceberg\_raw\_metadata()](#aurora-analytics-func-iceberg-raw-metadata)

下表摘要說明分析 SQL 函數。


**Analytics SQL 函數**  

| 函式 | Scope (範圍) | 它的答案 | 
| --- | --- | --- | 
| aurora\_analytics\_stat\_statements() | 每個標準化查詢，累計 | 從 Amazon S3 讀取的查詢與快取、溢出到磁碟或花費最多的 CPU。 | 
| aurora\_analytics\_stat\_resource\_usage() | 每個後端、即時 | 哪個後端目前正在耗用記憶體、工作者執行緒和溢出空間。 | 
| aurora\_analytics\_instance\_metrics() | 整個執行個體，自引擎啟動以來累積 | 自引擎啟動以來，執行個體已完成多少 Amazon S3 請求和快取活動。 | 
| aurora\_analytics\_cache\_size() | 整個執行個體，目前 | 目前的磁碟上讀取快取大小。 | 
| aurora\_analytics\_clear\_cache() | 整個執行個體 | 清除磁碟上讀取快取以釋放本機儲存。 | 
| aurora\_analytics\_refresh\_foreign\_table() | 每個外部資料表 | 從目前的來源中繼資料重新推斷外部資料表的結構描述。 | 
| aurora\_analytics\_available\_features() | 整個執行個體，目前 | 哪些運算子、函數和類型符合分析引擎下推的資格。 | 
| aurora\_analytics\_stats\_duckdb\_memory() | 每個後端、即時 | 分析引擎如何為目前後端跨內部類別配置記憶體，以及溢出到磁碟的內容。 | 
| aurora\_analytics\_remote\_tables() | 每個遠端目錄和結構描述 | 哪些資料表存在於遠端 Amazon S3 Tables 命名空間或 AWS Glue 資料庫中，及其儲存位置。 | 
| aurora\_analytics\_iceberg\_snapshots() | 每個外部資料表 | 外部資料表存在哪些 Iceberg 快照，用於時間歷程查詢。 | 
| aurora\_analytics\_iceberg\_metadata() | 每個外部資料表 | 哪些 Iceberg 資訊清單和資料檔案會傳回外部資料表。 | 
| aurora\_analytics\_iceberg\_raw\_metadata() | 每個外部資料表 | 外部資料表的原始 Iceberg metadata.json，用於偵錯或非標準欄位。 | 

**注意**  
診斷函數會將所有位元組資料欄報告為原始位元組。將這些資料欄包裝在 `pg_size_pretty()`中以供讀取輸出。

## aurora\_analytics\_stat\_statements()
<a name="aurora-analytics-func-stat-statements"></a>

```
aurora_analytics_stat_statements()
```

傳回每個標準化查詢的累積分析效能統計資料。使用此函數來尋找從 Amazon S3 讀取的查詢，而不是從快取讀取的查詢、溢出到磁碟的查詢，以及哪些查詢花費最多的 CPU 時間。

**注意**  
根據預設，此函數只會針對您自己的角色執行的查詢傳回統計資料。`rds_superuser` 角色的成員會查看所有查詢的統計資料。

下表說明傳回資料欄。


**傳回 aurora\_analytics\_stat\_statements() 的資料欄**  

| 資料行 | Type | 說明 | 
| --- | --- | --- | 
| calls | bigint | 標準化查詢執行的次數。 | 
| analytics\_cache\_hit\_bytes | bigint | 從磁碟上讀取快取提供的位元組數。 | 
| analytics\_remote\_read\_bytes | bigint | 從 Amazon S3 遠端讀取的位元組數。 | 
| analytics\_total\_disk\_spill | bigint | 溢出到臨時本機磁碟儲存體的位元組數。 | 
| analytics\_total\_cpu\_time | double precision | 執行查詢所花費的總 CPU 時間，以毫秒為單位。 | 
| analytics\_total\_thread\_wait\_time | double precision | 工作者執行緒等待的總時間，以毫秒為單位。 | 

函數也會傳回每一列的標準化查詢文字。

下列範例列出讀取資料的查詢，依 Amazon S3 的遠端讀取排序。

```
SELECT calls,
       pg_size_pretty(analytics_cache_hit_bytes) AS cache_hits,
       pg_size_pretty(analytics_remote_read_bytes) AS s3_reads,
       pg_size_pretty(analytics_total_disk_spill) AS spill,
       round(analytics_total_cpu_time::numeric, 2) AS cpu_ms
FROM aurora_analytics_stat_statements()
WHERE analytics_cache_hit_bytes > 0 OR analytics_remote_read_bytes > 0
ORDER BY analytics_remote_read_bytes DESC;
```

解譯結果，如下所示。
+ `analytics_cache_hit_bytes` 遠大於`analytics_remote_read_bytes`表示快取是暖的，且大多數讀取都是本機的。
+ `analytics_remote_read_bytes` 遠大於`analytics_cache_hit_bytes`表示快取很冷，或工作集太大而無法容納在快取中。
+ `analytics_total_disk_spill` 大於 0 表示查詢因為記憶體壓力而溢出到磁碟。

如需解譯這些統計資料和調校工作負載的指引，請參閱 [監控和故障診斷](aurora-analytics-monitoring-troubleshooting.md)和 [資源管理](aurora-analytics-resource-management.md)。

## aurora\_analytics\_stat\_resource\_usage()
<a name="aurora-analytics-func-stat-resource-usage"></a>

```
aurora_analytics_stat_resource_usage()
```

傳回每個後端的分析資源用量即時快照。使用此函數來尋找哪個後端目前正在耗用記憶體、工作者執行緒和溢出空間。

下表說明傳回資料欄。


**傳回 aurora\_analytics\_stat\_resource\_usage() 的資料欄**  

| 資料行 | Type | 說明 | 
| --- | --- | --- | 
| pid | integer | 後端的程序 ID。 | 
| current\_memory\_usage | bigint | 後端目前正在使用的記憶體位元組數。 | 
| active\_threads | integer | 後端目前正在執行的工作者執行緒數量。 | 
| disk\_spill\_size | bigint | 後端目前溢出到臨時本機磁碟儲存體的位元組數。 | 

**注意**  
加入 `pid` `pg_stat_activity`以查看每個後端正在執行的查詢。

下列範例列出使用記憶體的後端，依記憶體用量排序。

```
SELECT pid,
       pg_size_pretty(current_memory_usage) AS mem_used,
       active_threads,
       pg_size_pretty(disk_spill_size) AS spill
FROM aurora_analytics_stat_resource_usage()
WHERE current_memory_usage > 0
ORDER BY current_memory_usage DESC;
```

## aurora\_analytics\_instance\_metrics()
<a name="aurora-analytics-func-instance-metrics"></a>

```
aurora_analytics_instance_metrics()
```

傳回引擎啟動後整個執行個體的累積分析指標。使用此函數來查看執行個體已完成多少 Amazon S3 請求和快取活動。如果引擎重新啟動，計數器會重設。

下表說明傳回資料欄。


**傳回 aurora\_analytics\_instance\_metrics() 的資料欄**  

| 資料行 | Type | 說明 | 
| --- | --- | --- | 
| s3\_head\_request\_count | bigint | 執行個體對 Amazon S3 提出的 HEAD 請求數量。 | 
| s3\_get\_request\_count | bigint | 執行個體對 Amazon S3 提出的 GET 請求數量。 | 
| s3\_cache\_hit\_bytes | bigint | 從磁碟上讀取快取提供的位元組數。 | 
| s3\_remote\_read\_bytes | bigint | 從 Amazon S3 遠端讀取的位元組數。 | 

下列範例會傳回整個執行個體的請求和快取指標。

```
SELECT s3_head_request_count,
       s3_get_request_count,
       pg_size_pretty(s3_cache_hit_bytes) AS cache_hit,
       pg_size_pretty(s3_remote_read_bytes) AS s3_read
FROM aurora_analytics_instance_metrics();
```

## aurora\_analytics\_cache\_size()
<a name="aurora-analytics-func-cache-size"></a>

```
aurora_analytics_cache_size()
```

傳回單一`bigint`值，代表整個執行個體磁碟上讀取快取的目前大小，以位元組為單位。由於 函數會傳回原始位元組，請將它包裝在 中，`pg_size_pretty()`以取得可讀取的輸出。

下列範例會傳回目前的快取大小。

```
SELECT pg_size_pretty(aurora_analytics_cache_size()) AS cache_size;
```

## aurora\_analytics\_clear\_cache()
<a name="aurora-analytics-func-clear-cache"></a>

```
aurora_analytics_clear_cache()
```

清除整個執行個體的磁碟上讀取快取，以釋放本機儲存。清除快取後，後續查詢會從 Amazon S3 重新擷取資料。

**注意**  
此函數需要 `rds_superuser`角色。

下列範例會清除讀取快取。

```
SELECT aurora_analytics_clear_cache();
```

## aurora\_analytics\_refresh\_foreign\_table()
<a name="aurora-analytics-func-refresh-foreign-table"></a>

```
aurora_analytics_refresh_foreign_table(table_name regclass, apply_changes boolean)
```

從目前的來源中繼資料重新推斷外部資料表的結構描述，使資料表定義與基礎 Amazon S3 資料保持同步。第一個引數 `table_name`是外部資料表的名稱或 OID。第二個引數 `apply_changes`是必要的位置布林值，可控制函數預覽或套用變更。函數會傳回`true`成功時`boolean`的值。
+ `apply_changes = false` 會執行試轉並報告變更內容，而不修改資料表。
+ `apply_changes = true` 會將結構描述變更套用至資料表。

許可：外部資料表擁有者或 `rds_superuser`。

下列範例會先預覽變更，然後套用變更。

```
-- Preview the changes
SELECT aurora_analytics_refresh_foreign_table('ft_orders', false);

-- Apply the changes
SELECT aurora_analytics_refresh_foreign_table('ft_orders', true);
```

## aurora\_analytics\_available\_features()
<a name="aurora-analytics-func-available-features"></a>

```
aurora_analytics_available_features()
```

列出分析引擎支援用於向量化執行下推的 PostgreSQL 運算子、函數和類型。使用此函數來判斷哪些 SQL 建構可以原生下推和執行，而不是返回 PostgreSQL。

此函數不採用引數。

下表說明傳回資料欄。


**傳回 aurora\_analytics\_available\_features() 的資料欄**  

| 資料行 | Type | 說明 | 
| --- | --- | --- | 
| feature\_type | text | 目錄物件的類型：運算子、函數或類型。 | 
| oid | oid | 對應pg\_catalog資料表中運算子、函數或類型的 OID。 | 
| description | text | 建構的下推支援限制，如果沒有限制，則為 NULL。 | 

許可：所有使用者。

**注意**  
查詢只有在每個運算子、函數及其參考的類型都會顯示在此函數的輸出中，且沒有限制描述時，才符合完整下推的資格。否則，查詢會回到資料表掃描下推。

下列範例列出具有下推限制的支援類型。

```
SELECT t.typname, f.description
FROM aurora_analytics_available_features() f
JOIN pg_type t ON f.oid = t.oid
WHERE f.feature_type = 'type' AND f.description IS NOT NULL
ORDER BY t.typname;
```

## aurora\_analytics\_stats\_duckdb\_memory()
<a name="aurora-analytics-func-stats-duckdb-memory"></a>

```
aurora_analytics_stats_duckdb_memory()
```

報告目前後端每個內部記憶體類別的記憶體用量和暫時儲存用量。使用此函數來了解分析引擎如何在查詢執行期間跨內部元件配置記憶體。

此函數不採用引數。

下表說明傳回資料欄。


**傳回 aurora\_analytics\_stats\_duckdb\_memory() 的資料欄**  

| 資料行 | Type | 說明 | 
| --- | --- | --- | 
| tag | text | 內部記憶體類別標籤 （例如，BASE\_TABLE、HASH\_TABLE)。 | 
| memory\_usage\_bytes | int8 | 此類別目前配置的記憶體數量，以位元組為單位。 | 
| temporary\_storage\_bytes | int8 | 此類別的資料量溢出到臨時磁碟上儲存，以位元組為單位。 | 

許可：所有使用者。

**注意**  
此函數只會報告目前後端工作階段的記憶體用量。非零`temporary_storage_bytes`值表示分析引擎正在將該類別的資料溢出到磁碟，這可能會影響查詢效能。

下列範例會傳回目前後端的記憶體用量。

```
SELECT * FROM aurora_analytics_stats_duckdb_memory();
```

## aurora\_analytics\_remote\_tables()
<a name="aurora-analytics-func-remote-tables"></a>

```
aurora_analytics_remote_tables(catalog text, schema_name text)
```

探索遠端目錄 ( AWS Glue 資料庫或 Amazon S3 資料表命名空間） 中可用的資料表，並傳回其名稱和儲存位置。

此函數採用下列引數。
+ `catalog`： AWS Glue Data Catalog ARN 或 Amazon S3 Tables 儲存貯體 ARN。這是您在 中使用的相同目錄值`IMPORT FOREIGN SCHEMA`。
+ `schema_name`：目錄中結構描述的名稱 (AWS Glue 資料庫或 Amazon S3 Tables 命名空間）。這是您在 中使用的相同結構描述名稱`IMPORT FOREIGN SCHEMA`。

下表說明傳回資料欄。


**傳回 aurora\_analytics\_remote\_tables() 的資料欄**  

| 資料行 | Type | 說明 | 
| --- | --- | --- | 
| table\_name | text | 遠端結構描述中資料表的名稱。 | 
| location | text |  AWS Glue 資料表 ARN 或 Amazon S3 資料表 ARN。 | 

許可：外部伺服器上`USAGE`的權限。

下列範例列出遠端目錄和結構描述中的資料表。

```
SELECT * FROM aurora_analytics_remote_tables('arn:aws:glue:us-east-1:123456789012:catalog', 'my_database');
```

## aurora\_analytics\_iceberg\_snapshots()
<a name="aurora-analytics-func-iceberg-snapshots"></a>

```
aurora_analytics_iceberg_snapshots(table_name regclass)
```

列出外部資料表的所有可用 Iceberg 快照。在設定時間歷程查詢`snapshot`的選項之前，使用此函數來探索哪些快照存在。

此函數需要一個引數 `table_name`，即 Iceberg 外部資料表的名稱或 OID。

下表說明傳回資料欄。


**傳回 aurora\_analytics\_iceberg\_snapshots() 的資料欄**  

| 資料行 | Type | 說明 | 
| --- | --- | --- | 
| sequence\_number | int8 | 此快照的 Iceberg 序號。 | 
| snapshot\_id | int8 | 快照 ID。將此值與snapshot外部資料表選項搭配使用。 | 
| timestamp\_ms | timestamp | 建立快照時的時間戳記。 | 
| manifest\_list | text | 此快照的資訊清單檔案路徑。 | 

許可：外部資料表擁有者或 `rds_superuser`。僅資料表`SELECT`上的 是不夠的。

下列範例列出外部資料表的五個最近快照。

```
SELECT sequence_number, snapshot_id, timestamp_ms
FROM aurora_analytics_iceberg_snapshots('ft_transactions')
ORDER BY sequence_number DESC
LIMIT 5;
```

## aurora\_analytics\_iceberg\_metadata()
<a name="aurora-analytics-func-iceberg-metadata"></a>

```
aurora_analytics_iceberg_metadata(table_name regclass)
```

列出外部資料表的 Iceberg 資訊清單項目和資料檔案。使用此函數進行偵錯、了解資料表配置，或檢查傳回資料表的資料檔案。

此函數需要一個引數 `table_name`，即 Iceberg 外部資料表的名稱或 OID。

下表說明傳回資料欄。


**傳回 aurora\_analytics\_iceberg\_metadata() 的資料欄**  

| 資料行 | Type | 說明 | 
| --- | --- | --- | 
| manifest\_path | text | 指向資訊清單檔案的路徑。 | 
| manifest\_sequence\_number | int8 | 資訊清單的序號。 | 
| manifest\_content | text | 資訊清單的內容類型 （資料或刪除）。 | 
| status | text | 項目的狀態 （現有、新增、刪除）。 | 
| content | text | 內容類型 （資料或 equality-deletes)。 | 
| file\_path | text | 資料檔案的完整 Amazon S3 路徑。 | 
| file\_format | text | 檔案格式 (Parquet、ORC、Avro)。 | 
| record\_count | int8 | 此資料檔案中的記錄數目。 | 

許可：外部資料表擁有者或 `rds_superuser`。僅資料表`SELECT`上的 是不夠的。

下列範例列出外部資料表的五個最大現有資料檔案。

```
SELECT file_path, file_format, record_count, status
FROM aurora_analytics_iceberg_metadata('ft_transactions')
WHERE status = 'EXISTING'
ORDER BY record_count DESC
LIMIT 5;
```

## aurora\_analytics\_iceberg\_raw\_metadata()
<a name="aurora-analytics-func-iceberg-raw-metadata"></a>

```
aurora_analytics_iceberg_raw_metadata(table_name regclass)
```

以單一 JSON 值傳回 Iceberg 外部資料表`metadata.json`的原始值。使用此函數來偵錯或讀取 `aurora_analytics_iceberg_snapshots`和 `aurora_analytics_iceberg_metadata`不會公開的非標準中繼資料欄位，例如資料表屬性、分割區規格或排序順序。

此函數需要一個引數 `table_name`，即 Iceberg 外部資料表的名稱或 OID。

此函數會傳回包含完整 Iceberg `metadata.json`內容的單一`json`值。

許可：外部資料表擁有者或 `rds_superuser`。僅資料表`SELECT`上的 是不夠的。

**注意**  
使用 PostgreSQL JSON 運算子從結果中擷取特定欄位。

下列範例會傳回外部資料表的原始 Iceberg 中繼資料。

```
SELECT aurora_analytics_iceberg_raw_metadata('ft_transactions');
```