# 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 함수를 요약한 것입니다.


**분석 SQL 함수**  

| 함수 | 범위 | 제공 정보 및 기능 | 
| --- | --- | --- | 
| 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()의 반환 열**  

| 열 | 유형 | 설명 | 
| --- | --- | --- | 
| 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()의 반환 열**  

| 열 | 유형 | 설명 | 
| --- | --- | --- | 
| pid | 정수 | 백엔드의 프로세스 ID입니다. | 
| current\_memory\_usage | bigint | 백엔드가 현재 사용 중인 메모리 바이트 수입니다. | 
| active\_threads | 정수 | 백엔드가 현재 실행 중인 워커 스레드 수입니다. | 
| 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()의 반환 열**  

| 열 | 유형 | 설명 | 
| --- | --- | --- | 
| 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`는 필수 위치 기반 부울 값으로, 함수가 변경 사항을 미리 볼지 아니면 실제로 적용할지를 제어합니다. 이 함수는 성공 시 `boolean` 값 `true`를 반환합니다.
+ `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()의 반환 열**  

| 열 | 유형 | 설명 | 
| --- | --- | --- | 
| feature\_type | 텍스트 | 카탈로그 객체의 종류로 연산자, 함수 또는 데이터 유형 중 하나입니다. | 
| oid | oid | 해당 pg\_catalog 테이블에 있는 연산자, 함수 또는 데이터 유형의 OID입니다. | 
| description | 텍스트 | 해당 구문의 푸시다운 지원에 대한 제한 사항이며, 제한이 없는 경우 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()의 반환 열**  

| 열 | 유형 | 설명 | 
| --- | --- | --- | 
| tag | 텍스트 | 내부 메모리 범주 레이블(예: BASE\_TABLE, HASH\_TABLE)입니다. | 
| memory\_usage\_bytes | "char" | 이 범주에 현재 할당된 메모리 양(바이트 단위)입니다. | 
| temporary\_storage\_bytes | "char" | 이 범주의 데이터 중 임시 온디스크 스토리지로 스필된 바이트 수입니다. | 

권한: 모든 사용자.

**참고**  
이 함수는 현재 백엔드 세션의 메모리 사용량만 보고합니다. `temporary_storage_bytes` 값이 0이 아니라는 것은 분석 엔진이 해당 범주의 데이터를 디스크로 스필하고 있음을 나타내며, 이는 쿼리 성능에 영향을 줄 수 있습니다.

다음 예제는 현재 백엔드의 메모리 사용량을 반환합니다.

```
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 Tables 네임스페이스)에서 사용할 수 있는 테이블을 검색하고 해당 테이블의 이름과 스토리지 위치를 반환합니다.

이 함수는 다음과 같은 인수를 사용합니다.
+ `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()의 반환 열**  

| 열 | 유형 | 설명 | 
| --- | --- | --- | 
| table\_name | 텍스트 | 원격 스키마 내 테이블의 이름입니다. | 
| location | 텍스트 | AWS Glue 테이블 ARN 또는 Amazon S3 Tables 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` 옵션을 설정하기 전 어떤 스냅샷이 존재하는지 확인하려면 이 함수를 사용하세요.

이 함수는 Iceberg 외부 테이블의 이름 또는 OID에 해당하는 `table_name`이라는 인수 한 개를 받습니다.

다음 표는 반환되는 열에 대해 설명합니다.


**aurora\_analytics\_iceberg\_snapshots()의 반환 열**  

| 열 | 유형 | 설명 | 
| --- | --- | --- | 
| sequence\_number | "char" | 이 스냅샷의 Iceberg 시퀀스 번호입니다. | 
| snapshot\_id | "char" | 스냅샷 ID입니다. 이 값을 외부 테이블의 snapshot 옵션과 함께 사용하세요. | 
| timestamp\_ms | timestamp | 스냅샷이 생성된 타임스탬프(시간)입니다. | 
| manifest\_list | 텍스트 | 이 스냅샷의 매니페스트 목록 파일 경로입니다. | 

권한: 외부 테이블 소유자 또는 `rds_superuser` 역할. 테이블에 대한 `SELECT` 권한만으로는 충분하지 않습니다.

다음 예제는 외부 테이블의 최근 스냅샷 5개를 나열합니다.

```
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 매니페스트 항목과 데이터 파일을 나열합니다. 디버깅을 수행하거나, 테이블 레이아웃을 파악하거나, 어떤 데이터 파일이 테이블을 구성하고 있는지 확인하려면 이 함수를 사용하세요.

이 함수는 Iceberg 외부 테이블의 이름 또는 OID에 해당하는 `table_name`이라는 인수 한 개를 받습니다.

다음 표는 반환되는 열에 대해 설명합니다.


**aurora\_analytics\_iceberg\_metadata()의 반환 열**  

| 열 | 유형 | 설명 | 
| --- | --- | --- | 
| manifest\_path | 텍스트 | 매니페스트 파일 경로입니다. | 
| manifest\_sequence\_number | "char" | 매니페스트의 시퀀스 번호입니다. | 
| manifest\_content | 텍스트 | 매니페스트의 콘텐츠 유형(데이터 또는 삭제 파일)입니다. | 
| status | 텍스트 | 항목의 상태(기존 유지, 추가, 삭제)입니다. | 
| content | 텍스트 | 콘텐츠 유형(데이터 또는 동등 삭제 파일)입니다. | 
| file\_path | 텍스트 | 데이터 파일의 전체 Amazon S3 경로입니다. | 
| file\_format | 텍스트 | 파일 형식(Parquet, ORC, Avro)입니다. | 
| record\_count | "char" | 이 데이터 파일의 레코드 수입니다. | 

권한: 외부 테이블 소유자 또는 `rds_superuser` 역할. 테이블에 대한 `SELECT` 권한만으로는 충분하지 않습니다.

다음 예제는 외부 테이블의 기존 데이터 파일 중 크기가 가장 큰 5개를 나열합니다.

```
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)
```

Iceberg 외부 테이블의 원시 `metadata.json`을 단일 JSON 값으로 반환합니다. 테이블 속성, 파티션 사양 또는 정렬 순서와 같이 `aurora_analytics_iceberg_snapshots` 및 `aurora_analytics_iceberg_metadata`에서 노출하지 않는 비표준 메타데이터 필드를 읽거나 디버깅하려면 이 함수를 사용하세요.

이 함수는 Iceberg 외부 테이블의 이름 또는 OID에 해당하는 `table_name`이라는 인수 한 개를 받습니다.

이 함수는 전체 Iceberg `metadata.json` 내용이 포함된 단일 `json` 값을 반환합니다.

권한: 외부 테이블 소유자 또는 `rds_superuser` 역할. 테이블에 대한 `SELECT` 권한만으로는 충분하지 않습니다.

**참고**  
결과에서 특정 필드를 추출하려면 PostgreSQL JSON 연산자를 사용하세요.

다음 예제는 외부 테이블에 대한 원시 Iceberg 메타데이터를 반환합니다.

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