翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS Clean Rooms Spark SQL 関数
AWS Clean Rooms Spark SQL は、次の SQL 関数をサポートしています。
**Topics**
+ [集計関数](sql-functions-agg-spark.md)
+ [配列関数](Array_Functions.md)
+ [条件式](sql-functions-conditional-expressions-spark.md)
+ [コンストラクター関数](sql-functions-constructor.md)
+ [データ型フォーマット関数](Data_type_formatting.md)
+ [日付および時刻関数](date-time-functions-spark.md)
+ [暗号化および復号関数](encryption-decryption-functions.md)
+ [ハッシュ関数](s_hash-functions.md)
+ [Hyperloglog 関数](hyperloglog-functions.md)
+ [JSON 関数](json-functions-spark.md)
+ [数学関数](Math_functions-spark.md)
+ [スカラー関数](scalar_functions.md)
+ [文字列関数](String_functions_spark.md)
+ [プライバシー関連の機能](privacy-related-functions.md)
+ [ウィンドウ関数](Window_functions.md)
# 集計関数
Spark SQL AWS Clean Rooms の集計関数は、行のグループに対して計算またはオペレーションを実行し、単一の値を返すために使用されます。データ分析や要約タスクに不可欠です。
AWS Clean Rooms Spark SQL は、次の集計関数をサポートしています。
**Topics**
+ [ANY\$1VALUE 関数](ANY_VALUE.md)
+ [APPROX COUNT\$1DISTINCT 関数](approx-count-distinct.md)
+ [APPROX PERCENTILE 関数](approx-percentile.md)
+ [AVG 関数](avg-function.md)
+ [BOOL\$1AND 関数](BOOL_AND.md)
+ [BOOL\$1OR 関数](BOOL_OR.md)
+ [CARDINALITY 関数](CARDINALITY.md)
+ [COLLECT\$1LIST 関数](COLLECT_LIST.md)
+ [COLLECT\$1SET 関数](COLLECT_SET.md)
+ [COUNT および COUNT DISTINCT 関数](count-function.md)
+ [COUNT 関数](COUNT.md)
+ [MAX 関数](MAX.md)
+ [MEDIAN 関数](MEDIAN.md)
+ [MIN 関数](MIN.md)
+ [PERCENTILE 関数](percentile.md)
+ [SKEWNESS 関数](SKEWNESS.md)
+ [STDDEV\$1SAMP および STDDEV\$1POP 関数](STDDEV_functions.md)
+ [SUM および SUM DISTINCT 関数](sum-function.md)
+ [VAR\$1SAMP および VAR\$1POP 関数](VARIANCE_functions.md)
# ANY\$1VALUE 関数
ANY\$1VALUE 関数は、入力式の値から任意の値を非決定的に返します。この関数は、入力式で行が返されない場合に NULL を返すことができます。
## 構文
```
ANY_VALUE (expression[, isIgnoreNull] )
```
## 引数
*expression *
関数が動作するターゲット列または式。*式*は、以下に示すデータ型の 1 つを取ります。
*isIgnoreNull*
関数が NULL 以外の値のみを返すかどうかを決定するブール値。
## 戻り値
同じデータ型を *expression* として返します。
## 使用に関する注意事項
列の ANY\$1VALUE 関数を指定するステートメントに 2 番目の列参照も含まれている場合、2 番目の列は GROUP BY 句に含めるか、集計関数に含める必要があります。
## 例
次の例では、`eventname` が `Eagles` である任意の `dateid` のインスタンスを返します。
```
select any_value(dateid) as dateid, eventname from event where eventname ='Eagles' group by eventname;
```
結果は、以下のとおりです。
```
dateid | eventname
-------+---------------
1878 | Eagles
```
次の例では、`eventname` が `Eagles` または `Cold War Kids` である任意の `dateid` のインスタンスを返します。
```
select any_value(dateid) as dateid, eventname from event where eventname in('Eagles', 'Cold War Kids') group by eventname;
```
結果は、以下のとおりです。
```
dateid | eventname
-------+---------------
1922 | Cold War Kids
1878 | Eagles
```
# APPROX COUNT\$1DISTINCT 関数
APPROX COUNT\$1DISTINCT を使用すると、列またはデータセット内の一意の値の数を効率的に見積もることができます。
## 構文
```
approx_count_distinct(expr[, relativeSD])
```
## 引数
expr**
一意の値の数を推定する式または列。
1 つの列、複雑な式、または列の組み合わせを指定できます。
*relativeSD*
見積りの望ましい相対標準偏差を指定するオプションのパラメータ。
これは 0～1 の値で、推定値の最大許容相対誤差を表します。relativeSD 値が小さいほど、より正確ですが推定が遅くなります。
このパラメータを指定しない場合、デフォルト値 (通常は約 0.05 または 5%) が使用されます。
## 戻り値
HyperLogLog\$1\$1 による推定基数を返します。 relativeSD は、許容される最大相対標準偏差を定義します。
## 例
次のクエリは、`col1`列内の一意の値の数を推定し、相対標準偏差は 1% (0.01) です。
```
SELECT approx_count_distinct(col1, 0.01)
```
次のクエリでは、`col1`列に 3 つの一意の値 (値 1、2、3) があると推定します。
```
SELECT approx_count_distinct(col1) FROM VALUES (1), (1), (2), (2), (3) tab(col1)
```
# APPROX PERCENTILE 関数
APPROX PERCENTILE は、データセット全体をソートすることなく、特定の式または列のパーセンタイル値を推定するために使用されます。この関数は、正確なパーセンタイル計算を実行する計算オーバーヘッドなしで、大規模なデータセットの分布をすばやく把握したり、パーセンタイルベースのメトリクスを追跡したりするシナリオに役立ちます。ただし、速度と精度のトレードオフを理解し、ユースケースの特定の要件に基づいて適切なエラー耐性を選択することが重要です。
## 構文
```
APPROX_PERCENTILE(expr, percentile [, accuracy])
```
## 引数
expr**
パーセンタイル値を推定する式または列。
1 つの列、複雑な式、または列の組み合わせを指定できます。
*percentile*
推定するパーセンタイル値。0～1 の値で表されます。
たとえば、0.5 は 50 パーセンタイル (中央値) に対応します。
*精度*
パーセンタイル推定値の望ましい精度を指定するオプションのパラメータ。これは 0～1 の値で、推定値の最大許容相対誤差を表します。`accuracy` 値が小さいほど、より正確ですが推定が遅くなります。このパラメータを指定しない場合、デフォルト値 (通常は約 0.05 または 5%) が使用されます。
## 戻り値
数値または ANSI 間隔列の col の近似パーセンタイルを返します。これは、順序付けられた col 値 (最小から最大にソート) の最小値であり、col 値の割合が 値より小さいか、その値と等しくならないようにします。
パーセンテージの値は 0.0 から 1.0 の間でなければなりません。精度パラメータ (デフォルト: 10000) は、メモリのコストで近似精度を制御する正の数値リテラルです。
精度の値が大きいほど精度が向上します。 `1.0/accuracy`は近似の相対誤差です。
percentage が配列の場合、割合配列の各値は 0.0 から 1.0 の間である必要があります。この場合、 は指定されたパーセンテージ配列で列列列の近似パーセンタイル配列を返します。
## 例
次のクエリは、`response_time`列の 95 パーセンタイルを推定し、最大相対誤差は 1% (0.01) です。
```
SELECT APPROX_PERCENTILE(response_time, 0.95, 0.01) AS p95_response_time
FROM my_table;
```
次のクエリは、`tab`テーブル内の`col`列の 50 パーセンタイル値、40 パーセンタイル値、および 10 パーセンタイル値を推定します。
```
SELECT approx_percentile(col, array(0.5, 0.4, 0.1), 100) FROM VALUES (0), (1), (2), (10) AS tab(col)
```
次のクエリは、col 列の値の 50 パーセンタイル (中央値) を推定します。
```
SELECT approx_percentile(col, 0.5, 100) FROM VALUES (0), (6), (7), (9), (10) AS tab(col)
```
# AVG 関数
AVG 関数は、入力式の値の平均 (算術平均) を返します。AVG 関数は数値に対してはたらき、NULL 値は無視します。
## 構文
```
AVG (column)
```
## 引数
*column*
関数の対象となる列。列は、以下に示すデータ型の 1 つを取ります。
+ SMALLINT
+ INTEGER
+ BIGINT
+ DECIMAL
+ DOUBLE
+ FLOAT
## データ型
AVG 関数でサポートされる引数の型は、SMALLINT、INTEGER、BIGINT、DECIMAL、および DOUBLE です。
AVG 関数でサポートされる戻り値の型は次のとおりです。
+ 整数型の引数の場合は BIGINT
+ 浮動小数点の引数の場合は DOUBLE
+ 他の引数型については、式と同じデータ型を返します。
DECIMAL 引数を使用した AVG 関数の結果のデフォルト精度は 38 です。結果のスケールは、引数のスケールと同じです。例えば、DEC(5,2) 列の AVG は DEC(38,2) データ型を返します。
## 例
SALES テーブルから、取引ごとの平均販売数量を求めます。
```
select avg(qtysold) from sales;
```
# BOOL\$1AND 関数
BOOL\$1AND 関数は、単一のブール値、整数値、または式に対して動作します。この関数は、BIT\$1AND 関数と BIT\$1OR 関数に同様のロジックを適用します。この関数の戻り値の型はブール値 (`true` または `false`) です。
セットの値がすべて true の場合、BOOL\$1AND 関数は `true` (`t`) を返します。いずれかの値が false の場合、関数は `false` (`f`) を返します。
## 構文
```
BOOL_AND ( [DISTINCT | ALL] expression )
```
## 引数
*expression *
関数の対象となる列または式。この式には BOOLEAN または整数のデータ型がある必要があります。関数の戻り値の型は BOOLEAN です。
DISTINCT \$1 ALL
引数 DISTINCT を指定すると、この関数は結果を計算する前に指定された式から重複した値をすべて削除します。引数 ALL 指定すると、この関数は重複する値をすべて保持します。ALL がデフォルトです。
## 例
ブール関数をブール式または整数式のどちらかに対して使用できます。
例えば、次のクエリは複数のブール列のある TICKIT データベースの標準 USERS テーブルから結果を返します。
BOOL\$1AND 関数は 5 行すべてに `false` を返します。これら各州のすべてのユーザーがスポーツを好きというわけではありません。
```
select state, bool_and(likesports) from users
group by state order by state limit 5;
state | bool_and
------+---------
AB | f
AK | f
AL | f
AZ | f
BC | f
(5 rows)
```
# BOOL\$1OR 関数
BOOL\$1OR 関数は、単一のブール値、整数値、または式に対して動作します。この関数は、BIT\$1AND 関数と BIT\$1OR 関数に同様のロジックを適用します。この関数の戻り値の型はブール値 (`true`、`false`、または `NULL`) です。
セットの値が `true` の場合、BOOL\$1OR 関数は `true` (`t`) を返します。セットの値が `false` の場合、関数は `false` (`f`) を返します。値が不明な場合は NULL を返すことができます。
## 構文
```
BOOL_OR ( [DISTINCT | ALL] expression )
```
## 引数
*expression *
関数の対象となる列または式。この式には BOOLEAN または整数のデータ型がある必要があります。関数の戻り値の型は BOOLEAN です。
DISTINCT \$1 ALL
引数 DISTINCT を指定すると、この関数は結果を計算する前に指定された式から重複した値をすべて削除します。引数 ALL 指定すると、この関数は重複する値をすべて保持します。ALL がデフォルトです。
## 例
ブール関数はブール式または整数式のどちらかで使用できます。例えば、次のクエリは複数のブール列のある TICKIT データベースの標準 USERS テーブルから結果を返します。
BOOL\$1OR 関数は 5 行すべてに `true` を返します。これらの州のそれぞれにおいて少なくとも 1 人のユーザーがスポーツを好きです。
```
select state, bool_or(likesports) from users
group by state order by state limit 5;
state | bool_or
------+--------
AB | t
AK | t
AL | t
AZ | t
BC | t
(5 rows)
```
次の例は、NULL を返します。
```
SELECT BOOL_OR(NULL = '123')
bool_or
------
NULL
```
# CARDINALITY 関数
CARDINALITY 関数は、ARRAY 式または MAP 式 (*expr*) のサイズを返します。
この関数は、配列のサイズまたは長さを見つけるのに役立ちます。
## 構文
```
cardinality(expr)
```
## 引数
expr**
ARRAY 式または MAP 式。
## 戻り値
配列またはマップ (INTEGER) のサイズを返します。
が に設定されている場合、`false`または が に設定されている場合`sizeOfNull`、関数`enabled`は null 入力`NULL`を返します`true`。
それ以外の場合、関数は null 入力`-1`を返します。デフォルト設定では、関数は null 入力`-1`に対して を返します。
## 例
次のクエリは、指定された配列の基数または要素の数を計算します。配列 (`'b', 'd', 'c', 'a'`) には 4 つの要素があるため、このクエリの出力は になります`4`。
```
SELECT cardinality(array('b', 'd', 'c', 'a'));
4
```
# COLLECT\$1LIST 関数
COLLECT\$1LIST 関数は、一意でない要素のリストを収集して返します。
このタイプの関数は、行のセットから複数の値を単一の配列またはリストデータ構造に収集する場合に便利です。
**注記**
収集された結果の順序は行の順序に依存するため、関数は非決定的です。シャッフル操作の実行後に非決定的になる可能性があります。
## 構文
```
collect_list(expr)
```
## 引数
expr**
任意のタイプの式。
## 戻り値
引数タイプの ARRAY を返します。配列内の要素の順序は非決定的です。
NULL 値は除外されます。
DISTINCT が指定されている場合、関数は一意の値のみを収集し、`collect_set `集計関数のシノニムです。
## 例
次のクエリは、col 列からすべての値をリストに収集します。`VALUES` 句は、3 行のインラインテーブルを作成するために使用されます。各行の列列はそれぞれ 1、2、1 です。次に、 `collect_list() `関数を使用して、col 列のすべての値を 1 つの配列に集約します。この SQL ステートメントの出力は配列 となり`[1,2,1]`、入力データに表示された順序で col 列のすべての値が含まれます。
```
SELECT collect_list(col) FROM VALUES (1), (2), (1) AS tab(col);
[1,2,1]
```
# COLLECT\$1SET 関数
COLLECT\$1SET 関数は、一意の要素のセットを収集して返します。
この関数は、重複を含めずに、行のセットからすべての個別の値を 1 つのデータ構造に収集する場合に便利です。
**注記**
収集された結果の順序は行の順序に依存するため、関数は非決定的です。シャッフル操作の実行後に非決定的になる可能性があります。
## 構文
```
collect_set(expr)
```
## 引数
expr**
MAP を除く任意のタイプの式。
## 戻り値
引数タイプの ARRAY を返します。配列内の要素の順序は非決定的です。
NULL 値は除外されます。
## 例
次のクエリは、col 列からすべての一意の値をセットに収集します。`VALUES` 句は、3 行のインラインテーブルを作成するために使用されます。各行の列列はそれぞれ 1、2、1 です。次に、 `collect_set()`関数を使用して、col 列のすべての一意の値を 1 つのセットに集約します。この SQL ステートメントの出力は`[1,2]`、col 列の一意の値を含むセット になります。重複する値 1 は、結果に 1 回のみ含まれます。
```
SELECT collect_set(col) FROM VALUES (1), (2), (1) AS tab(col);
[1,2]
```
# COUNT および COUNT DISTINCT 関数
COUNT 関数は、式で定義された行をカウントします。COUNT DISTINCT 関数は、列または式内の個別の非 NULL 値の数を計算します。この関数は、カウントを行う前に指定された式から重複した値をすべて削除します。
## 構文
```
COUNT (DISTINCT column)
```
## 引数
*column*
関数の対象となる列。
## データ型
COUNT 関数および COUNT DISTINCT 関数は、引数のデータ型をすべてサポートしています。
COUNT DISTINCT 関数は BIGINT を返します。
## 例
フロリダ州のユーザーをすべてカウントします。
```
select count (identifier) from users where state='FL';
```
EVENT テーブルから一意の会場 ID をすべてカウントします。
```
select count (distinct venueid) as venues from event;
```
# COUNT 関数
COUNT 関数は式で定義された行をカウントします。
COUNT 関数には 3 つのバリエーションがあります。
+ COUNT(\$1) は null を含むかどうかにかかわらず、ターゲットテーブルのすべての行をカウントします。
+ COUNT ( *expression* ) は、特定の列または式にある Null 以外の値を持つ行数を計算します。
+ COUNT ( DISTINCT *expression* ) は、列または式にある Null 以外の一意な値の数を計算します。
## 構文
```
COUNT( * | expression )
```
```
COUNT ( [ DISTINCT | ALL ] expression )
```
## 引数
*expression *
関数の対象となる列または式。COUNT 関数は引数のデータ型をすべてサポートしています。
DISTINCT \$1 ALL
引数 DISTINCT を指定すると、この関数はカウントを行う前に指定された式から重複した値をすべて削除します。引数 ALL を指定すると、この関数はカウントに使用する式から重複する値をすべて保持します。ALL がデフォルトです。
## 戻り型
COUNT 関数は BIGINT を返します。
## 例
フロリダ州のユーザーをすべてカウントします。
```
select count(*) from users where state='FL';
count
-------
510
```
EVENT テーブルからすべてのイベント名をカウントします。
```
select count(eventname) from event;
count
-------
8798
```
EVENT テーブルからすべてのイベント名をカウントします。
```
select count(all eventname) from event;
count
-------
8798
```
EVENT テーブルから一意の会場 ID をすべてカウントします。
```
select count(distinct venueid) as venues from event;
venues
--------
204
```
4 枚より多いチケットをまとめて販売した販売者ごとの回数をカウントします。販売者 ID で結果をグループ化します。
```
select count(*), sellerid from listing
where numtickets > 4
group by sellerid
order by 1 desc, 2;
count | sellerid
------+----------
12 | 6386
11 | 17304
11 | 20123
11 | 25428
...
```
# MAX 関数
MAX 関数は行のセットの最大値を返します。DISTINCT または ALL が使用される可能性がありますが、結果には影響しません。
## 構文
```
MAX ( [ DISTINCT | ALL ] expression )
```
## 引数
*expression *
関数の対象となる列または式。*式*は任意の数値データ型です。
DISTINCT \$1 ALL
引数 DISTINCT を指定すると、この関数は最大値を計算する前に指定された式から重複した値をすべて削除します。引数 ALL を指定すると、この関数は最大値を計算する式から重複する値をすべて保持します。ALL がデフォルトです。
## データ型
同じデータ型を *expression* として返します。
## 例
すべての販売から最高支払価格を検索します。
```
select max(pricepaid) from sales;
max
----------
12624.00
(1 row)
```
すべての販売からチケットごとの最高支払価格を検索します。
```
select max(pricepaid/qtysold) as max_ticket_price
from sales;
max_ticket_price
-----------------
2500.00000000
(1 row)
```
# MEDIAN 関数
## 構文
```
MEDIAN ( median_expression )
```
## 引数
*median\$1expression*
関数の対象となる列または式。
# MIN 関数
MIN 関数は行のセットの最小値を返します。DISTINCT または ALL が使用される可能性がありますが、結果には影響しません。
## 構文
```
MIN ( [ DISTINCT | ALL ] expression )
```
## 引数
*expression *
関数の対象となる列または式。*式*は任意の数値データ型です。
DISTINCT \$1 ALL
引数 DISTINCT を指定すると、この関数は最小値を計算する前に指定された式から重複した値をすべて削除します。引数 ALL を指定すると、この関数は最小値を計算する式から重複する値をすべて保持します。ALL がデフォルトです。
## データ型
同じデータ型を *expression* として返します。
## 例
すべての販売から最低支払価格を検索します。
```
select min(pricepaid) from sales;
min
-------
20.00
(1 row)
```
すべての販売からチケットごとの最低支払価格を検索します。
```
select min(pricepaid/qtysold)as min_ticket_price
from sales;
min_ticket_price
------------------
20.00000000
(1 row)
```
# PERCENTILE 関数
PERCENTILE 関数は、最初に`col`列内の値をソートし、次に指定された で値を検索することで、正確なパーセンタイル値を計算するために使用します`percentage`。
PERCENTILE 関数は、正確なパーセンタイル値を計算する必要があり、計算コストがユースケースで許容できる場合に役立ちます。APPROX\$1PERCENTILE 関数よりも正確な結果が得られますが、特に大規模なデータセットでは時間がかかる場合があります。
対照的に、APPROX\$1PERCENTILE 関数は、指定されたエラー耐性を持つパーセンタイル値の推定値を提供できる、より効率的な代替手段であり、絶対精度よりも速度が優先度が高いシナリオに適しています。
## 構文
```
percentile(col, percentage [, frequency])
```
## 引数
*コール*
パーセンタイル値を計算する式または列。
*パーセンテージ*
計算するパーセンタイル値。0～1 の値で表されます。
たとえば、0.5 は 50 パーセンタイル (中央値) に対応します。
*頻度 *
`col` 列内の各値の頻度または重みを指定するオプションのパラメータ。指定した場合、関数は各値の頻度に基づいてパーセンタイルを計算します。
## 戻り値
数値または ANSI 間隔の列列の正確なパーセンタイル値を指定されたパーセンテージで返します。
パーセンテージの値は 0.0 から 1.0 の間でなければなりません。
頻度の値は正の整数である必要があります
## 例
次のクエリは、 `col`列の値の 30% 以上の値を検索します。値は 0 と 10 であるため、30 パーセンタイルはデータの 30% 以上の値であるため、3.0 です。
```
SELECT percentile(col, 0.3) FROM VALUES (0), (10) AS tab(col);
3.0
```
# SKEWNESS 関数
SKEWNESS 関数は、グループの値から計算された歪度値を返します。
歪みは、データセット内の非対称性または対称性の欠如を記述する統計的尺度です。データディストリビューションの形状に関する情報を提供します。
この関数は、データセットの統計プロパティを理解し、さらなる分析や意思決定を通知するのに役立ちます。
## 構文
```
skewness(expr)
```
## 引数
expr**
数値に評価される式。
## 戻り値
DOUBLE を返します。
DISTINCT が指定されている場合、関数は一意の *expr* 値のセットでのみ動作します。
## 例
次のクエリは、 `col`列の値の歪みを計算します。この例では、 `VALUES`句を使用して 4 行のインラインテーブルを作成します。各行の列の`col`値は -10、-20、100、1000 です。次に、 `skewness()`関数を使用して`col`列の値の歪度を計算します。結果 1.1135657469022011 は、データの歪みの程度と方向を表します。正の歪値は、データが右側に歪んでいて、値の大部分が分散の左側に集中していることを示します。負の歪値は、データが左側に歪んでいて、値の大部分がディストリビューションの右側に集中していることを示します。
```
SELECT skewness(col) FROM VALUES (-10), (-20), (100), (1000) AS tab(col);
1.1135657469022011
```
次のクエリは、col 列の値の歪度を計算します。前の例と同様に、 `VALUES`句は 4 行のインラインテーブルを作成するために使用されます。各行には -1000、-100、10、20 の値が 1 列`col`あります。次に、 `skewness()`関数を使用して`col`列の値の歪度を計算します。結果 -1.1135657469022011 は、データの歪みの程度と方向を表します。この場合、負の歪値は、データが左側に歪んでいて、値の大部分が分布の右側に集中していることを示します。
```
SELECT skewness(col) FROM VALUES (-1000), (-100), (10), (20) AS tab(col);
-1.1135657469022011
```
# STDDEV\$1SAMP および STDDEV\$1POP 関数
STDDEV\$1SAMP および STDDEV\$1POP 関数は、数値のセットの標本標準偏差と母集団標準偏差 (整数、10 進数、または浮動小数点) を返します。STDDEV\$1SAMP 関数の結果は、値の同じセットの標本分散の平方根に相当します。
STDDEV\$1SAMP および STDDEV は、同じ関数のシノニムです。
## 構文
```
STDDEV_SAMP | STDDEV ( [ DISTINCT | ALL ] expression) STDDEV_POP ( [ DISTINCT | ALL ] expression)
```
式には数値データ型が必要です。式のデータ型にかかわらず、この関数の戻り値の型は倍精度の数値です。
**注記**
標準偏差は浮動小数点演算を使用して計算されます。これはわずかに不正確である可能性があります。
## 使用に関する注意事項
標本標準偏差 (STDDEV または STDDEV\$1SAMP) が 1 つの値で構成される式に対して計算される場合、関数の結果は 0 ではなく、NULL になります。
## 例
次のクエリは VENUE テーブルの VENUESEATS 列の値の平均、続いて値の同じセットの標本標準偏差と母集団標準偏差を返します。VENUESEATS は INTEGER 列です。結果のスケールは 2 桁に減らされます。
```
select avg(venueseats),
cast(stddev_samp(venueseats) as dec(14,2)) stddevsamp,
cast(stddev_pop(venueseats) as dec(14,2)) stddevpop
from venue;
avg | stddevsamp | stddevpop
-------+------------+-----------
17503 | 27847.76 | 27773.20
(1 row)
```
次のクエリは SALES テーブルの COMMISSION 列に標本標準偏差を返します。COMMISSION は DECIMAL 列です。結果のスケールは 10 桁に減らされます。
```
select cast(stddev(commission) as dec(18,10))
from sales;
stddev
----------------
130.3912659086
(1 row)
```
次のクエリは整数として COMMISSION 列の標本標準偏差をキャストします。
```
select cast(stddev(commission) as integer)
from sales;
stddev
--------
130
(1 row)
```
次のクエリは COMMISSION 列に標本標準偏差と標本分散の平方根の両方を返します。これらの計算の結果は同じです。
```
select
cast(stddev_samp(commission) as dec(18,10)) stddevsamp,
cast(sqrt(var_samp(commission)) as dec(18,10)) sqrtvarsamp
from sales;
stddevsamp | sqrtvarsamp
----------------+----------------
130.3912659086 | 130.3912659086
(1 row)
```
# SUM および SUM DISTINCT 関数
SUM 関数は入力列または式の値の合計を返します。SUM 関数は数値に対してはたらき、NULL 値は無視します。
SUM DISTINCT 関数は合計を計算する前に指定された式から重複した値をすべて削除します。
## 構文
```
SUM (DISTINCT column )
```
## 引数
*column*
関数の対象となる列。列は任意の数値データ型です。
## 例
SALES テーブルから、支払われたすべての手数料の合計を求めます。
```
select sum(commission) from sales
```
SALES テーブルから、支払われたすべての重複しない手数料の合計を求めます。
```
select sum (distinct (commission)) from sales
```
# VAR\$1SAMP および VAR\$1POP 関数
VAR\$1SAMP および VAR\$1POP 関数は、数値のセットの標本分散と母集団分散 (整数、10 進数、または浮動小数点) を返します。VAR\$1SAMP 関数の結果は、値の同じセットの 2 乗の標本標準偏差に相当します。
VAR\$1SAMP および VARIANCE は同じ関数のシノニムです。
## 構文
```
VAR_SAMP | VARIANCE ( [ DISTINCT | ALL ] expression)
VAR_POP ( [ DISTINCT | ALL ] expression)
```
この式は整数、10 進数、または浮動小数点数データ型である必要があります。式のデータ型にかかわらず、この関数の戻り値の型は倍精度の数値です。
**注記**
これらの関数の結果は、それぞれのクラスターの設定に応じて、データウェアハウスクラスターによって変わる場合があります。
## 使用に関する注意事項
標本分散 (VARIANCE または VAR\$1SAMP) が 1 つの値で構成される式に対して計算される場合、関数の結果は 0 ではなく、NULL になります。
## 例
次のクエリは LISTING テーブルの NUMTICKETS 列の四捨五入した標本分散と母集団分散を返します。
```
select avg(numtickets),
round(var_samp(numtickets)) varsamp,
round(var_pop(numtickets)) varpop
from listing;
avg | varsamp | varpop
-----+---------+--------
10 | 54 | 54
(1 row)
```
次のクエリは同じ計算を実行しますが、10 進値の結果をキャストします。
```
select avg(numtickets),
cast(var_samp(numtickets) as dec(10,4)) varsamp,
cast(var_pop(numtickets) as dec(10,4)) varpop
from listing;
avg | varsamp | varpop
-----+---------+---------
10 | 53.6291 | 53.6288
(1 row)
```
# 配列関数
このセクションでは、 AWS Clean Roomsでサポートされている SQL の配列関数について説明します。
**Topics**
+ [ARRAY 関数](array.md)
+ [ARRAY\$1CONTAINS 関数](array_contains.md)
+ [ARRAY\$1DISTINCT 関数](array_distinct.md)
+ [ARRAY\$1EXCEPT 関数](array_except.md)
+ [ARRAY\$1INTERSECT 関数](array_intersect.md)
+ [ARRAY\$1JOIN 関数](array_join.md)
+ [ARRAY\$1REMOVE 関数](array_remove.md)
+ [ARRAY\$1UNION 関数](array_union.md)
+ [EXPLODE 関数](explode.md)
+ [FLATTEN 関数](flatten.md)
# ARRAY 関数
指定された要素を持つ配列を作成します。
## 構文
```
ARRAY( [ expr1 ] [ , expr2 [ , ... ] ] )
```
## 引数
*expr1、expr2*
日付型と時刻型を除く任意のデータ型の式。引数は同じデータ型である必要はありません。
## 戻り型
配列関数は、式内の要素を含む ARRAY を返します。
## 例
次の例は、数値の配列と、さまざまなデータ型の配列を示しています。
```
--an array of numeric values
select array(1,50,null,100);
array
------------------
[1,50,null,100]
(1 row)
--an array of different data types
select array(1,'abc',true,3.14);
array
-----------------------
[1,"abc",true,3.14]
(1 row)
```
# ARRAY\$1CONTAINS 関数
ARRAY\$1CONTAINS 関数を使用して、配列データ構造に対して基本的なメンバーシップチェックを実行できます。ARRAY\$1CONTAINS 関数は、配列内に特定の値が存在するかどうかを確認する必要がある場合に便利です。
## 構文
```
array_contains(array, value)
```
## 引数
*array*
検索する ARRAY。
*value*
配列要素と最も一般的でない型を共有する型を持つ式。
## 戻り型
ARRAY\$1CONTAINS 関数は BOOLEAN を返します。
値が NULL の場合、結果は NULL です。
配列内のいずれかの要素が NULL の場合、値が他の要素と一致しない場合、結果は NULL になります。
## 例
次の例では、配列に値 `[1, 2, 3]`が含まれているかどうかを確認します`4`。配列 `[1, 2, 3`] には値 が含まれていないため`4`、array\$1contains 関数は を返します`false`。
```
SELECT array_contains(array(1, 2, 3), 4)
false
```
次の例では、配列に値 `[1, 2, 3]`が含まれているかどうかを確認します`2`。配列`[1, 2, 3]`には値 が含まれているため`2`、array\$1contains 関数は を返します`true`。
```
SELECT array_contains(array(1, 2, 3), 2);
true
```
# ARRAY\$1DISTINCT 関数
ARRAY\$1DISTINCT 関数を使用して、配列から重複した値を削除できます。ARRAY\$1DISTINCT 関数は、配列から重複を削除し、一意の要素のみを操作する必要がある場合に便利です。これは、繰り返し値が干渉されることなくデータセットに対してオペレーションまたは分析を実行するシナリオに役立ちます。
## 構文
```
array_distinct(array)
```
## 引数
*array*
ARRAY 式。
## 戻り型
ARRAY\$1DISTINCT 関数は、入力配列の一意の要素のみを含む ARRAY を返します。
## 例
この例では、入力配列に の重複値`[1, 2, 3, null, 3]`が含まれています`3`。`array_distinct` 関数はこの重複した値を削除`3`し、一意の要素 を持つ新しい配列を返します`[1, 2, 3, null]`。
```
SELECT array_distinct(array(1, 2, 3, null, 3));
[1,2,3,null]
```
この例では、入力配列に `2`と の重複した値`[1, 2, 2, 3, 3, 3]`が含まれています`3`。`array_distinct` 関数はこれらの重複を削除し、一意の要素 を持つ新しい配列を返します`[1, 2, 3]`。
```
SELECT array_distinct(array(1, 2, 2, 3, 3, 3))
[1,2,3]
```
# ARRAY\$1EXCEPT 関数
ARRAY\$1EXCEPT 関数は 2 つの配列を引数として受け取り、最初の配列に存在する要素のみを含む新しい配列を返しますが、2 番目の配列は含みません。
ARRAY\$1EXCEPT は、ある配列と別の配列に固有の要素を見つける必要がある場合に便利です。これは、2 つのデータセットの違いを見つけるなど、配列に対してセットのようなオペレーションを実行する必要がある場合に役立ちます。
## 構文
```
array_except(array1, array2)
```
## 引数
*array1*
同等の要素を持つ任意のタイプの ARRAY。
*array2*
array*1* の要素と最小共通タイプを共有する要素の ARRAY。
## 戻り型
ARRAY\$1EXCEPT 関数は、重複することなく*、配列 1* に一致するタイプの ARRAY を返します。
## 例
この例では、最初の配列に要素 1、2、3 `[1, 2, 3]`が含まれています。2 番目の配列には、要素 2、3、および 4 `[2, 3, 4]`が含まれています。この`array_except`関数は、2 番目の配列にも存在するため、最初の配列から要素 2 と 3 を削除します。結果の出力は配列 です`[1]`。
```
SELECT array_except(array(1, 2, 3), array(2, 3, 4))
[1]
```
この例では、最初の配列に要素 1、2、3 `[1, 2, 3]`が含まれています。2 番目の配列には、要素 1、3、5 `[1, 3, 5]`が含まれます。`array_except` 関数は、2 番目の配列にも存在するため、最初の配列から要素 1 と 3 を削除します。結果の出力は配列 です`[2]`。
```
SELECT array_except(array(1, 2, 3), array(1, 3, 5));
[2]
```
# ARRAY\$1INTERSECT 関数
ARRAY\$1INTERSECT 関数は 2 つの配列を引数として受け取り、両方の入力配列に存在する要素を含む新しい配列を返します。この関数は、2 つの配列間で共通の要素を見つける必要がある場合に便利です。これは、2 つのデータセット間の交差を見つけるなど、配列に対してセットのようなオペレーションを実行する必要がある場合に役立ちます。
## 構文
```
array_intersect(array1, array2)
```
## 引数
*array1*
同等の要素を持つ任意のタイプの ARRAY。
*array2*
array1 の要素と最小共通タイプを共有する要素の ARRAY。
## 戻り型
ARRAY\$1INTERSECT 関数は、配列 1 と配列 2 の両方に含まれる重複や要素なしで、配列 1 に一致するタイプの ARRAY を返します。
## 例
この例では、最初の配列に要素 1、2、3 `[1, 2, 3]`が含まれています。2 番目の配列には、要素 1、3、5 `[1, 3, 5]`が含まれます。ARRAY\$1INTERSECT 関数は、1 と 3 の 2 つの配列間の共通要素を識別します。結果の出力配列は です`[1, 3]`。
```
SELECT array_intersect(array(1, 2, 3), array(1, 3, 5));
[1,3]
```
# ARRAY\$1JOIN 関数
ARRAY\$1JOIN 関数は 2 つの引数を取ります。最初の引数は、結合される入力配列です。2 番目の引数は、配列要素の連結に使用される区切り文字列です。この関数は、文字列の配列 (またはその他のデータ型) を 1 つの連結文字列に変換する必要がある場合に便利です。これは、表示目的や今後の処理など、値の配列を単一の形式の文字列として表示する場合に役立ちます。
## 構文
```
array_join(array, delimiter[, nullReplacement])
```
## 引数
*array*
任意の ARRAY 型、ただしその要素は文字列として解釈されます。
*delimiter*
連結された配列要素を分離するために使用される STRING。
*nullReplacement*
結果で NULL 値を表すために使用される STRING。
## 戻り型
ARRAY\$1JOIN 関数は、配列の要素が区切り文字で区切られ、null 要素が に置き換えられる STRING を返します`nullReplacement`。`nullReplacement` を省略すると、`null`要素は除外されます。引数が の場合`NULL`、結果は です`NULL`。
## 例
この例では、ARRAY\$1JOIN 関数は配列`['hello', 'world']`を取得し、区切り文字 `' '` (スペース文字) を使用して要素を結合します。結果の出力は文字列 です`'hello world'`。
```
SELECT array_join(array('hello', 'world'), ' ');
hello world
```
この例では、ARRAY\$1JOIN 関数は配列`['hello', null, 'world']`を取得し、区切り文字 `' '` (スペース文字) を使用して要素を結合します。`null` 値は、指定された置換文字列 `','` (カンマ) に置き換えられます。結果の出力は文字列 です`'hello , world'`。
```
SELECT array_join(array('hello', null ,'world'), ' ', ',');
hello , world
```
# ARRAY\$1REMOVE 関数
ARRAY\$1REMOVE 関数は 2 つの引数を取ります。最初の引数は、要素が削除される入力配列です。2 番目の引数は、配列から削除される値です。この関数は、配列から特定の要素を削除する必要がある場合に便利です。これは、値の配列に対してデータクリーニングまたは前処理を実行する必要がある場合に役立ちます。
## 構文
```
array_remove(array, element)
```
## 引数
*array*
ARRAY。
*element*
配列の要素と最も一般的でない型を共有する型の式。
## 戻り型
ARRAY\$1REMOVE 関数は、配列のタイプに一致する結果タイプを返します。削除する要素が の場合`NULL`、結果は です`NULL`。
## 例
この例では、ARRAY\$1REMOVE 関数は 配列`[1, 2, 3, null, 3]`を取得し、値 3 のすべての出現を削除します。結果の出力は配列 です`[1, 2, null]`。
```
SELECT array_remove(array(1, 2, 3, null, 3), 3);
[1,2,null]
```
# ARRAY\$1UNION 関数
ARRAY\$1UNION 関数は 2 つの配列を引数として受け取り、両方の入力配列の一意の要素を含む新しい配列を返します。この関数は、2 つの配列を組み合わせて重複要素を排除する必要がある場合に便利です。これは、2 つのデータセット間の結合を見つけるなど、配列に対してセットのようなオペレーションを実行する必要がある場合に役立ちます。
## 構文
```
array_union(array1, array2)
```
## 引数
*array1*
ARRAY。
*array2*
*array1* と同じタイプの ARRAY。
## 戻り型
ARRAY\$1UNION 関数は、配列と同じタイプの ARRAY を返します。
## 例
この例では、最初の配列に要素 1、2、3 `[1, 2, 3]`が含まれています。2 番目の配列には、要素 1、3、5 `[1, 3, 5]`が含まれます。ARRAY\$1UNION 関数は、両方の配列の一意の要素を組み合わせて、出力配列 を生成します`[1, 2, 3, 5]`。T
```
SELECT array_union(array(1, 2, 3), array(1, 3, 5));
[1,2,3,5]
```
# EXPLODE 関数
EXPLODE 関数は、配列またはマップ列を持つ単一の行を複数の行に変換するために使用されます。各行は配列またはマップの単一の要素に対応します。
## 構文
```
explode(expr)
```
## 引数
expr**
配列式またはマップ式。
## 戻り型
EXPLODE 関数は行のセットを返します。各行は入力配列またはマップの 1 つの要素を表します。
出力行のデータ型は、入力配列またはマップ内の要素のデータ型によって異なります。
## 例
次の例では、単一行配列 [10, 20] を取得し、それぞれ配列要素 (10 と 20) の 1 つを含む 2 つの別々の行に変換します。
```
SELECT explode(array(10, 20));
```
最初の例では、入力配列が引数として に直接渡されました`explode()`。この例では、入力配列は `=>`構文を使用して指定されます。ここで、列名 (`collection`) は明示的に指定されます。
```
SELECT explode(array(10, 20));
```
どちらのアプローチも有効であり、同じ結果が得られますが、2 番目の構文は、単純な配列リテラルではなく、より大きなデータセットから列を爆発させる必要がある場合に便利です。
# FLATTEN 関数
FLATTEN 関数は、ネストされた配列構造を単一のフラット配列に「フラット化」するために使用されます。
## 構文
```
flatten(arrayOfArrays)
```
## 引数
*arrayOfArrays*
配列の配列。
## 戻り型
FLATTEN 関数は配列を返します。
## 例
この例では、入力は 2 つの内部配列を持つネストされた配列であり、出力は内部配列のすべての要素を含む単一のフラット配列です。FLATTEN 関数は、ネストされた配列 `[[1, 2], [3, 4]]`を取得し、すべての要素を 1 つの配列 に結合します`[1, 2, 3, 4]`。
```
SELECT flatten(array(array(1, 2), array(3, 4)));
[1,2,3,4]
```
# 条件式
SQL では、条件式を使用して、特定の条件に基づいて決定を行います。これにより、SQL ステートメントのフローを制御し、1 つ以上の条件の評価に基づいて異なる値を返したり、異なるアクションを実行したりできます。
AWS Clean Rooms は、次の条件式をサポートしています。
**Topics**
+ [CASE 条件式](CASE_function.md)
+ [COALESCE 式](coalesce-function.md)
+ [GREATEST 式と LEAST 式](GREATEST_LEAST.md)
+ [**IF** expression](IF.md)
+ [IS\$1NULL 式](IS_NULL.md)
+ [IS\$1NOT\$1NULL 式](IS_NOT_NULL.md)
+ [NVL および COALESCE 関数](NVL_function.md)
+ [NVL2 関数](NVL2.md)
+ [NULLIF 関数](NULLIF_function.md)
# CASE 条件式
CASE 式は条件式であり、他の言語で使われる if/then/else ステートメントと似ています。CASE は、複数の条件がある場合に結果を指定するために使用されます。SELECT コマンドでなど、SQL 式が有効な場合に CASE を使用してください。
2 種類の CASE 式 (簡易および検索) があります。
+ 簡易 CASE 式では、式は値と比較されます。一致が検出された場合、THEN 句で指定されたアクションが適用されます。一致が検出されない場合、ELSE 句のアクションが適用されます。
+ 検索 CASE 式では、CASE ごとにブール式に基づいて検証され、CASE ステートメントは最初を一致する CASE を返します。WHEN 句で検出されない場合、ELSE 句のアクションが返されます。
## 構文
条件を満たすために使用される簡易 CASE ステートメント
```
CASE expression
WHEN value THEN result
[WHEN...]
[ELSE result]
END
```
各条件を検証するために使用する検索 CASE ステートメント
```
CASE
WHEN condition THEN result
[WHEN ...]
[ELSE result]
END
```
## 引数
*expression*
列名または有効な式。
*value*
数値定数または文字列などの式を比較する値。
*result*
式またはブール条件が検証されるときに返されるターゲット値または式。すべての結果式のデータタイプは、単一の出力タイプに変換できる必要があります。
condition**
true または false に評価される Boolean 式。*条件*が true の場合、CASE 式の値は条件に続く結果であり、残りの CASE 式は処理されません。*条件*が false の場合、後続の WHEN 句はすべて評価されます。WHEN 条件の結果がどれも true ではない場合、CASE 式の値が ELSE 句の結果になります。ELSE 句が省略され、どの条件も true ではない場合、結果は Null となります。
## 例
簡易 CASE 式を使用し、VENUE テーブルに対するクエリで `New York City` を `Big Apple` に置換します。その他すべての都市名を `other` に置換します。
```
select venuecity,
case venuecity
when 'New York City'
then 'Big Apple' else 'other'
end
from venue
order by venueid desc;
venuecity | case
-----------------+-----------
Los Angeles | other
New York City | Big Apple
San Francisco | other
Baltimore | other
...
```
検索 CASE 式を使用し、それぞれのチケット販売の PRICEPAID 値に基づいてグループ番号を割り当てます。
```
select pricepaid,
case when pricepaid <10000 then 'group 1'
when pricepaid >10000 then 'group 2'
else 'group 3'
end
from sales
order by 1 desc;
pricepaid | case
----------+---------
12624 | group 2
10000 | group 3
10000 | group 3
9996 | group 1
9988 | group 1
...
```
# COALESCE 式
COALESCE 式は、Null ではないリストの最初の式の値を返します。すべての式が null の場合、結果は null になります。null 以外の値が見つかると、リスト内の残りの式は検証されません。
このタイプの式は、優先する値がないか Null の場合に何かにバックアップ値を返すときに役に立ちます。例えば、クエリは 3 つの電話番号 (携帯、自宅、職場の順) のうち、いずれかテーブルで最初に検出された 1 つを返す可能性があります (Null でない)。
## 構文
```
COALESCE (expression, expression, ... )
```
## 例
COALESCE 式を 2 つの列に適用します。
```
select coalesce(start_date, end_date)
from datetable
order by 1;
```
NVL 式のデフォルトの列名は COALESCE です。次のクエリは同じ結果を返します。
```
select coalesce(start_date, end_date) from datetable order by 1;
```
# GREATEST 式と LEAST 式
任意の数の式のリストから最大値または最小値を返します。
## 構文
```
GREATEST (value [, ...])
LEAST (value [, ...])
```
## パラメータ
*expression\$1list*
列名などの式のカンマ区切りリスト。式はすべて一般的なデータ型に変換可能である必要があります。リスト内の NULL 値は無視されます。すべての式が NULL と評価された場合、結果は NULL になります。
## 戻り値
指定された式のリストから最大 (GREATEST の場合) または最小 (LEAST の場合) の値を返します。
## 例
次の例は、アルファベット順で最も高い `firstname` または `lastname` の値を返します。
```
select firstname, lastname, greatest(firstname,lastname) from users
where userid < 10
order by 3;
firstname | lastname | greatest
-----------+-----------+-----------
Alejandro | Rosalez | Ratliff
Carlos | Salazar | Carlos
Jane | Doe | Doe
John | Doe | Doe
John | Stiles | John
Shirley | Rodriguez | Rodriguez
Terry | Whitlock | Terry
Richard | Roe | Richard
Xiulan | Wang | Wang
(9 rows)
```
# **IF** expression
IF 条件関数は、条件に基づいて 2 つの値のいずれかを返します。
この関数は、条件の評価に基づいて決定を行い、異なる値を返すために SQL で使用される一般的なコントロールフローステートメントです。これは、クエリ内に単純な if-else ロジックを実装するのに役立ちます。
## 構文
```
if(expr1, expr2, expr3)
```
## 引数
*expr1*
評価される条件または式。の場合`true`、関数は *expr2* の値を返します。*expr1* が の場合`false`、関数は *expr3* の値を返します。
*expr2*
*expr1* が の場合に評価および返される式`true`。
*expr3*
*expr1* が の場合に評価および返される式`false`。
## 戻り値
が に`expr1`評価された場合`true`、 は を返し`expr2`、それ以外の場合は を返します`expr3`。
## 例
次の例では、 `if()`関数を使用して、条件に基づいて 2 つの値のいずれかを返します。評価される条件は です`1 < 2`。これは であるため`true`、最初の値`'a'`が返されます。
```
SELECT if(1 < 2, 'a', 'b');
a]
```
# IS\$1NULL 式
IS\$1NULL 条件式は、値が null かどうかをチェックするために使用されます。
この式は のシノニムですIS NULL。
## 構文
```
is_null(expr)
```
## 引数
expr**
任意のタイプの式。
## 戻り値
IS\$1NULL 条件式はブール値を返します。`expr1` が NULL の場合、 は を返し`true`、それ以外の場合は を返します`false`。
## 例
次の例では、値が `1` null かどうかをチェックし、1 が有効な NULL 以外の値`true`であるため、ブール値を返します。
```
SELECT is not null(1);
true
```
次の例では、`squirrels`テーブルから`id`列を選択しますが、経過時間列が である行に対してのみ選択します`null`。
```
SELECT id FROM squirrels WHERE is_null(age)
```
# IS\$1NOT\$1NULL 式
IS\$1NOT\$1NULL 条件式は、値が null でないかどうかを確認するために使用されます。
この式は のシノニムですIS NOT NULL。
## 構文
```
is_not_null(expr)
```
## 引数
expr**
任意のタイプの式。
## 戻り値
IS\$1NOT\$1NULL 条件式はブール値を返します。`expr1` が NULL でない場合、 は を返し`true`、それ以外の場合は を返します`false`。
## 例
次の例では、値が null でないかどうかをチェックし、1 `1`が有効な NULL 以外の値`true`であるため、ブール値を返します。
```
SELECT is not null(1);
true
```
次の例では、`squirrels`テーブルから`id`列を選択しますが、経過時間列が ではない行に対してのみ選択します`null`。
```
SELECT id FROM squirrels WHERE is_not_null(age)
```
# NVL および COALESCE 関数
一連の式の中で、Null 以外の最初の式の値を返します。Null 以外の値が見つかると、リスト内の残りの式は評価されません。
NVL は COALESCE と同じです。これらはシノニムです。このトピックでは、両方の構文について説明し、例を示します。
## 構文
```
NVL( expression, expression, ... )
```
COALESCE の構文は同じです。
```
COALESCE( expression, expression, ... )
```
すべての式が null の場合、結果は null になります。
これらの関数は、プライマリ値がないか Null の場合にセカンダリ値を返すときに役に立ちます。例えば、クエリを実行すると、使用可能な 3 つの電話番号 (携帯、自宅、職場) のうち最初の電話番号が返されることがあります。関数内の式の順序によって、評価の順序が決まります。
## 引数
*expression*
Null ステータスが評価される列名などの式。
## 戻り型
AWS Clean Rooms は、入力式に基づいて返される値のデータ型を決定します。入力式のデータ型に共通の型がない場合は、エラーが返されます。
## 例
リストに整数式が含まれている場合、関数は整数を返します。
```
SELECT COALESCE(NULL, 12, NULL);
coalesce
--------------
12
```
この例は前の例と同じですが、NVL を使用して、同じ結果が返される点が異なります。
```
SELECT NVL(NULL, 12, NULL);
coalesce
--------------
12
```
次の例は、文字列型を返します。
```
SELECT COALESCE(NULL, 'AWS Clean Rooms', NULL);
coalesce
--------------
AWS Clean Rooms
```
次の例では、式リストのデータ型が異なるため、エラーになります。この場合、リストには文字列型と数値型の両方があります。
```
SELECT COALESCE(NULL, 'AWS Clean Rooms', 12);
ERROR: invalid input syntax for integer: "AWS Clean Rooms"
```
# NVL2 関数
指定された式の結果が NULL か NOT NULL かに基づいて、2 つの値のいずれかを返します。
## 構文
```
NVL2 ( expression, not_null_return_value, null_return_value )
```
## 引数
*expression*
Null ステータスが評価される列名などの式。
*not\$1null\$1return\$1value*
*expression* が NOT NULL に評価された場合に返される値。*not\$1null\$1return\$1value* 値は、*expression* と同じデータ型を持つか、そのデータ型に暗黙的に変換可能である必要があります。
*null\$1return\$1value*
*expression* が NULL に評価される場合に値が返されます。*null\$1return\$1value* 値は、*expression* と同じデータ型を持つか、そのデータ型に暗黙的に変換可能である必要があります。
## 戻り型
NVL2 の戻り値の型は、次のように決まります。
+ *not\$1null\$1return\$1value* または *null\$1return\$1value* が null の場合、not-null 式のデータ型が返されます。
*not\$1null\$1return\$1value* と *null\$1return\$1value* がどちらも null である場合
+ *not\$1null\$1return\$1value* と *null\$1return\$1value* のデータ型が同じ場合、そのデータ型が返されます。
+ *not\$1null\$1return\$1value* と *null\$1return\$1value* の数値データ型が異なる場合、互換性を持つ最小の数値データ型が返されます。
+ *not\$1null\$1return\$1value* と *null\$1return\$1value* の日時データ型が異なる場合、タイムスタンプデータ型が返されます。
+ *not\$1null\$1return\$1value* と *null\$1return\$1value* の文字データ型が異なる場合、*not\$1null\$1return\$1value* のデータ型が返されます。
+ *not\$1null\$1return\$1value* と *null\$1return\$1value* で数値データ型と数値以外のデータ型が混合している場合、*not\$1null\$1return\$1value* のデータ型が返されます。
**重要**
*not\$1null\$1return\$1value* のデータ型が返される最後の 2 つのケースでは、*null\$1return\$1value* がそのデータ型に暗黙的にキャストされます。データ型に互換性がない場合、関数は失敗します。
## 使用に関する注意事項
NVL2 では、*not\$1null\$1return\$1value* または *null\$1return\$1value* パラメータのうち、どちらか関数により選択された方の値が戻り値に含められますが、データ型については *not\$1null\$1return\$1value* のデータ型が含められます。
例えば、column1 が NULL の場合、次のクエリは同じ値を返します。ただし、DECODE の戻り値のデータ型は INTEGER となり、NVL2 の戻り値のデータ型は VARCHAR になります。
```
select decode(column1, null, 1234, '2345');
select nvl2(column1, '2345', 1234);
```
## 例
次の例では、一部のサンプルデータを変更し、2 つのフィールドを評価してユーザーに適切な連絡先情報を提供します。
```
update users set email = null where firstname = 'Aphrodite' and lastname = 'Acevedo';
select (firstname + ' ' + lastname) as name,
nvl2(email, email, phone) AS contact_info
from users
where state = 'WA'
and lastname like 'A%'
order by lastname, firstname;
name contact_info
--------------------+-------------------------------------------
Aphrodite Acevedo (555) 555-0100
Caldwell Acevedo Nunc.sollicitudin@example.ca
Quinn Adams vel@example.com
Kamal Aguilar quis@example.com
Samson Alexander hendrerit.neque@example.com
Hall Alford ac.mattis@example.com
Lane Allen et.netus@example.com
Xander Allison ac.facilisis.facilisis@example.com
Amaya Alvarado dui.nec.tempus@example.com
Vera Alvarez at.arcu.Vestibulum@example.com
Yetta Anthony enim.sit@example.com
Violet Arnold ad.litora@example.comm
August Ashley consectetuer.euismod@example.com
Karyn Austin ipsum.primis.in@example.com
Lucas Ayers at@example.com
```
# NULLIF 関数
2 つの引数を比較し、引数が等しい場合は Null を返します。等しくない場合、最初の引数が返されます。
## 構文
NULLIF 式は 2 つの引数を比較し、引数が等しい場合に Null を返します。等しくない場合、最初の引数が返されます。この式は NVL または COALESCE 式の逆です。
```
NULLIF ( expression1, expression2 )
```
## 引数
*expression1, expression2*
比較対象の列または式。戻り値の型は、最初の式の型と同じです。
## 例
次の例では、引数が等しくないため、クエリは `first` 文字列を返します。
```
SELECT NULLIF('first', 'second');
case
-------
first
```
次の例では、文字列リテラル引数が等しいため、クエリは `NULL` を返します。
```
SELECT NULLIF('first', 'first');
case
-------
NULL
```
次の例では、整数の引数が等しくないため、クエリは `1` を返します。
```
SELECT NULLIF(1, 2);
case
-------
1
```
次の例では、整数の引数が等しいため、クエリは `NULL` を返します。
```
SELECT NULLIF(1, 1);
case
-------
NULL
```
次の例に示すクエリは、LISTID 値と SALESID 値が一致する場合に Null を返します。
```
select nullif(listid,salesid), salesid
from sales where salesid<10 order by 1, 2 desc;
listid | salesid
--------+---------
4 | 2
5 | 4
5 | 3
6 | 5
10 | 9
10 | 8
10 | 7
10 | 6
| 1
(9 rows)
```
# コンストラクター関数
SQL コンストラクタ関数は、配列やマップなどの新しいデータ構造を作成するために使用される関数です。
いくつかの入力値を取得し、新しいデータ構造オブジェクトを返します。コンストラクタ関数は通常、ARRAY や MAP など、作成するデータ型にちなんで命名されます。
コンストラクタ関数は、スカラー関数や集計関数とは異なり、既存のデータに対して動作し、単一の値を返します。コンストラクタ関数は、新しいデータ構造を作成するために使用されます。このデータ構造は、さらなるデータ処理や分析に使用できます。
AWS Clean Rooms は、次のコンストラクタ関数をサポートしています。
**Topics**
+ [MAP コンストラクタ関数](map_function.md)
+ [NAMED\$1STRUCT コンストラクタ関数](named-struct_function.md)
+ [STRUCT コンストラクタ関数](struct_function.md)
# MAP コンストラクタ関数
MAP コンストラクタ関数は、指定されたキーと値のペアを持つマップを作成します。
MAP などのコンストラクタ関数は、SQL クエリ内でプログラムで新しいデータ構造を作成する必要がある場合に役立ちます。これにより、さらなるデータ処理や分析に使用できる複雑なデータ構造を構築できます。
## 構文
```
map(key0, value0, key1, value1, ...)
```
## 引数
*キー0*
同等の任意のタイプの式。すべての *key0* は、最も一般的でないタイプを共有する必要があります。
*値0*
任意のタイプの式。すべての *valueN* は、最小共通タイプを共有する必要があります。
## 戻り値
MAP 関数は、最も一般的でないタイプの *key0* として入力されたキーと、最も一般的でないタイプの *value0* として入力された値を持つ MAP を返します。
## 例
次の例では、2 つのキーと値のペアを持つ新しいマップを作成します。キー `1.0`は値 に関連付けられています`'2'`。キー`3.0`は値 に関連付けられます`'4'`。その後、結果のマップが SQL ステートメントの出力として返されます。
```
SELECT map(1.0, '2', 3.0, '4');
{1.0:"2",3.0:"4"}
```
# NAMED\$1STRUCT コンストラクタ関数
NAMED\$1STRUCT コンストラクタ関数は、指定されたフィールド名と値を持つ構造体を作成します。
NAMED\$1STRUCT などのコンストラクタ関数は、SQL クエリ内でプログラムで新しいデータ構造を作成する必要がある場合に役立ちます。これにより、構造体やレコードなどの複雑なデータ構造を構築できます。これは、さらなるデータ処理や分析に使用できます。
## 構文
```
named_struct(name1, val1, name2, val2, ...)
```
## 引数
*名前1*
STRING リテラル命名フィールド 1。
*val1*
フィールド 1 の値を指定する任意のタイプの式。
## 戻り値
NAMED\$1STRUCT 関数は、*val*1 のタイプに一致するフィールド 1 を持つ構造体を返します。
## 例
次の例では、3 つの名前付きフィールドを持つ新しい構造体を作成します。 フィールド`"a"`には値 が割り当てられます`1`。フィールドには 値が`"b"`割り当てられます`2.`。 フィールド`"c"`には 値が割り当てられます`3`。結果として得られる構造体は、SQL ステートメントの出力として返されます。
```
SELECT named_struct("a", 1, "b", 2, "c", 3);
{"a":1,"b":2,"c":3}
```
# STRUCT コンストラクタ関数
STRUCT コンストラクタ関数は、指定されたフィールド値を持つ構造体を作成します。
STRUCT などのコンストラクタ関数は、SQL クエリ内でプログラムで新しいデータ構造を作成する必要がある場合に役立ちます。これにより、構造体やレコードなどの複雑なデータ構造を構築できます。これは、さらなるデータ処理や分析に使用できます。
## 構文
```
struct(col1, col2, col3, ...)
```
## 引数
*col1*
列名または有効な式。
## 戻り値
STRUCT 関数は、*expr**1 のタイプに一致する field*1 を持つ構造体を返します。
引数が参照という名前の場合、名前はフィールドの名前に使用されます。それ以外の場合、フィールドの名前は *colN* です。ここで、N は構造体内のフィールドの位置です。
## 例
次の例では、3 つのフィールドを持つ新しい構造体を作成します。最初のフィールドには値 1 が割り当てられます。2 番目のフィールドには値 2 が割り当てられます。3 番目のフィールドには値 3 が割り当てられます。デフォルトでは、結果の構造体のフィールドには`col1`、引数リスト内の位置に基づいて、`col2`、`col3`、および という名前が付けられます。結果として得られる構造体は、SQL ステートメントの出力として返されます。
```
SELECT struct(1, 2, 3);
{"col1":1,"col2":2,"col3":3}
```
# データ型フォーマット関数
データ型フォーマット関数を使用すると、値のデータ型を変換できます。これらの各関数では必ず、最初の引数にはフォーマットする値を指定し、2 番目の引数には新しい形式のテンプレートを指定します。
AWS Clean Rooms Spark SQL は、複数のデータ型フォーマット関数をサポートしています。
**Topics**
+ [BASE64 関数](base64.md)
+ [CAST 関数](CAST_function.md)
+ [DECODE 関数](DECODE.md)
+ [ENCODE 関数](ENCODE.md)
+ [HEX 関数](HEX.md)
+ [STR\$1TO\$1MAP 関数](STR_TO_MAP.md)
+ [TO\$1CHAR](TO_CHAR.md)
+ [TO\$1DATE 関数](TO_DATE_function.md)
+ [TO\$1NUMBER](TO_NUMBER.md)
+ [UNBASE64 関数](unbase64.md)
+ [UNHEX 関数](UNHEX.md)
+ [日時形式の文字列](FORMAT_strings.md)
+ [数値形式の文字列](Numeric_formating.md)
# BASE64 関数
BASE64 関数は、[MIME の RFC2045 Base64 転送エンコーディングを使用して式を base 64 文字列に変換します](https://datatracker.ietf.org/doc/html/rfc2045)。
## 構文
```
base64(expr)
```
## 引数
expr**
関数が BINARY として解釈する BINARY 式または STRING。
## 戻り型
`STRING`
## 例
指定された文字列入力を Base64 でエンコードされた表現に変換するには、次の例を使用します。その結果、入力文字列「Spark SQL」の Base64 エンコード表現がU3BhcmsgU1FM」になります。
```
SELECT base64('Spark SQL');
U3BhcmsgU1FM
```
# CAST 関数
CAST 関数は、1 つのデータ型を互換性のある別のデータ型に変換します。例えば、文字列を日付に変換したり、数値型を文字列に変換したりできます。CAST はランタイム変換を実行します。つまり、変換によってソーステーブル内の値のデータ型は変更されません。クエリのコンテキストでのみ変更されます。
特定のデータ型では、CAST 関数を使用して他のデータ型に明示的に変換する必要があります。他のデータ型は、CAST を使用せずに、別のコマンドの一部として暗黙的に変換できます。「[型の互換性と変換](s_Type_conversion.md)」を参照してください。
## 構文
式のデータ型を別のデータ型に変換するには、次の 2 つの同等な構文フォームのいずれかを使用します。
```
CAST ( expression AS type )
```
## 引数
*expression*
1 つ以上の値 (列名、値など) に評価される式。null 値を変換すると、null が返されます。式に、空白または空の文字列を含めることはできません。
*type*
BINARY [データ型](s_Supported_data_types.md) および BINARY VARYING データ型を除く、サポートされている の 1 つ。
## 戻り型
CAST は、*type* 引数で指定されたデータ型を返します。
**注記**
AWS Clean Rooms は、次のような精度を失った DECIMAL 変換など、問題のある変換を実行しようとすると、エラーを返します。
```
select 123.456::decimal(2,1);
```
また、次の INTEGER 変換では、オーバーフローが生じます。
```
select 12345678::smallint;
```
## 例
次の 2 つのクエリは同等です。どちらも 10 進値を整数に変換します。
```
select cast(pricepaid as integer)
from sales where salesid=100;
pricepaid
-----------
162
(1 row)
```
```
select pricepaid::integer
from sales where salesid=100;
pricepaid
-----------
162
(1 row)
```
次の場合も同様の結果が得られます。サンプルデータの実行は必要ありません。
```
select cast(162.00 as integer) as pricepaid;
pricepaid
-----------
162
(1 row)
```
次の例では、タイムスタンプ列の値を日付に変換して、各結果から時刻を削除します。
```
select cast(saletime as date), salesid
from sales order by salesid limit 10;
saletime | salesid
-----------+---------
2008-02-18 | 1
2008-06-06 | 2
2008-06-06 | 3
2008-06-09 | 4
2008-08-31 | 5
2008-07-16 | 6
2008-06-26 | 7
2008-07-10 | 8
2008-07-22 | 9
2008-08-06 | 10
(10 rows)
```
前のサンプルで示した CAST を使用しなかった場合、結果には *2008-02-18 02:36:48* という時刻が含まれます。
次のクエリは、可変文字データを日付に変換します。実行にサンプルデータは必要ありません。
```
select cast('2008-02-18 02:36:48' as date) as mysaletime;
mysaletime
--------------------
2008-02-18
(1 row)
```
次の例では、日付列の値をタイムスタンプに変換します。
```
select cast(caldate as timestamp), dateid
from date order by dateid limit 10;
caldate | dateid
--------------------+--------
2008-01-01 00:00:00 | 1827
2008-01-02 00:00:00 | 1828
2008-01-03 00:00:00 | 1829
2008-01-04 00:00:00 | 1830
2008-01-05 00:00:00 | 1831
2008-01-06 00:00:00 | 1832
2008-01-07 00:00:00 | 1833
2008-01-08 00:00:00 | 1834
2008-01-09 00:00:00 | 1835
2008-01-10 00:00:00 | 1836
(10 rows)
```
前のサンプルのような場合は、[TO\$1CHAR](TO_CHAR.md) を使用して出力形式をさらに制御できます。
次の例では、整数が文字列に変換されます。
```
select cast(2008 as char(4));
bpchar
--------
2008
```
次の例では、DECIMAL(6,3) 値を DECIMAL(4,1) 値に変換します。
```
select cast(109.652 as decimal(4,1));
numeric
---------
109.7
```
この例は、より複雑な式を示しています。SALES テーブル内の PRICEPAID 列 (DECIMAL(8,2) 列) を DECIMAL(38,2) 列に変換し、結果の値を 100000000000000000000 で乗算します。
```
select salesid, pricepaid::decimal(38,2)*100000000000000000000
as value from sales where salesid<10 order by salesid;
salesid | value
---------+----------------------------
1 | 72800000000000000000000.00
2 | 7600000000000000000000.00
3 | 35000000000000000000000.00
4 | 17500000000000000000000.00
5 | 15400000000000000000000.00
6 | 39400000000000000000000.00
7 | 78800000000000000000000.00
8 | 19700000000000000000000.00
9 | 59100000000000000000000.00
(9 rows)
```
# DECODE 関数
DECODE 関数は ENCODE 関数と同等であり、特定の文字エンコードを使用して文字列をバイナリ形式に変換するために使用されます。DECODE 関数はバイナリデータを取得し、指定された文字エンコードを使用して読み取り可能な文字列形式に変換します。
この関数は、データベースに保存されているバイナリデータを操作し、人間が読める形式で表示する必要がある場合や、異なる文字エンコード間でデータを変換する必要がある場合に便利です。
## 構文
```
decode(expr, charset)
```
## 引数
expr**
文字セットでエンコードされた BINARY 式。
*文字セット*
STRING 式。
サポートされている文字セットエンコーディング (大文字と小文字を区別しない): `'US-ASCII'`、`'ISO-8859-1'`、`'UTF-8'`、`'UTF-16BE'`、`'UTF-16LE'`、および `'UTF-16'`。
## 戻り型
DECODE 関数は STRING を返します。
## 例
次の例では、UTF-8 文字エンコーディングを使用してメッセージデータをバイナリ形式で`message_text`保存する という列`messages`を持つ というテーブルがあります。DECODE 関数は、バイナリデータを読み取り可能な文字列形式に変換します。このクエリの出力は、メッセージテーブルに保存されているメッセージの読み取り可能なテキストで、ID は で`123`、 エン`'utf-8'`コードを使用してバイナリ形式から文字列に変換されます。
```
SELECT decode(message_text, 'utf-8') AS message
FROM messages
WHERE message_id = 123;
```
# ENCODE 関数
ENCODE 関数は、指定された文字エンコードを使用して文字列をバイナリ表現に変換するために使用されます。
この関数は、バイナリデータを使用する必要がある場合や、異なる文字エンコーディング間で変換する必要がある場合に便利です。たとえば、バイナリストレージを必要とするデータベースにデータを保存する場合や、異なる文字エンコードを使用するシステム間でデータを転送する必要がある場合に、ENCODE 関数を使用できます。
## 構文
```
encode(str, charset)
```
## 引数
*str*
エンコードされる STRING 式。
*文字セット*
エンコードを指定する STRING 式。
サポートされている文字セットエンコーディング (大文字と小文字を区別しない): `'US-ASCII'`、`'ISO-8859-1'`、`'UTF-8'`、`'UTF-16BE'`、`'UTF-16LE'`、および `'UTF-16'`。
## 戻り型
ENCODE 関数は BINARY を返します。
## 例
次の例では、エン`'utf-8'`コードを使用して文字列を`'abc'`バイナリ表現に変換します。この場合、元の文字列が返されます。これは、エン`'utf-8'`コードが可変幅の文字エンコードであり`'a'`、文字ごとに 1 バイトを使用して ASCII 文字セット全体 (、`'b'`、 を含む`'c'`) を表すことができるためです。したがって、 `'abc'`を使用する のバイナリ表現`'utf-8'`は、元の文字列と同じです。
```
SELECT encode('abc', 'utf-8');
abc
```
# HEX 関数
HEX 関数は、数値 (整数または浮動小数点数) を対応する 16 進文字列表現に変換します。
16 進数は、16 個の異なる記号 (0～9 および A～F) を使用して数値を表す数値システムです。コンピュータサイエンスやプログラミングで一般的に使用され、バイナリデータをよりコンパクトで人間が読める形式で表現します。
## 構文
```
hex(expr)
```
## 引数
expr**
BIGINT、BINARY、または STRING 式。
## 戻り型
HEX は STRING を返します。関数は、引数の 16 進数表現を返します。
## 例
次の例では、整数値 17 を入力として受け取り、それに HEX() 関数を適用します。出力は です。これは`11`入力値 の 16 進数表現です`17`。
```
SELECT hex(17);
11
```
次の例では、文字列を 16 進数表現に変換`'Spark_SQL'`します。出力は です。これは`537061726B2053514C`入力文字列 の 16 進数表現です`'Spark_SQL'`。
```
SELECT hex('Spark_SQL');
537061726B2053514C
```
この例では、文字列「Spark\$1SQL」は次のように変換されます。
+ 'S' -> 53
+ 'p' -> 70
+ 'a' -> 61
+ 'r' -> 72 '
+ k' -> 6B
+ '\$1' -> 20
+ 'S' -> 53
+ 'Q' -> 51
+ 'L' -> 4C
これらの 16 進値の連結は、最終的な出力「」になります`537061726B2053514C"`。
# STR\$1TO\$1MAP 関数
STR\$1TO\$1MAP 関数は、string-to-map変換関数です。マップ (またはディクショナリ) の文字列表現を実際のマップデータ構造に変換します。
この関数は、SQL でマップデータ構造を操作する必要がある場合に便利ですが、データは最初は文字列として保存されます。文字列表現を実際のマップに変換することで、マップデータのオペレーションと操作を実行できます。
## 構文
```
str_to_map(text[, pairDelim[, keyValueDelim]])
```
## 引数
*text*
マップを表す STRING 式。
*pairDelim*
エントリを分離する方法を指定するオプションの STRING リテラル。デフォルトはカンマ () です`','`。
*keyValueDelim*
各キーと値のペアを分離する方法を指定するオプションの STRING リテラル。デフォルトではコロン () になります`':'`。
## 戻り型
STR\$1TO\$1MAP 関数は、キーと値の両方について STRING の MAP を返します。*pairDelim* と *keyValueDelim* はどちらも正規表現として扱われます。
## 例
次の例では、入力文字列と 2 つの区切り文字引数を取得し、文字列表現を実際のマップデータ構造に変換します。この特定の例では、入力文字列はキーと値のペアを持つマップ`'a:1,b:2,c:3'`を表します。 `'a'` はキー、 `'1'` は値です。 `'b'`はキー、 `'2'`は値です。 はキー、 は 値です。 `'c'` はキー、 `'3'`は 値です。`','` 区切り記号を使用してキーと値のペアを区切り、`':'`区切り記号を使用して各ペア内のキーと値を区切ります。このクエリの出力は です`{"a":"1","b":"2","c":"3"}`。これは結果のマップデータ構造で、キーは `'a'`、、`'b'`および `'c'`で、対応する値は `'1'`、`'2'`、および です`'3'`。
```
SELECT str_to_map('a:1,b:2,c:3', ',', ':');
{"a":"1","b":"2","c":"3"}
```
次の例は、STR\$1TO\$1MAP 関数が入力文字列が特定の形式で、キーと値のペアが正しく区切られていることを想定していることを示しています。入力文字列が想定された形式と一致しない場合、関数は引き続きマップの作成を試みますが、結果の値は想定どおりではない可能性があります。
```
SELECT str_to_map('a');
{"a":null}
```
# TO\$1CHAR
TO\$1CHAR は、タイムスタンプまたは数値式を文字列データ形式に変換します。
## 構文
```
TO_CHAR (timestamp_expression | numeric_expression , 'format')
```
## 引数
*timestamp\$1expression*
TIMESTAMP 型または TIMESTAMPTZ 型の値、またはタイムスタンプに暗黙的に強制変換できる値を生成する式。
*numeric\$1expression*
数値データ型の値、または数値型に暗黙的に強制変換できる値が生成される式。詳細については、「[数値型](Numeric_types.md)」を参照してください。TO\$1CHAR は、数文字列の左側にスペースを挿入します。
TO\$1CHAR は、128 ビットの DECIMAL 値をサポートしません。
*format*
新しい値の形式。有効な形式については、「[日時形式の文字列](FORMAT_strings.md)」および「[数値形式の文字列](Numeric_formating.md)」を参照してください。
## 戻り型
VARCHAR
## 例
次の例では、月の名前を 9 文字に埋め込み、曜日の名前と日付の数字を指定した形式でタイムスタンプを日付と時刻の値に変換します。
```
select to_char(timestamp '2009-12-31 23:15:59', 'MONTH-DY-DD-YYYY HH12:MIPM');
to_char
-------------------------
DECEMBER -THU-31-2009 11:15PM
```
次の例では、タイムスタンプを日付の番号の値に変換します。
```
select to_char(timestamp '2009-12-31 23:15:59', 'DDD');
to_char
-------------------------
365
```
次の例では、タイムスタンプを曜日の番号の値に変換します。
```
select to_char(timestamp '2022-05-16 23:15:59', 'ID');
to_char
-------------------------
1
```
以下の例では、日付から月を抽出しています。
```
select to_char(date '2009-12-31', 'MONTH');
to_char
-------------------------
DECEMBER
```
次の例は、EVENT テーブル内の各 STARTTIME 値を、時、分、および秒から成る文字列に変換します。
```
select to_char(starttime, 'HH12:MI:SS')
from event where eventid between 1 and 5
order by eventid;
to_char
----------
02:30:00
08:00:00
02:30:00
02:30:00
07:00:00
(5 rows)
```
次の例は、タイムスタンプの値全体を別の形式に変換します。
```
select starttime, to_char(starttime, 'MON-DD-YYYY HH12:MIPM')
from event where eventid=1;
starttime | to_char
---------------------+---------------------
2008-01-25 14:30:00 | JAN-25-2008 02:30PM
(1 row)
```
次の例は、タイムスタンプリテラルをキャラクタ文字列に変換します。
```
select to_char(timestamp '2009-12-31 23:15:59','HH24:MI:SS');
to_char
----------
23:15:59
(1 row)
```
次の例では、数字を負の記号を末尾に付けた文字列に変換します。
```
select to_char(-125.8, '999D99S');
to_char
---------
125.80-
(1 row)
```
次の例では、数字を通貨記号付きの文字列に変換します。
```
select to_char(-125.88, '$S999D99');
to_char
---------
$-125.88
(1 row)
```
次の例では、負の数字に角括弧を使用して、数字を文字列に変換します。
```
select to_char(-125.88, '$999D99PR');
to_char
---------
$<125.88>
(1 row)
```
次の例では、数字をローマ字の文字列に変換します。
```
select to_char(125, 'RN');
to_char
---------
CXXV
(1 row)
```
次の例では、曜日を表示します。
```
SELECT to_char(current_timestamp, 'FMDay, FMDD HH12:MI:SS');
to_char
-----------------------
Wednesday, 31 09:34:26
```
次の例では、数に対して序数のサフィックスを表示します。
```
SELECT to_char(482, '999th');
to_char
-----------------------
482nd
```
次の例では、販売テーブル内の支払い価格からコミッションを減算します。誤差は四捨五入されて、ローマ数字に変換され、`to_char` 列に表示されます。
```
select salesid, pricepaid, commission, (pricepaid - commission)
as difference, to_char(pricepaid - commission, 'rn') from sales
group by sales.pricepaid, sales.commission, salesid
order by salesid limit 10;
salesid | pricepaid | commission | difference | to_char
---------+-----------+------------+------------+-----------------
1 | 728.00 | 109.20 | 618.80 | dcxix
2 | 76.00 | 11.40 | 64.60 | lxv
3 | 350.00 | 52.50 | 297.50 | ccxcviii
4 | 175.00 | 26.25 | 148.75 | cxlix
5 | 154.00 | 23.10 | 130.90 | cxxxi
6 | 394.00 | 59.10 | 334.90 | cccxxxv
7 | 788.00 | 118.20 | 669.80 | dclxx
8 | 197.00 | 29.55 | 167.45 | clxvii
9 | 591.00 | 88.65 | 502.35 | dii
10 | 65.00 | 9.75 | 55.25 | lv
(10 rows)
```
次の例では、さまざまな値に通貨記号を追加して、`to_char` 列に表示します。
```
select salesid, pricepaid, commission, (pricepaid - commission)
as difference, to_char(pricepaid - commission, 'l99999D99') from sales
group by sales.pricepaid, sales.commission, salesid
order by salesid limit 10;
salesid | pricepaid | commission | difference | to_char
--------+-----------+------------+------------+------------
1 | 728.00 | 109.20 | 618.80 | $ 618.80
2 | 76.00 | 11.40 | 64.60 | $ 64.60
3 | 350.00 | 52.50 | 297.50 | $ 297.50
4 | 175.00 | 26.25 | 148.75 | $ 148.75
5 | 154.00 | 23.10 | 130.90 | $ 130.90
6 | 394.00 | 59.10 | 334.90 | $ 334.90
7 | 788.00 | 118.20 | 669.80 | $ 669.80
8 | 197.00 | 29.55 | 167.45 | $ 167.45
9 | 591.00 | 88.65 | 502.35 | $ 502.35
10 | 65.00 | 9.75 | 55.25 | $ 55.25
(10 rows)
```
次の例では、各販売が行われた世紀を一覧で示します。
```
select salesid, saletime, to_char(saletime, 'cc') from sales
order by salesid limit 10;
salesid | saletime | to_char
---------+---------------------+---------
1 | 2008-02-18 02:36:48 | 21
2 | 2008-06-06 05:00:16 | 21
3 | 2008-06-06 08:26:17 | 21
4 | 2008-06-09 08:38:52 | 21
5 | 2008-08-31 09:17:02 | 21
6 | 2008-07-16 11:59:24 | 21
7 | 2008-06-26 12:56:06 | 21
8 | 2008-07-10 02:12:36 | 21
9 | 2008-07-22 02:23:17 | 21
10 | 2008-08-06 02:51:55 | 21
(10 rows)
```
次の例は、EVENT テーブル内の各 STARTTIME 値を、時、分、秒、およびタイムゾーンから成る文字列に変換します。
```
select to_char(starttime, 'HH12:MI:SS TZ')
from event where eventid between 1 and 5
order by eventid;
to_char
----------
02:30:00 UTC
08:00:00 UTC
02:30:00 UTC
02:30:00 UTC
07:00:00 UTC
(5 rows)
(10 rows)
```
以下の例では、秒、ミリ秒、マイクロ秒の形式を示しています。
```
select sysdate,
to_char(sysdate, 'HH24:MI:SS') as seconds,
to_char(sysdate, 'HH24:MI:SS.MS') as milliseconds,
to_char(sysdate, 'HH24:MI:SS:US') as microseconds;
timestamp | seconds | milliseconds | microseconds
--------------------+----------+--------------+----------------
2015-04-10 18:45:09 | 18:45:09 | 18:45:09.325 | 18:45:09:325143
```
# TO\$1DATE 関数
TO\$1DATE は、文字列で表記された日付を DATE データ型に変換します。
## 構文
```
TO_DATE (date_str)
```
```
TO_DATE (date_str, format)
```
## 引数
*date\$1str*
日付文字列または日付文字列にキャストできるデータ型。
*format*
Spark の日時パターンに一致する文字列リテラル。有効な日時パターンについては、[「フォーマットと解析の日時パターン](https://spark.apache.org/docs/latest/sql-ref-datetime-pattern.html)」を参照してください。
## 戻り型
TO\$1DATE は、*format* の値に応じて DATE を返します。
*フォーマット*への変換が失敗すると、エラーが返されます。
## 例
次の SQL ステートメントは、日付 `02 Oct 2001` を日付データ型に変換します。
```
select to_date('02 Oct 2001', 'dd MMM yyyy');
to_date
------------
2001-10-02
(1 row)
```
次の SQL ステートメントは、文字列 `20010631` を日付に変換します。
```
select to_date('20010631', 'yyyyMMdd');
```
次の SQL ステートメントは、文字列 `20010631` を日付に変換します。
```
to_date('20010631', 'YYYYMMDD', TRUE);
```
6 月には 30 日しかないため、結果は null 値です。
```
to_date
------------
NULL
```
# TO\$1NUMBER
TO\$1NUMBER は、文字列を数値 (10 進) に変換します。
## 構文
```
to_number(string, format)
```
## 引数
*string*
変換する文字列。形式はリテラル値である必要があります。
*format*
2 番目の引数は、数値を作成するために文字列を解析する方法を示す書式文字列です。例えば、形式 `'99D999'` では、変換する文字列が 5 つの数字で構成され、3 番目の位置に小数点が挿入されます。たとえば、`to_number('12.345','99D999')`は数値として `12.345` を返します。有効な形式の一覧については、「[数値形式の文字列](Numeric_formating.md)」を参照してください。
## 戻り型
TO\$1NUMBER は DECIMAL 型の数値を返します。
*フォーマット*への変換が失敗すると、エラーが返されます。
## 例
次の例では、文字列 `12,454.8-` を数値に変換します。
```
select to_number('12,454.8-', '99G999D9S');
to_number
-----------
-12454.8
```
次の例では、文字列 `$ 12,454.88` を数値に変換します。
```
select to_number('$ 12,454.88', 'L 99G999D99');
to_number
-----------
12454.88
```
次の例では、文字列 `$ 2,012,454.88` を数値に変換します。
```
select to_number('$ 2,012,454.88', 'L 9,999,999.99');
to_number
-----------
2012454.88
```
# UNBASE64 関数
UNBASE64 関数は、引数をベース 64 文字列からバイナリに変換します。
Base64 エンコーディングは、さまざまな通信チャネル (E メール、URL パラメータ、データベースストレージなど) を介した送信に安全なテキスト形式でバイナリデータ (イメージ、ファイル、暗号化された情報など) を表すために一般的に使用されます。
UNBASE64 関数を使用すると、このプロセスを逆にして元のバイナリデータを復元できます。このタイプの機能は、データ転送メカニズムとして Base64 を使用する外部システムや APIs と統合する場合など、Base64 形式でエンコードされたデータを操作する必要がある場合に役立ちます。
## 構文
```
unbase64(expr)
```
## 引数
expr**
base64 形式の STRING 式。
## 戻り型
`BINARY`
## 例
次の例では、Base64-encodedされた文字列`'U3BhcmsgU1FM'`は元の文字列 に変換されます`'Spark SQL'`。
```
SELECT unbase64('U3BhcmsgU1FM');
Spark SQL
```
# UNHEX 関数
UNHEX 関数は、16 進数の文字列を元の文字列表現に変換します。
この関数は、16 進形式で保存または送信されたデータを操作する必要があり、さらに処理または表示するために元の文字列表現を復元する必要がある場合に役立ちます。
UNHEX 関数は[、HEX 関数](HEX.md)のカウンターパートです。
## 構文
```
unhex(expr)
```
## 引数
expr**
16 進数文字の STRING 式。
## 戻り型
UNHEX は BINARY を返します。
*expr* の長さが奇数の場合、最初の文字は破棄され、結果は null バイトで埋められます。*expr* に 16 進数以外の文字が含まれている場合、結果は NULL です。
## 例
次の例では、UNHEX() 関数と DECODE() 関数を一緒に使用して、16 進数の文字列を元の文字列表現に変換します。クエリの最初の部分では、UNHEX() 関数を使用して 16 進文字列 '537061726B2053514C' をバイナリ表現に変換します。クエリの 2 番目の部分では、DECODE() 関数を使用して、UNHEX() 関数から取得したバイナリデータを文字列に変換し、'UTF-8' 文字エンコーディングを使用します。クエリの出力は、16 進数に変換され、文字列に戻された元の文字列「Spark\$1SQL」です。
```
SELECT decode(unhex('537061726B2053514C'), 'UTF-8');
Spark SQL
```
# 日時形式の文字列
以下の一般的なシナリオでは、日時パターンを使用できます。
+ CSV および JSON データソースを使用して日時コンテンツを解析およびフォーマットする場合
+ 次のような関数を使用して文字列型と日付型またはタイムスタンプ型の間で変換する場合:
+ unix\$1timestamp
+ date\$1format
+ to\$1unix\$1timestamp
+ from\$1unixtime
+ to\$1date
+ to\$1timestamp
+ from\$1utc\$1timestamp
+ to\$1utc\$1timestamp
日付とタイムスタンプの解析と書式設定には、次の表のパターン文字を使用します。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/clean-rooms/latest/sql-reference/FORMAT_strings.html)
パターン文字の数によって形式タイプが決まります。
テキスト形式
+ 省略形には 1～3 文字を使用します (月曜日には「月」など）。
+ 完全な形式 (「月曜日」など) には 4 文字のみを使用してください。
+ 5 文字以上は使用しないでください。エラーが発生します。
数値形式 (n)
+ 値 n は、許可される最大文字数を表します。
+ 単一文字パターンの場合:
+ 出力はパディングなしで最小桁数を使用します
+ 複数の文字パターンの場合:
+ 出力は文字数の幅に合わせてゼロで埋められます
+ 解析する場合、入力には正確な桁数が含まれている必要があります
数値/テキスト形式
+ 3 文字以上の場合は、テキスト形式ルールに従います。
+ 文字数を減らすには、数値形式ルールに従います。
フラクション形式
+ 1～9 文字の「S」文字を使用する (SSSSSS など)
+ 解析の場合:
+ 1 から S 文字数までの小数を受け入れる
+ フォーマットの場合:
+ S 文字数と一致するゼロのパッド
+ マイクロ秒の精度で最大 6 桁をサポート
+ ナノ秒を解析できますが、余分な桁は切り捨てます
年形式
+ 文字数はパディングの最小フィールド幅を設定します
+ 2 文字の場合:
+ 最後の 2 桁を出力します
+ 2000-2099 の間の年を解析する
+ 4 文字未満の場合 (2 文字を除く):
+ 負の年のみの符号を表示します
+ 7 文字以上は使用しないでください。エラーが発生します。
月の形式
+ 標準フォームには「M」、スタンドアロンフォームには「L」を使用します。
+ 単一の「M」または「L」:
+ パディングなしで月番号 1～12 を表示します
+ 「MM」または「LL」:
+ パディング付きの月番号 01～12 を表示します
+ 'MMM':
+ 略名を標準形式で表示する
+ 完全な日付パターンの一部である必要があります
+ 'LLL':
+ 省略された月名をスタンドアロン形式で表示する
+ 月のみの書式設定に使用
+ 「MMMM」:
+ 月名を標準形式で表示する
+ 日付とタイムスタンプに を使用する
+ 'LLLL':
+ 完全な月名をスタンドアロン形式で表示する
+ 月のみの書式設定に使用
タイムゾーン形式
+ am-pm: 1 文字のみを使用する
+ ゾーン ID (V): 2 文字のみを使用する
+ ゾーン名 (z):
+ 1～3 文字: 短縮名を表示します
+ 4 文字: フルネームを表示します
+ 5 文字以上は使用しないでください
オフセット形式
+ X と x:
+ 1 文字: 時間 (\$101) または時間/分 (\$10130) を表示
+ 2 文字: コロンなしの時間/分を表示 (\$10130)
+ 3 文字: コロンで時間/分を表示 (\$101:30)
+ 4 文字: コロンなしhour-minute-secondを表示 (\$1013015)
+ 5 文字: hour-minute-secondをコロンで表示 (\$101:30:15)
+ X はゼロオフセットに「Z」を使用します
+ x はゼロオフセットに「\$100」、「\$10000」、または「\$100:00」を使用します
+ O:
+ 1 文字: ショートフォームを表示 (GMT\$18)
+ 4 文字: フルフォームを表示 (GMT\$108:00)
+ Z:
+ 1～3 文字: コロンなしの時間/分を表示 (\$10130)
+ 4 文字: 完全なローカライズされたフォームを表示します
+ 5 文字: hour-minute-secondとコロンを表示
オプションのセクション
+ 角括弧 [ ] を使用してオプションのコンテンツをマークする
+ オプションのセクションをネストできます
+ すべての有効なデータが出力に表示されます
+ 入力はオプションセクション全体を省略できます
**注記**
記号「E」、「F」、「q」、「Q」は、日時形式 (date\$1format など) でのみ機能します。日時解析 (to\$1timestamp など) には使用しないでください。
# 数値形式の文字列
以下の数値形式の文字列は、TO\$1NUMBER や TO\$1CHAR などの関数に適用されます。
+ 文字列を数値の形式にする例については、「[TO\$1NUMBER](TO_NUMBER.md)」を参照してください。
+ 数字をも文字列の形式にする例については、「[TO\$1CHAR](TO_CHAR.md)」を参照してください。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/clean-rooms/latest/sql-reference/Numeric_formating.html)
# 日付および時刻関数
日付と時刻関数を使用すると、日付の一部の抽出、日付計算の実行、日付と時刻の書式設定、現在の日付と時刻の操作など、日付と時刻のデータに対して幅広いオペレーションを実行できます。これらの関数は、データ分析、レポート、時間的データを含むデータ操作などのタスクに不可欠です。
AWS Clean Rooms では、次の日付および時刻関数がサポートされています。
**Topics**
+ [ADD\$1MONTHS 関数](ADD_MONTHS.md)
+ [CONVERT\$1TIMEZONE 関数](s_CONVERT_TIMEZONE.md)
+ [CURRENT\$1DATE 関数](CURRENT_DATE_function.md)
+ [CURRENT\$1TIMESTAMP 関数](CURRENT_TIMESTAMP.md)
+ [DATE\$1ADD 関数](DATE_ADD_function.md)
+ [DATE\$1DIFF 関数](DATE_DIFF_function.md)
+ [DATE\$1PART 関数](DATE_PART_function.md)
+ [DATE\$1TRUNC 関数](DATE_TRUNC.md)
+ [DAY 関数](DAY.md)
+ [DAYOFMONTH 関数](DAYOFMONTH.md)
+ [DAYOFWEEK 関数](DAYOFWEEK.md)
+ [DAYOFYEAR 関数](DAYOFYEAR.md)
+ [EXTRACT 関数](EXTRACT_function.md)
+ [FROM\$1UTC\$1TIMESTAMP 関数](FROM_UTC_TIMESTAMP.md)
+ [HOUR 関数](HOUR.md)
+ [MINUTE 関数](MINUTE.md)
+ [MONTH 関数](MONTH.md)
+ [SECOND 関数](SECOND.md)
+ [TIMESTAMP 関数](TIMESTAMP.md)
+ [TO\$1TIMESTAMP 関数](TO_TIMESTAMP.md)
+ [YEAR 関数](YEAR.md)
+ [日付関数またはタイムスタンプ関数の日付部分](Dateparts_for_datetime_functions.md)
# ADD\$1MONTHS 関数
ADD\$1MONTHS は日付またはタイムスタンプの値または式に、指定された月数を加算します。[DATE\$1ADD](DATE_ADD_function.md) 関数は同様の機能を提供します。
## 構文
```
ADD_MONTHS( {date | timestamp}, integer)
```
## 引数
*date* \$1 *timestamp*
日付またはタイムスタンプの列、あるいは暗黙的に日付またはタイムスタンプに変換される式。date がその月の最終日である場合、または結果の月が短い場合、関数は結果に月の最終日を返します。その他の日付の場合、結果には date 式と同じ日数が含まれます。
*integer*
正または負の整数。負の数を使用し、日付から月を削除します。
## 戻り型
TIMESTAMP
## 例
次のクエリは、TRUNC 関数内の ADD\$1MONTHS 関数を使用します。TRUNC 関数は、ADD\$1MONTHS の結果から日付の時刻を削除します。ADD\$1MONTHS 関数は CALDATE 列の値ごとに 12 か月を追加します。
```
select distinct trunc(add_months(caldate, 12)) as calplus12,
trunc(caldate) as cal
from date
order by 1 asc;
calplus12 | cal
------------+------------
2009-01-01 | 2008-01-01
2009-01-02 | 2008-01-02
2009-01-03 | 2008-01-03
...
(365 rows)
```
次の例は、ADD\$1MONTHS 関数が異なる日数の月を持つ日付で実行される動作を示しています。
```
select add_months('2008-03-31',1);
add_months
---------------------
2008-04-30 00:00:00
(1 row)
select add_months('2008-04-30',1);
add_months
---------------------
2008-05-31 00:00:00
(1 row)
```
# CONVERT\$1TIMEZONE 関数
CONVERT\$1TIMEZONE は、タイムスタンプのタイムゾーンを別のタイムゾーンに変換します。この関数は夏時間に合わせて自動的に調整されます。
## 構文
```
CONVERT_TIMEZONE ( ['source_timezone',] 'target_timezone', 'timestamp')
```
## 引数
*source\$1timezone*
(オプション) 現在のタイムスタンプのタイムゾーン。デフォルトは UTC です。
*target\$1timezone*
新しいタイムスタンプのタイムゾーン。
*timestamp*
タイムスタンプの列、あるいは暗黙的にタイムスタンプに変換される式。
## 戻り型
TIMESTAMP
## 例
次の例は、タイムスタンプ値をデフォルトの UTC タイムゾーンから PST に変換します。
```
select convert_timezone('PST', '2008-08-21 07:23:54');
convert_timezone
------------------------
2008-08-20 23:23:54
```
次の例は、LISTTIME 列のタイムスタンプ値をデフォルトの UTC タイムゾーンから PST に変換します。タイムスタンプが夏時間の期間内であっても、変換後のタイムゾーンが略名 (PST) で指定されているため、標準時間に変換されます。
```
select listtime, convert_timezone('PST', listtime) from listing
where listid = 16;
listtime | convert_timezone
--------------------+-------------------
2008-08-24 09:36:12 2008-08-24 01:36:12
```
次の例は、タイムスタンプの LISTTIME 列をデフォルトの UTC タイムゾーンから US/Pacific タイムゾーンに変換します。変換後のタイムゾーンはタイムゾーン名で指定されており、タイムスタンプは夏時間の期間内であるため、この関数は夏時間を返します。
```
select listtime, convert_timezone('US/Pacific', listtime) from listing
where listid = 16;
listtime | convert_timezone
--------------------+---------------------
2008-08-24 09:36:12 | 2008-08-24 02:36:12
```
次の例は、タイムスタンプの文字列を EST から PST に変換します。
```
select convert_timezone('EST', 'PST', '20080305 12:25:29');
convert_timezone
-------------------
2008-03-05 09:25:29
```
次の例は、変換後のタイムゾーンがタイムゾーン名 (America/New\$1York) で指定されており、タイムスタンプが標準時間の期間内にあるため、タイムスタンプを米国東部標準時に変換します。
```
select convert_timezone('America/New_York', '2013-02-01 08:00:00');
convert_timezone
---------------------
2013-02-01 03:00:00
(1 row)
```
次の例は、変換後のタイムゾーンがタイムゾーン名 (America/New\$1York) で指定されており、タイムスタンプが夏時間の期間内にあるため、タイムスタンプを米国東部夏時間に変換します。
```
select convert_timezone('America/New_York', '2013-06-01 08:00:00');
convert_timezone
---------------------
2013-06-01 04:00:00
(1 row)
```
次の例は、オフセットの使用を示しています。
```
SELECT CONVERT_TIMEZONE('GMT','NEWZONE +2','2014-05-17 12:00:00') as newzone_plus_2,
CONVERT_TIMEZONE('GMT','NEWZONE-2:15','2014-05-17 12:00:00') as newzone_minus_2_15,
CONVERT_TIMEZONE('GMT','America/Los_Angeles+2','2014-05-17 12:00:00') as la_plus_2,
CONVERT_TIMEZONE('GMT','GMT+2','2014-05-17 12:00:00') as gmt_plus_2;
newzone_plus_2 | newzone_minus_2_15 | la_plus_2 | gmt_plus_2
---------------------+---------------------+---------------------+---------------------
2014-05-17 10:00:00 | 2014-05-17 14:15:00 | 2014-05-17 10:00:00 | 2014-05-17 10:00:00
(1 row)
```
# CURRENT\$1DATE 関数
CURRENT\$1DATE は、現在のセッションのタイムゾーン (デフォルトは UTC) の日付をデフォルト形式 YYYY-MM-DD で返します。
**注記**
CURRENT\$1DATE は、現在のステートメントの開始日ではなく、現在のトランザクションの開始日を返します。複数のステートメントを含むトランザクションを 2008 年 10 月 1 日 23:59 に開始し、CURRENT\$1DATE を含むステートメントが 2008 年 10 月 2 日 00:00 に実行されるシナリオを考えてみましょう。CURRENT\$1DATE は `10/02/08` ではなく、`10/01/08` を返します。
## 構文
```
CURRENT_DATE
```
## 戻り型
DATE
## 例
次の例では、現在の日付 ( 関数 AWS リージョン が実行される ) を返します。
```
select current_date;
date
------------
2008-10-01
```
# CURRENT\$1TIMESTAMP 関数
CURRENT\$1TIMESTAMP は、日付、時刻、および (オプションで) ミリ秒またはマイクロ秒を含む現在の日付と時刻を返します。
この関数は、イベントのタイムスタンプの記録、時間ベースの計算の実行、日付/時刻列の入力など、現在の日付と時刻を取得する必要がある場合に便利です。
## 構文
```
current_timestamp()
```
## 戻り型
CURRENT\$1TIMESTAMP 関数は DATE を返します。
## 例
次の例では、クエリが実行された時点の現在の日時を返します。2020 年 4 月 25 日、15:49:11.914 (午後 3:49:11.914)。
```
SELECT current_timestamp();
2020-04-25 15:49:11.914
```
次の の例では、`squirrels`テーブルの各行の現在の日付と時刻を取得します。
```
SELECT current_timestamp() FROM squirrels
```
# DATE\$1ADD 関数
start\$1date から num\$1days の日付を返します。
## 構文
```
date_add(start_date, num_days)
```
## 引数
*start\$1date*
開始日の値。
*num\$1days*
追加する日数 (整数）。正の数値は日数を加算し、負の数値は日数を減算します。
## 戻り型
DATE
## 例
次の例では、日付に 1 日を追加します。
```
SELECT date_add('2016-07-30', 1);
Result:
2016-07-31
```
次の例では、複数日を追加します。
```
SELECT date_add('2016-07-30', 5);
Result:
2016-08-04
```
## 使用に関する注意事項
このドキュメントは、Spark SQL の DATE\$1ADD 関数を対象としています。この関数は、他の SQL バリアントと比較して、日付に日数を追加するシンプルなインターフェイスを提供します。月や年などの他の間隔を追加するには、異なる関数が必要になる場合があります。
# DATE\$1DIFF 関数
DATE\$1DIFF は、2 つの日付または時刻式の日付部分の差を返します。
## 構文
```
date_diff(endDate, startDate)
```
## 引数
*endDate*
DATE 式。
*startDate*
DATE 式。
## 戻り型
BIGINT
## DATE 列の例
次の例では、2 つの日付リテラル値の間の差 (週単位) を取得します。
```
select date_diff(week,'2009-01-01','2009-12-31') as numweeks;
numweeks
----------
52
(1 row)
```
次の例は、2 つの日付リテラル値の差 (時間単位) を検出します。日付の時刻値を指定しなかった場合、デフォルトで 00:00:00 に設定されます。
```
select date_diff(hour, '2023-01-01', '2023-01-03 05:04:03');
date_diff
----------
53
(1 row)
```
次の例は、2 つの日付リテラル TIMESTAMETZ 値の差 (日単位) を検出します。
```
Select date_diff(days, 'Jun 1,2008 09:59:59 EST', 'Jul 4,2008 09:59:59 EST')
date_diff
----------
33
```
次の例は、テーブルの同じ行の 2 つの日付の差 (日単位) を検出します。
```
select * from date_table;
start_date | end_date
-----------+-----------
2009-01-01 | 2009-03-23
2023-01-04 | 2024-05-04
(2 rows)
select date_diff(day, start_date, end_date) as duration from date_table;
duration
---------
81
486
(2 rows)
```
次の例では、過去のリテラル値と今日の日付の間の差 (四半期単位) を取得します。この例では、現在の日付を 2008 年 6 月 5 日とします。完全名または略名で日付部分に名前を付けることができます。DATE\$1DIFF 関数のデフォルトの列名は DATE\$1DIFF です。
```
select date_diff(qtr, '1998-07-01', current_date);
date_diff
-----------
40
(1 row)
```
次の例では、SALES テーブルと LISTING テーブルを結合し、リスト 1000 から 1005 に対してチケットをリストしてから何日後に販売されたかを計算します。これらのリストの販売を最長の待機期間は 15 日であり、最小は 1 日より短いです (0 日)。
```
select priceperticket,
date_diff(day, listtime, saletime) as wait
from sales, listing where sales.listid = listing.listid
and sales.listid between 1000 and 1005
order by wait desc, priceperticket desc;
priceperticket | wait
---------------+------
96.00 | 15
123.00 | 11
131.00 | 9
123.00 | 6
129.00 | 4
96.00 | 4
96.00 | 0
(7 rows)
```
この例は、販売者が任意およびすべてのチケット販売を待機する平均時間を計算します。
```
select avg(date_diff(hours, listtime, saletime)) as avgwait
from sales, listing
where sales.listid = listing.listid;
avgwait
---------
465
(1 row)
```
## TIME 列の例
次のテーブルの TIME\$1TEST の例には、3 つの値が挿入された列 TIME\$1VAL (タイプ TIME) があります。
```
select time_val from time_test;
time_val
---------------------
20:00:00
00:00:00.5550
00:58:00
```
次の例では、TIME\$1VAL 列と時刻リテラル間の時間数の差を検出します。
```
select date_diff(hour, time_val, time '15:24:45') from time_test;
date_diff
-----------
-5
15
15
```
次の例では、2 つのリテラル時間値の分数の差を検出します。
```
select date_diff(minute, time '20:00:00', time '21:00:00') as nummins;
nummins
----------
60
```
## TIMETZ 列の例
次のテーブルの TIMETZ\$1TEST の例には、3 つの値が挿入された列 TIMETZ\$1VAL (タイプ TIMETZ) があります。
```
select timetz_val from timetz_test;
timetz_val
------------------
04:00:00+00
00:00:00.5550+00
05:58:00+00
```
次の例では、TIMETZ リテラルと timetz\$1val の間の時間数の差を検出します。
```
select date_diff(hours, timetz '20:00:00 PST', timetz_val) as numhours from timetz_test;
numhours
----------
0
-4
1
```
次の例では、2 つのリテラル TIMETZ 値間の時間数の差を検出します。
```
select date_diff(hours, timetz '20:00:00 PST', timetz '00:58:00 EST') as numhours;
numhours
----------
1
```
# DATE\$1PART 関数
DATE\$1PART は式から日付部分の値を抽出します。DATE\$1PART は PGDATE\$1PART 関数のシノニムです。
## 構文
```
datepart(field, source)
```
## 引数
*field*
ソースのどの部分を抽出する必要があり、サポートされている文字列値は同等の関数 EXTRACT のフィールドと同じです。
*source*
フィールドを抽出する DATE または INTERVAL 列。
## 戻り型
*フィールド*が「SECOND」の場合、DECIMAL(8, 6)。それ以外の場合は、INTEGER。
## 例
次の例では、日付値から日 (DOY) を抽出します。出力は、日付「2019-08-12」の日が であることを示しています`224`。つまり、2019 年 8 月 12 日は 2019 年 224 日です。
```
SELECT datepart('doy', DATE'2019-08-12');
224
```
# DATE\$1TRUNC 関数
DATE\$1TRUNC 関数は、指定した日付部分 (時、日、月など) に基づいてタイムスタンプの式またはリテラルを切り捨てます。
## 構文
```
date_trunc(format, datetime)
```
## 引数
*format*
切り捨てられる単位を表す形式。有効な形式は次のとおりです。
+ 「YEAR」、「YYYY」、「YY」 - ts が属する年の最初の日付に切り捨て、タイムパートはゼロになります
+ 「QUARTER」 - ts が属する四半期の最初の日付に切り捨て、タイムパートはゼロになります
+ 「MONTH」、「MM」、「MON」 - ts が属する月の最初の日付に切り捨て、タイムパートはゼロになります
+ 「WEEK」 - ts が属する週の月曜日に切り捨て、タイムパートはゼロになります
+ 「DAY」、「DD」 - 時間帯をゼロにします
+ 「時間」 - 分と秒を分数でゼロにします
+ 「MINUTE」- 小数部分で秒をゼロにします
+ 「SECOND」 - 2 番目の小数部分をゼロにします
+ 「MILLISECOND」 - マイクロ秒をゼロにします
+ 「MICROSECOND」 - すべてが残ります
*ts*
日時値
## 戻り型
形式モデルで指定された単位に切り捨てられたタイムスタンプ *ts* を返します。
## 例
次の例では、日付値を年初に切り捨てます。出力は、日付「2015-03-05」が 2015 年の初めである「2015-01-01」に切り捨てられたことを示しています。
```
SELECT date_trunc('YEAR', '2015-03-05');
date_trunc
-----------
2015-01-01
```
# DAY 関数
DAY 関数は、日付/タイムスタンプの日を返します。
日付抽出関数は、日付ベースの計算、データのフィルタリング、日付値の書式設定など、日付またはタイムスタンプの特定のコンポーネントを操作する必要がある場合に便利です。
## 構文
```
day(date)
```
## 引数
*date*
DATE 式または TIMESTAMP 式。
## 戻り値
DAY 関数は INTEGER を返します。
## 例
次の例では、入力日 から日付 (`30`) を抽出します`'2009-07-30'`。
```
SELECT day('2009-07-30');
30
```
次の例では、`squirrels`テーブルの `birthday`列から日付を抽出し、結果を SELECT ステートメントの出力として返します。このクエリの出力は、`squirrels`テーブル内の行ごとに 1 つずつ、各リスの誕生日を表す日の値のリストになります。
```
SELECT day(birthday) FROM squirrels
```
# DAYOFMONTH 関数
DAYOFMONTH 関数は、日付/タイムスタンプ (月と年に応じて 1～31 の値) の日を返します。
DAYOFMONTH 関数は DAY 関数と似ていますが、名前と動作が少し異なります。DAY 関数はより一般的に使用されますが、代わりに DAYOFMONTH 関数を使用できます。このタイプのクエリは、日付ベースの分析を実行したり、さらに処理またはレポートするために日付の特定のコンポーネントを抽出するなど、日付またはタイムスタンプデータを含むテーブルでフィルタリングしたりする必要がある場合に役立ちます。
## 構文
```
dayofmonth(date)
```
## 引数
*date*
DATE 式または TIMESTAMP 式。
## 戻り値
DAYOFMONTH 関数は INTEGER を返します。
## 例
次の例では、入力日 から日付 (`30`) を抽出します`'2009-07-30'`。
```
SELECT dayofmonth('2009-07-30');
30
```
次の例では、DAYOFMONTH 関数を`squirrels`テーブルの `birthday`列に適用します。`squirrels` テーブルの各行について、`birthday`列の曜日が抽出され、SELECT ステートメントの出力として返されます。このクエリの出力は、`squirrels`テーブル内の行ごとに 1 つずつ、各リスの誕生日を表す日の値のリストになります。
```
SELECT dayofmonth(birthday) FROM squirrels
```
# DAYOFWEEK 関数
DAYOFWEEK 関数は、日付またはタイムスタンプを入力として受け取り、曜日を数値 (日曜日の場合は 1、月曜日の場合は 2、土曜日の場合は 7) として返します。
この日付抽出関数は、日付ベースの計算、データのフィルタリング、日付値の書式設定など、日付またはタイムスタンプの特定のコンポーネントを操作する必要がある場合に便利です。
## 構文
```
dayofweek(date)
```
## 引数
*date*
DATE 式または TIMESTAMP 式。
## 戻り値
DAYOFWEEK 関数は INTEGER を返します。
1 = 日曜日
2 = 月曜日
3 = 火曜日
4 = 水曜日
5 = 木曜日
6 = 金曜日
7 = 土曜日
## 例
次の例では、この日付から曜日を抽出します。この日付は 5 (木曜日を表します) です。
```
SELECT dayofweek('2009-07-30');
5
```
次の例では、`squirrels`テーブルの `birthday`列から曜日を抽出し、結果を SELECT ステートメントの出力として返します。このクエリの出力は、`squirrels`テーブル内の行ごとに 1 つずつ、曜日の値のリストになり、各リスの生年月日の曜日を表します。
```
SELECT dayofweek(birthday) FROM squirrels
```
# DAYOFYEAR 関数
DAYOFYEAR 関数は、日付またはタイムスタンプを入力として受け取り、その年の日 (年とうるう年かどうかに応じて 1～366 の値) を返す日付抽出関数です。
この関数は、日付ベースの計算、データのフィルタリング、日付値の書式設定など、日付またはタイムスタンプの特定のコンポーネントを操作する必要がある場合に便利です。
## 構文
```
dayofyear(date)
```
## 引数
*date*
DATE 式または TIMESTAMP 式。
## 戻り値
DAYOFYEAR 関数は INTEGER を返します (年とうるう年かどうかに応じて 1～366)。
## 例
次の例では、入力日 から日 (`100`) を抽出します`'2016-04-09'`。
```
SELECT dayofyear('2016-04-09');
100
```
次の例では、`squirrels`テーブルの `birthday`列から曜日を抽出し、結果を SELECT ステートメントの出力として返します。
```
SELECT dayofyear(birthday) FROM squirrels
```
# EXTRACT 関数
EXTRACT 関数は、TIMESTAMP、TIMESTAMPTZ、TIME、または TIMETZ 値から日付または時刻部分を返します。例としては、タイムスタンプの日、月、年、時、分、秒、ミリ秒、マイクロ秒などがあります。
## 構文
```
EXTRACT(datepart FROM source)
```
## 引数
*datepart*
日、月、年、時、分、秒、ミリ秒、マイクロ秒など、抽出する日付または時刻のサブフィールド。有効な値については、「[日付関数またはタイムスタンプ関数の日付部分](Dateparts_for_datetime_functions.md)」を参照してください。
*source*
評価結果が TIMESTAMP、TIMESTAMPTZ、TIME、または TIMETZ のデータ型になる列または式。
## 戻り型
*source* 値が TIMESTAMP、TIME、または TIMETZ のデータ型として評価される場合は INTEGER。
*source* 値がデータ型 TIMESTAMPTZ として評価される場合は、DOUBLE PRECISION。
## TIME の例
次のテーブルの TIME\$1TEST の例には、3 つの値が挿入された列 TIME\$1VAL (タイプ TIME) があります。
```
select time_val from time_test;
time_val
---------------------
20:00:00
00:00:00.5550
00:58:00
```
次の例は、各 time\$1val から分を抽出します。
```
select extract(minute from time_val) as minutes from time_test;
minutes
-----------
0
0
58
```
次の例は、各 time\$1val から時間を抽出します。
```
select extract(hour from time_val) as hours from time_test;
hours
-----------
20
0
0
```
# FROM\$1UTC\$1TIMESTAMP 関数
FROM\$1UTC\$1TIMESTAMP 関数は、入力日を UTC (協定世界時) から指定されたタイムゾーンに変換します。
この関数は、日付と時刻の値を UTC から特定のタイムゾーンに変換する必要がある場合に便利です。これは、世界のさまざまな地域から発信され、適切な現地時間で提示する必要があるデータを使用する場合に重要です。
## 構文
```
from_utc_timestamp(timestamp, timezone
```
## 引数
*timestamp*
UTC タイムスタンプを持つ TIMESTAMP 式。
*timezone*
入力日付またはタイムスタンプを変換する有効なタイムゾーンである STRING 式。
## 戻り値
FROM\$1UTC\$1TIMESTAMP 関数は TIMESTAMP を返します。
## 例
次の の例では、入力日付を UTC から指定されたタイムゾーン (`'Asia/Seoul'`) に変換します。この場合は UTC の 9 時間前です。結果の出力は、ソウルタイムゾーンの日時です`2016-08-31 09:00:00`。
```
SELECT from_utc_timestamp('2016-08-31', 'Asia/Seoul');
2016-08-31 09:00:00
```
# HOUR 関数
HOUR 関数は、時間またはタイムスタンプを入力として受け取り、時間コンポーネント (0～23 の値) を返す時間抽出関数です。
この時間抽出関数は、時間ベースの計算、データのフィルタリング、時間値のフォーマットなど、時間またはタイムスタンプの特定のコンポーネントを操作する必要がある場合に便利です。
## 構文
```
hour(timestamp)
```
## 引数
*timestamp*
TIMESTAMP 式。
## 戻り値
HOUR 関数は INTEGER を返します。
## 例
次の の例では、入力タイムスタンプ から時間コンポーネント (`12`) を抽出します`'2009-07-30 12:58:59'`。
```
SELECT hour('2009-07-30 12:58:59');
12
```
# MINUTE 関数
MINUTE 関数は、時間またはタイムスタンプを入力として受け取り、分コンポーネント (0～60 の値) を返す時間抽出関数です。
## 構文
```
minute(timestamp)
```
## 引数
*timestamp*
TIMESTAMP 式または有効なタイムスタンプ形式の STRING。
## 戻り値
MINUTE 関数は INTEGER を返します。
## 例
次の の例では、入力タイムスタンプ から分コンポーネント (`58`) を抽出します`'2009-07-30 12:58:59'`。
```
SELECT minute('2009-07-30 12:58:59');
58
```
# MONTH 関数
MONTH 関数は、時間またはタイムスタンプを入力として受け取り、月コンポーネント (0～12 の値) を返す時間抽出関数です。
## 構文
```
month(date)
```
## 引数
*date*
TIMESTAMP 式または有効なタイムスタンプ形式の STRING。
## 戻り値
MONTH 関数は INTEGER を返します。
## 例
次の例では、入力タイムスタンプ から月コンポーネント (`7`) を抽出します`'2016-07-30'`。
```
SELECT month('2016-07-30');
7
```
# SECOND 関数
SECOND 関数は、時間またはタイムスタンプを入力として受け取り、2 番目のコンポーネント (0～60 の値) を返す時間抽出関数です。
## 構文
```
second(timestamp)
```
## 引数
*timestamp*
TIMESTAMP 式。
## 戻り値
SECOND 関数は INTEGER を返します。
## 例
次の例では、入力タイムスタンプ から 2 番目のコンポーネント (`59`) を抽出します`'2009-07-30 12:58:59'`。
```
SELECT second('2009-07-30 12:58:59');
59
```
# TIMESTAMP 関数
TIMESTAMP 関数は値 (通常は数値) を受け取り、タイムスタンプデータ型に変換します。
この関数は、時刻または日付を表す数値をタイムスタンプデータ型に変換する必要がある場合に便利です。これは、Unix タイムスタンプやエポック時間などの数値形式で保存されているデータを使用する場合に役立ちます。
## 構文
```
timestamp(expr)
```
## 引数
expr**
TIMESTAMP にキャストできる任意の式。
## 戻り値
TIMESTAMP 関数は TIMESTAMP を返します。
## 例
次の例では、数値 Unix タイムスタンプ (`1632416400`) を対応するタイムスタンプデータ型に変換します。2021 年 9 月 22 日午後 12:00:00 UTC。
```
SELECT timestamp(1632416400);
2021-09-22 12:00:00 UTC
```
# TO\$1TIMESTAMP 関数
TO\$1TIMESTAMP は TIMESTAMP 文字列を TIMESTAMPTZ に返します。
## 構文
```
to_timestamp (timestamp)
```
```
to_timestamp (timestamp, format)
```
## 引数
*timestamp*
タイムスタンプ文字列、またはタイムスタンプ文字列にキャストできるデータ型。
*format*
Spark の日時パターンに一致する文字列リテラル。有効な日時パターンについては、[「フォーマットと解析の日時パターン](https://spark.apache.org/docs/latest/sql-ref-datetime-pattern.html)」を参照してください。
## 戻り型
TIMESTAMP
## 例
次の例は、TO\$1TIMESTAMP 関数を使用して TIMESTAMP 文字列を TIMESTAMP に変換する方法を示しています。
```
select current_timestamp() as timestamp, to_timestamp( current_timestamp(), 'YYYY-MM-DD HH24:MI:SS') as second;
timestamp | second
-------------------------- ----------------------
2021-04-05 19:27:53.281812 | 2021-04-05 19:27:53+00
```
日付の TO\$1TIMESTAMP 部分を渡すこともできます。残りの日付部分はデフォルト値に設定されます。時刻は出力に含まれません。
```
SELECT TO_TIMESTAMP('2017','YYYY');
to_timestamp
--------------------------
2017-01-01 00:00:00+00
```
次の SQL ステートメントは、文字列「2011-12-18 24:38:15」を TIMESTAMP に変換します。結果は、時間数が 24 時間を超えているため、翌日になる TIMESTAMP になります。
```
select to_timestamp('2011-12-18 24:38:15', 'YYYY-MM-DD HH24:MI:SS');
to_timestamp
----------------------
2011-12-19 00:38:15+00
```
# YEAR 関数
YEAR 関数は、日付またはタイムスタンプを入力として受け取り、年コンポーネント (4 桁の数字) を返す日付抽出関数です。
## 構文
```
year(date)
```
## 引数
*date*
DATE 式または TIMESTAMP 式。
## 戻り値
YEAR 関数は INTEGER を返します。
## 例
次の の例では、入力日 から年コンポーネント (`2016`) を抽出します`'2016-07-30'`。
```
SELECT year('2016-07-30');
2016
```
次の例では、`squirrels`テーブルの `birthday`列から年コンポーネントを抽出し、結果を SELECT ステートメントの出力として返します。このクエリの出力は、`squirrels`テーブル内の行ごとに 1 つずつ、各リスの誕生日を表す年値のリストになります。
```
SELECT year(birthday) FROM squirrels
```
# 日付関数またはタイムスタンプ関数の日付部分
次のテーブルは、次の関数に対する引数として受け取る、日付部分および時刻部分の名前と略名を指定します。
+ DATE\$1ADD
+ DATE\$1DIFF
+ DATE\$1PART
+ EXTRACT
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/clean-rooms/latest/sql-reference/Dateparts_for_datetime_functions.html)
## 結果のバリエーション (秒、ミリ秒、マイクロ秒）
異なる日付関数が秒、ミリ秒、またはマイクロ秒を日付部分として指定する場合、クエリ結果にわずかな違いが生じます。
+ EXTRACT 関数は、上位および下位の日付部分は無視し、指定された日付部分のみの整数を返します。指定された日付部分が秒の場合、ミリ秒およびマイクロ秒は結果に含まれません。指定された日付部分がミリ秒の場合、秒およびマイクロ秒は結果に含まれません。指定された日付部分がマイクロ秒の場合、秒およびミリ秒は結果に含まれません。
+ DATE\$1PART 関数は、指定された日付部分にかかわらず、タイムスタンプの完全な秒部分を返します。必要に応じて小数値または整数を返します。
## CENTURY、EPOCH、DECADE、および MIL ノート
CENTURY または CENTURIES
AWS Clean Rooms は CENTURY を*「\$1\$1\$11*」で始まり、「」で終わるように解釈します`###0`。
```
select extract (century from timestamp '2000-12-16 12:21:13');
date_part
-----------
20
(1 row)
select extract (century from timestamp '2001-12-16 12:21:13');
date_part
-----------
21
(1 row)
```
EPOCH
EPOCH の AWS Clean Rooms 実装は、クラスターが存在するタイムゾーンとは無関係に 1970-01-01 00:00:00.000000 に関連しています。クラスターが設置されているタイムゾーンによって、時差による結果を補正する必要がある場合があります。
DECADE または DECADES
AWS Clean Rooms は、共通カレンダーに基づいて DECADE または DECADES DATEPART を解釈します。例えば、共通カレンダーが年 1 から始まるため、最初の 10 年 (decade 1) は 0001-01-01 から 0009-12-31 であり、2 番目の 10 年 (decade 2) は 0010-01-01 から 0019-12-31 です。例えば、decade 201 は 2000-01-01 から 2009-12-31 の期間に及びます。
```
select extract(decade from timestamp '1999-02-16 20:38:40');
date_part
-----------
200
(1 row)
select extract(decade from timestamp '2000-02-16 20:38:40');
date_part
-----------
201
(1 row)
select extract(decade from timestamp '2010-02-16 20:38:40');
date_part
-----------
202
(1 row)
```
MIL または MILS
AWS Clean Rooms は MIL を解釈して、*\$1001* 年の最初の日に始まり、最後の日に終わります`#000`。
```
select extract (mil from timestamp '2000-12-16 12:21:13');
date_part
-----------
2
(1 row)
select extract (mil from timestamp '2001-12-16 12:21:13');
date_part
-----------
3
(1 row)
```
# 暗号化および復号関数
暗号化および復号関数は、SQL デベロッパーが読み取り可能なプレーンテキスト形式と読み取り不可能な暗号化テキスト形式の間で機密データを変換することで、不正アクセスや誤用から保護するのに役立ちます。
AWS Clean Rooms Spark SQL は、次の暗号化および復号関数をサポートしています。
**Topics**
+ [AES\$1ENCRYPT 関数](AES_ENCRYPT.md)
+ [AES\$1DECRYPT 関数](AES_DECRYPT.md)
# AES\$1ENCRYPT 関数
AES\$1ENCRYPT 関数は、Advanced Encryption Standard (AES) アルゴリズムを使用してデータを暗号化するために使用されます。
## 構文
```
aes_encrypt(expr, key[, mode[, padding[, iv[, aad]]]])
```
## 引数
expr**
暗号化するバイナリ値。
*key*
データの暗号化に使用するパスフレーズ。
16、24、32 ビットのキー長がサポートされています。
*モード*
メッセージの暗号化に使用するブロック暗号モードを指定します。
有効なモード: ECB (電子 CodeBook)、GCM (Galois/Counter Mode)、CBC (Cipher-Block Chaining)。
*パディング*
長さがブロックサイズの倍数ではないメッセージをパディングする方法を指定します。
有効な値: PKCS、NONE、DEFAULT。
DEFAULT パディングは、ECB の場合は PKCS (パブリックキー暗号化標準）、GCM の場合は NONE、CBC の場合は PKCS を意味します。
（*モード*、*パディング*) のサポートされている組み合わせは、 ('ECB'、'PKCS')、 ('GCM'、'NONE')、および ('CBC'、'PKCS') です。
*iv*
オプションの初期化ベクトル (IV)。CBC モードと GCM モードでのみサポートされます。
有効な値: GCM の場合は 12 バイト、CBC の場合は 16 バイト。
*aad*
オプションの追加の認証データ (AAD)。GCM モードでのみサポートされます。これは任意の自由形式の入力にすることができ、暗号化と復号の両方に指定する必要があります。
## 戻り型
AES\$1ENCRYPT 関数は、指定されたパディングで指定されたモードで AES を使用して暗号化された *expr* の値を返します。
## 例
次の例は、Spark SQL AES\$1ENCRYPT 関数を使用して、指定された暗号化キーを使用してデータの文字列 (この場合は「Spark」という単語) を安全に暗号化する方法を示しています。結果として得られる暗号文は Base64-encodedされ、保存または送信が容易になります。
```
SELECT base64(aes_encrypt('Spark', 'abcdefghijklmnop'));
4A5jOAh9FNGwoMeuJukfllrLdHEZxA2DyuSQAWz77dfn
```
次の例は、Spark SQL AES\$1ENCRYPT 関数を使用して、指定された暗号化キーを使用してデータの文字列 (この場合は「Spark」という単語) を安全に暗号化する方法を示しています。結果として得られる暗号文は 16 進形式で表されます。これは、データストレージ、送信、デバッグなどのタスクに役立ちます。
```
SELECT hex(aes_encrypt('Spark', '0000111122223333'));
83F16B2AA704794132802D248E6BFD4E380078182D1544813898AC97E709B28A94
```
次の例は、Spark SQL AES\$1ENCRYPT 関数を使用して、指定された暗号化キー、暗号化モード、パディングモードを使用して、データの文字列 (この場合は「Spark SQL」) を安全に暗号化する方法を示しています。結果として得られる暗号文は Base64-encodedされ、保存または送信が容易になります。
```
SELECT base64(aes_encrypt('Spark SQL', '1234567890abcdef', 'ECB', 'PKCS'));
3lmwu+Mw0H3fi5NDvcu9lg==
```
# AES\$1DECRYPT 関数
AES\$1DECRYPT 関数は、Advanced Encryption Standard (AES) アルゴリズムを使用してデータを復号するために使用されます。
## 構文
```
aes_decrypt(expr, key[, mode[, padding[, aad]]])
```
## 引数
expr**
復号するバイナリ値。
*key*
データの復号に使用するパスフレーズ。
パスフレーズは、暗号化された値の生成に最初に使用されたキーと一致し、16、24、または 32 バイトの長さである必要があります。
*モード*
メッセージの復号に使用するブロック暗号モードを指定します。
有効なモード: ECB、GCM、CBC。
*パディング*
長さがブロックサイズの倍数ではないメッセージをパディングする方法を指定します。
有効な値: PKCS、NONE、DEFAULT。
DEFAULT パディングは、ECB の場合は PKCS、GCM の場合は NONE、CBC の場合は PKCS を意味します。
*aad*
オプションの追加の認証データ (AAD)。GCM モードでのみサポートされます。これは任意の自由形式の入力にすることができ、暗号化と復号の両方に指定する必要があります。
## 戻り型
パディング付きのモードで AES を使用して、復号された *expr* の値を返します。
## 例
次の例は、Spark SQL AES\$1ENCRYPT 関数を使用して、指定された暗号化キーを使用してデータの文字列 (この場合は「Spark」という単語) を安全に暗号化する方法を示しています。結果として得られる暗号文は Base64-encodedされ、保存または送信が容易になります。
```
SELECT base64(aes_encrypt('Spark', 'abcdefghijklmnop'));
4A5jOAh9FNGwoMeuJukfllrLdHEZxA2DyuSQAWz77dfn
```
次の例は、Spark SQL AES\$1DECRYPT 関数を使用して、以前に暗号化され Base64-encodedされたデータを復号する方法を示しています。復号プロセスでは、元のプレーンテキストデータを正常に復元するために、正しい暗号化キーとパラメータ (暗号化モードとパディングモード) が必要です。
```
SELECT aes_decrypt(unbase64('3lmwu+Mw0H3fi5NDvcu9lg=='), '1234567890abcdef', 'ECB', 'PKCS');
Spark SQL
```
# ハッシュ関数
ハッシュ関数は、数値入力値を別の値に変換する数学関数です。
AWS Clean Rooms Spark SQL は、次のハッシュ関数をサポートしています。
**Topics**
+ [MD5 関数](s_MD5.md)
+ [SHA 関数](s_SHA.md)
+ [SHA1 関数](s_SHA1.md)
+ [SHA2 関数](s_SHA2.md)
+ [xxHASH64 関数](xxhash64.md)
# MD5 関数
MD5 暗号化ハッシュ関数を使用して、可変長文字列を 32 文字の文字列に変換します。この 32 文字の文字列は、128 ビットチェックサムの 16 進値をテキストで表記したものです。
## 構文
```
MD5(string)
```
## 引数
*string*
可変長文字列。
## 戻り型
MD5 関数は、32 文字の文字列を返します。この 32 文字の文字列は、128 ビットチェックサムの 16 進値をテキストで表記したものです。
## 例
以下の例では、文字列 'AWS Clean Rooms' の 128 ビット値を示します。
```
select md5('AWS Clean Rooms');
md5
----------------------------------
f7415e33f972c03abd4f3fed36748f7a
(1 row)
```
# SHA 関数
SHA1 関数のシノニム。
「[SHA1 関数](s_SHA1.md)」を参照してください。
# SHA1 関数
SHA1 関数は、SHA1 暗号化ハッシュ関数を使用して、可変長文字列を 40 文字の文字列に変換します。この 40 文字の文字列は、160 ビットのチェックサムの 16 進値をテキストで表記したものです。
## 構文
SHA1 は [SHA 関数](s_SHA.md) のシノニムです。
```
SHA1(string)
```
## 引数
*string*
可変長文字列。
## 戻り型
SHA1 関数は、40 文字の文字列を返します。この 40 文字の文字列は、160 ビットのチェックサムの 16 進値をテキストで表記したものです。
## 例
以下の例は、単語 'AWS Clean Rooms' の 160 ビット値を返します。
```
select sha1('AWS Clean Rooms');
```
# SHA2 関数
SHA2 関数は、SHA2 暗号化ハッシュ関数を使用して、可変長文字列を文字列に変換します。この文字列は、指定されたビット数のチェックサムの 16 進値をテキストで表記したものです。
## 構文
```
SHA2(string, bits)
```
## 引数
*string*
可変長文字列。
*integer*
ハッシュ関数のビット数。有効な値は 0 (256 と同じ)、224、256、384、および 512 です。
## 戻り型
SHA2 関数は、チェックサムの 16 進値をテキストで表記した文字列を返します。また、ビット数が無効な場合は、空の文字列を返します。
## 例
次の例では、「AWS Clean Rooms」という語の 256 ビット値が返されます。
```
select sha2('AWS Clean Rooms', 256);
```
# xxHASH64 関数
xxhash64 関数は、引数の 64 ビットハッシュ値を返します。
xxhash64() 関数は、高速かつ効率的に設計された非暗号化ハッシュ関数です。多くの場合、データ処理およびストレージアプリケーションでは、データの一意の識別子が必要ですが、データの正確な内容を秘密にする必要はありません。
SQL クエリのコンテキストでは、xxhash64() 関数を次のようなさまざまな目的で使用できます。
+ テーブル内の行の一意の識別子の生成
+ ハッシュ値に基づくデータのパーティション化
+ カスタムインデックス作成またはデータ分散戦略の実装
特定のユースケースは、アプリケーションの要件と処理されるデータによって異なります。
## 構文
```
xxhash64(expr1, expr2, ...)
```
## 引数
*expr1*
任意のタイプの式。
*expr2*
任意のタイプの式。
## 戻り値
引数の 64 ビットハッシュ値 (BIGINT) を返します。ハッシュシードは 42 です。
## 例
次の の例では、指定された入力に基づいて 64 ビットのハッシュ値 (5602566077635097486) を生成します。最初の引数は文字列値で、この場合は「Spark」という単語です。2 番目の引数は、単一の整数値 123 を含む配列です。3 番目の引数は、ハッシュ関数のシードを表す整数値です。
```
SELECT xxhash64('Spark', array(123), 2);
5602566077635097486
```
# Hyperloglog 関数
SQL の HyperLogLog (HLL) 関数は、実際の一意の要素のセットが保存されていない場合でも、大規模なデータセット内の一意の要素 (カーディナリティ) の数を効率的に推定する方法を提供します。
HLL 関数を使用する主な利点は次のとおりです。
+ **メモリ効率**: HLL スケッチは、一意の要素の完全なセットを保存するよりもはるかに少ないメモリを必要とするため、大規模なデータセットに適しています。
+ **分散コンピューティング**: HLL スケッチは複数のデータソースまたは処理ノードにまたがって組み合わせることができるため、効率的な分散一意数推定が可能になります。
+ **おおよその結果**: HLL は、精度とメモリ使用量の間の調整可能なトレードオフ (精度パラメータを使用) により、おおよその一意のカウントの推定を提供します。
これらの関数は、分析、データウェアハウス、リアルタイムストリーム処理アプリケーションなど、一意の項目の数を見積もる必要があるシナリオで特に役立ちます。
AWS Clean Rooms は、次の HLL 関数をサポートしています。
**Topics**
+ [HLL\$1SKETCH\$1AGG 関数](HLL_SKETCH_AGG.md)
+ [HLL\$1SKETCH\$1ESTIMATE 関数](HLL_SKETCH_ESTIMATE.md)
+ [HLL\$1UNION 関数](HLL_UNION.md)
+ [HLL\$1UNION\$1AGG 関数](HLL_UNION_AGG.md)
# HLL\$1SKETCH\$1AGG 関数
HLL\$1SKETCH\$1AGG 集計関数は、指定された列の値から HLL スケッチを作成します。入力式の値をカプセル化する HLLSKETCH データ型を返します。
HLL\$1SKETCH\$1AGG 集計関数は任意のデータ型で動作し、NULL 値を無視します。
テーブルに行がない場合、またはすべての行が NULL の場合、結果のスケッチには `{"version":1,"logm":15,"sparse":{"indices":[],"values":[]}}` などのインデックスと値のペアがありません。
## 構文
```
HLL_SKETCH_AGG (aggregate_expression[, lgConfigK ] )
```
## 引数
*aggregate\$1expression*
一意のカウントが発生する INT、BIGINT、STRING、または BINARY 型の式。`NULL` 値はすべて無視されます。
*lgConfigK*
デフォルトの 12 を含む、4 から 21 までのオプションの INT 定数。K の log-base-2。ここで、K はスケッチのバケットまたはスロットの数です。
## 戻り型
HLL\$1SKETCH\$1AGG 関数は、集計グループ内のすべての入力値を消費および集計したために計算された HyperLogLog スケッチを含む NULL 以外の BINARY バッファを返します。
## 例
次の例では、HyperLogLog (HLL) アルゴリズムを使用して、 `col` 列の値の個別の数を推定します。`hll_sketch_agg(col, 12)` 関数は col 列の値を集計し、精度 12 を使用して HLL スケッチを作成します。次に、 `hll_sketch_estimate()`関数を使用して、生成された HLL スケッチに基づいて個別の値のカウントを推定します。クエリの最終結果は 3 で、`col`列の値の推定個別数を表します。この場合、個別の値は 1、2、3 です。
```
SELECT hll_sketch_estimate(hll_sketch_agg(col, 12))
FROM VALUES (1), (1), (2), (2), (3) tab(col);
3
```
次の例では、HLL アルゴリズムを使用して`col`列の値の個別の数を推定しますが、HLL スケッチの精度値は指定しません。この場合、デフォルトの精度である 14 が使用されます。`hll_sketch_agg(col)` 関数は `col`列の値を取得し、HyperLogLog (HLL) スケッチを作成します。これは、要素の個別の数を推定するために使用できるコンパクトなデータ構造です。`hll_sketch_estimate(hll_sketch_agg(col))` 関数は、前のステップで作成した HLL スケッチを取得し、 `col` 列の値の個別の数の推定値を計算します。クエリの最終結果は 3 で、`col`列の値の推定個別数を表します。この場合、個別の値は 1、2、3 です。
```
SELECT hll_sketch_estimate(hll_sketch_agg(col))
FROM VALUES (1), (1), (2), (2), (3) tab(col);
3
```
# HLL\$1SKETCH\$1ESTIMATE 関数
HLL\$1SKETCH\$1ESTIMATE 関数は HLL スケッチを取得し、スケッチで表される一意の要素の数を推定します。HyperLogLog (HLL) アルゴリズムを使用して、特定の列の一意の値の数の確率的近似をカウントし、HLL\$1SKETCH\$1AGG 関数によって以前に生成されたスケッチバッファと呼ばれるバイナリ表現を消費し、結果を大きな整数として返します。
HLL スケッチアルゴリズムは、大きなデータセットであっても、一意の値のセットをすべて保存することなく、一意の要素の数を効率的に推定する方法を提供します。
`hll_union` 関数と `hll_union_agg`関数は、これらのバッファを入力として消費およびマージすることで、スケッチを組み合わせることもできます。
## 構文
```
HLL_SKETCH_ESTIMATE (hllsketch_expression)
```
## 引数
*hllsketch\$1expression*
HLL\$1SKETCH\$1AGG によって生成されたスケッチを保持する`BINARY`式
## 戻り型
HLL\$1SKETCH\$1ESTIMATE 関数は、入力スケッチで表されるおおよその個別カウントである BIGINT 値を返します。
## 例
次の例では、HyperLogLog (HLL) スケッチアルゴリズムを使用して、`col`列の値の基数 (一意の数) を推定します。`hll_sketch_agg(col, 12)` 関数は `col`列を取得し、12 ビットの精度を使用して HLL スケッチを作成します。HLL スケッチは、セット内の一意の要素の数を効率的に推定できるおおよそのデータ構造です。`hll_sketch_estimate()` 関数は、 によって作成された HLL スケッチ`hll_sketch_agg`を取得し、スケッチによって表される値の基数 (一意の数) を推定します。は 5 行のテストデータセット`FROM VALUES (1), (1), (2), (2), (3) tab(col);`を生成します。この`col`列には 1、1、2、2、3 の値が含まれます。このクエリの結果は、`col`列の値の推定一意数 3 です。
```
SELECT hll_sketch_estimate(hll_sketch_agg(col, 12))
FROM VALUES (1), (1), (2), (2), (3) tab(col);
3
```
次の例と前の例の違いは、精度パラメータ (12 ビット) が`hll_sketch_agg`関数呼び出しで指定されていないことです。この場合、デフォルトの精度である 14 ビットが使用されます。これにより、12 ビットの精度を使用した前の例と比較して、一意のカウントのより正確な推定が得られます。
```
SELECT hll_sketch_estimate(hll_sketch_agg(col))
FROM VALUES (1), (1), (2), (2), (3) tab(col);
3
```
# HLL\$1UNION 関数
HLL\$1UNION 関数は、2 つの HLL スケッチを 1 つの統合スケッチに結合します。HyperLogLog (HLL) アルゴリズムを使用して、2 つのスケッチを 1 つのスケッチに結合します。クエリは、結果のバッファを使用して、`hll_sketch_estimate`関数でおおよその一意の数を長い整数として計算できます。
## 構文
```
HLL_UNION (( expr1, expr2 [, allowDifferentLgConfigK ] ))
```
## 引数
*exprN*
HLL\$1SKETCH\$1AGG によって生成されたスケッチを保持する`BINARY`式。
*allowDifferentLgConfigK*
異なる lgConfigK 値を持つ 2 つのスケッチのマージを許可するかどうかを制御するオプションの BOOLEAN 式。デフォルト値は `false` です。
## 戻り型
HLL\$1UNION 関数は、入力式を組み合わせた結果として計算された HyperLogLog スケッチを含む BINARY バッファを返します。`allowDifferentLgConfigK` パラメータが の場合`true`、結果スケッチは 2 つの指定された`lgConfigK`値のうち小さい方を使用します。
## 例
次の例では、HyperLogLog (HLL) スケッチアルゴリズムを使用して、データセット`col2`内の 2 つの列 `col1`と の値の一意の数を推定します。
`hll_sketch_agg(col1)` 関数は、`col1`列内の一意の値の HLL スケッチを作成します。
`hll_sketch_agg(col2)` 関数は、col2 列の一意の値の HLL スケッチを作成します。
この`hll_union(...)`関数は、ステップ 1 と 2 で作成した 2 つの HLL スケッチを 1 つの統合 HLL スケッチに結合します。
`hll_sketch_estimate(...)` 関数は、結合された HLL スケッチを取得し、 `col1` と の両方の値の一意の数を推定します`col2`。
`FROM VALUES` 句は 5 行のテストデータセットを生成します。 `col1`には値 1、1、2、2、3 が含まれ、 には値 4、4、5、5、6 `col2`が含まれます。
このクエリの結果は、 `col1`と の両方の値の推定一意数であり`col2`、6 です。HLL スケッチアルゴリズムは、大きなデータセットであっても、一意の値のセットをすべて保存することなく、一意の要素の数を効率的に推定する方法を提供します。この例では、 `hll_union`関数を使用して 2 つの列の HLL スケッチを組み合わせます。これにより、列ごとにだけでなく、データセット全体で一意の数を推定できます。
```
SELECT hll_sketch_estimate(
hll_union(
hll_sketch_agg(col1),
hll_sketch_agg(col2)))
FROM VALUES
(1, 4),
(1, 4),
(2, 5),
(2, 5),
(3, 6) AS tab(col1, col2);
6
```
次の例と前の例の違いは、精度パラメータ (12 ビット) が`hll_sketch_agg`関数呼び出しで指定されていないことです。この場合、デフォルトの精度である 14 ビットが使用されます。これにより、12 ビットの精度を使用した前の例と比較して、一意のカウントのより正確な推定が得られます。
```
SELECT hll_sketch_estimate(
hll_union(
hll_sketch_agg(col1, 14),
hll_sketch_agg(col2, 14)))
FROM VALUES
(1, 4),
(1, 4),
(2, 5),
(2, 5),
(3, 6) AS tab(col1, col2);
```
# HLL\$1UNION\$1AGG 関数
HLL\$1UNION\$1AGG 関数は、複数の HLL スケッチを 1 つの統合スケッチに結合します。HyperLogLog (HLL) アルゴリズムを使用して、スケッチのグループを 1 つのスケッチに結合します。クエリは、結果のバッファを使用して、`hll_sketch_estimate`関数でおおよその一意数を計算できます。
## 構文
```
HLL_UNION_AGG ( expr [, allowDifferentLgConfigK ] )
```
## 引数
expr**
HLL\$1SKETCH\$1AGG によって生成されたスケッチを保持する`BINARY`式。
*allowDifferentLgConfigK*
異なる lgConfigK 値を持つ 2 つのスケッチのマージを許可するかどうかを制御するオプションの BOOLEAN 式。デフォルト値は `false` です。
## 戻り型
HLL\$1UNION\$1AGG 関数は、同じグループの入力式を結合した結果、計算された HyperLogLog スケッチを含む BINARY バッファを返します。`allowDifferentLgConfigK` パラメータが の場合`true`、結果スケッチは 2 つの指定された`lgConfigK`値のうち小さい方を使用します。
## 例
次の例では、HyperLogLog (HLL) スケッチアルゴリズムを使用して、複数の HLL スケッチにわたる値の一意の数を推定します。
最初の例では、データセット内の値の一意の数を推定します。
```
SELECT hll_sketch_estimate(hll_union_agg(sketch, true))
FROM (SELECT hll_sketch_agg(col) as sketch
FROM VALUES (1) AS tab(col)
UNION ALL
SELECT hll_sketch_agg(col, 20) as sketch
FROM VALUES (1) AS tab(col));
1
```
内部クエリは 2 つの HLL スケッチを作成します。
+ 最初の SELECT ステートメントは、1 つの値からスケッチを作成します。
+ 2 番目の SELECT ステートメントは、別の 1 つの値 1 からスケッチを作成しますが、精度は 20 です。
外部クエリは HLL\$1UNION\$1AGG 関数を使用して、2 つのスケッチを 1 つのスケッチに結合します。次に、HLL\$1SKETCH\$1ESTIMATE 関数をこの組み合わせスケッチに適用して、値の一意の数を推定します。
このクエリの結果は、 `col`列の値の推定一意数です`1`。つまり、2 つの入力値 1 は、同じ値であっても一意であると見なされます。
2 番目の例には、HLL\$1UNION\$1AGG 関数の別の精度パラメータが含まれています。この場合、両方の HLL スケッチは 14 ビットの精度で作成されるため、 `true`パラメータ`hll_union_agg`で を使用して正常に組み合わせることができます。
```
SELECT hll_sketch_estimate(hll_union_agg(sketch, true))
FROM (SELECT hll_sketch_agg(col, 14) as sketch
FROM VALUES (1) AS tab(col)
UNION ALL
SELECT hll_sketch_agg(col, 14) as sketch
FROM VALUES (1) AS tab(col));
1
```
クエリの最終結果は推定一意数であり、この場合も です`1`。つまり、2 つの入力値 1 は、同じ値であっても一意であると見なされます。
# JSON 関数
相対的に小さい一連のキーと値のペアを格納する必要がある場合は、データを JSON 形式で格納すると、スペースを節約できます。JSON 文字列は単一の列に格納できるため、データを表形式で格納するより、JSON を使用する方が効率的である可能性があります。
**Example**
例えば、スパース表があるとします。その表では、すべての属性を完全に表すために多数の列が必要ですが、指定された行または指定された列のほとんどの列値は NULL になります。格納に JSON を使用することによって、行のデータを単一の JSON 文字列にキーと値のペアで格納できる可能性があり、格納データの少ない表の列を除去できる可能性があります。
その上、JSON 文字列を簡単に変更することによって、列を表に追加することなく、キーと値のペアをさらに格納することもできます。
JSON の使用は控えめにすることをお勧めします。JSON では、単一の列にさまざまなデータが保存され、 AWS Clean Rooms の列保存アーキテクチャが使用されません。したがってこの形式は、大きいデータセットの保存には適していません。
JSON は UTF-8 でエンコードされたテキスト文字列を使用するため、JSON 文字列を CHAR データ型または VARCHAR データ型として格納できます。文字列にマルチバイト文字が含まれている場合は、VARCHAR を使用します。
JSON 文字列は、以下のルールに従って、正しくフォーマットされた JSON である必要があります。
+ ルートレベルの JSON には、JSON オブジェクトまたは JSON 配列を使用できます。JSON オブジェクトは、順序が設定されていない一連のキーと値のペアがカンマで区切られ、中括弧で囲まれたものです。
例: `{"one":1, "two":2} `
+ JSON 配列は、順序付けられた一連のカンマ区切り値が角括弧で囲まれたものです。
例は次のとおりです: `["first", {"one":1}, "second", 3, null] `
+ JSON 配列は、0 から始まるインデックスを使用します。配列内の最初の要素の位置は 0 です。JSON のキーと値のペアでは、キーは二重引用符で囲まれた文字列です。
+ JSON 値には次のいずれかを指定できます。
+ JSON オブジェクト
+ JSON 配列
+ 二重引用符で囲まれた文字列
+ 数値 (整数および浮動小数点数)
+ ブール値
+ Null
+ 空のオブジェクトおよび空の配列は、有効な JSON 値です。
+ JSON フィールドでは、大文字と小文字が区別されます。
+ JSON 構造要素 (`{ }, [ ]` など) は無視されます。
**Topics**
+ [GET\$1JSON\$1OBJECT 関数](GET_JSON_OBJECT.md)
+ [TO\$1JSON 関数](TO_JSON.md)
# GET\$1JSON\$1OBJECT 関数
GET\$1JSON\$1OBJECT 関数は、 から JSON オブジェクトを抽出します`path`。
## 構文
```
get_json_object(json_txt, path)
```
## 引数
*json\$1txt*
適切に形成された JSON を含む STRING 式。
*パス*
適切に形成された JSON パス式を持つ STRING リテラル。
## 戻り値
STRING を返します。
オブジェクトが見つからない場合、NULL が返されます。
## 例
次の例では、JSON オブジェクトから値を抽出します。最初の引数は、単一のキーと値のペアを持つ単純なオブジェクトを表す JSON 文字列です。2 番目の引数は JSON パス式です。`$` 記号は JSON オブジェクトのルートを表し、 `.a`部分は`a`「」キーに関連付けられた値を抽出することを指定します。関数の出力は`b`「」です。これは、入力 JSON オブジェクトの`a`「」キーに関連付けられた値です。
```
SELECT get_json_object('{"a":"b"}', '$.a');
b
```
# TO\$1JSON 関数
TO\$1JSON 関数は、入力式を JSON 文字列表現に変換します。この関数は、さまざまなデータ型 (数値、文字列、ブール値など) の対応する JSON 表現への変換を処理します。
TO\$1JSON 関数は、構造化データ (データベース行や JSON オブジェクトなど) を JSON のようなよりポータブルで自己記述型の形式に変換する必要がある場合に役立ちます。これは、JSON 形式のデータを期待する他のシステムやサービスとやり取りする必要がある場合に特に役立ちます。
## 構文
```
to_json(expr[, options])
```
## 引数
expr**
JSON 文字列に変換する入力式。値、列、またはその他の有効な SQL 式を指定できます。
*options*:
JSON 変換プロセスをカスタマイズするために使用できるオプションの一連の設定オプション。これらのオプションには、null 値の処理、数値の表現、特殊文字の処理などが含まれます。
## 戻り値
指定された構造体値を持つ JSON 文字列を返します。
## 例
次の例では、名前付き構造体 (構造化データの一種) を JSON 文字列に変換します。最初の引数 `(named_struct('a', 1, 'b', 2)`) は、`to_json()`関数に渡される入力式です。値 1 の「a」と値 2 の「b」の 2 つのフィールドを持つ名前付き構造体を作成します。to\$1json() 関数は、名前付き struct を引数として受け取り、JSON 文字列表現に変換します。出力は です。これは`{"a":1,"b":2}`、名前付き構造体を表す有効な JSON 文字列です。
```
SELECT to_json(named_struct('a', 1, 'b', 2));
{"a":1,"b":2}
```
次の例では、タイムスタンプ値を含む名前付き構造体を、カスタマイズされたタイムスタンプ形式の JSON 文字列に変換します。最初の引数 (`named_struct('time', to_timestamp('2015-08-26', 'yyyy-MM-dd'))`) は、タイムスタンプ値を含む単一のフィールド「time」を持つ名前付き構造体を作成します。2 番目の引数 (`map('timestampFormat', 'dd/MM/yyyy')`) は、単一のキーと値のペアを持つマップ (キーと値のディクショナリ) を作成します。キーはtimestampFormat」で、値はdd/MM/yyyy」です。このマップは、JSON に変換するときにタイムスタンプ値に必要な形式を指定するために使用されます。to\$1json() 関数は、名前付き構造体を JSON 文字列に変換します。2 番目の引数であるマップは、タイムスタンプ形式をdd/MM/yyyy」にカスタマイズするために使用されます。出力は です。これは`{"time":"26/08/2015"}`、目的のdd/MM/yyyy」形式のタイムスタンプ値を含む単一のフィールド「time」を持つ JSON 文字列です。
```
SELECT to_json(named_struct('time', to_timestamp('2015-08-26', 'yyyy-MM-dd')), map('timestampFormat', 'dd/MM/yyyy'));
{"time":"26/08/2015"}
```
# 数学関数
このセクションでは、Spark SQL AWS Clean Rooms でサポートされている数学演算子と関数について説明します。
**Topics**
+ [数学演算子の記号](OPERATOR_SYMBOLS.md)
+ [ABS 関数](ABS.md)
+ [ACOS 関数](ACOS.md)
+ [ASIN 関数](ASIN.md)
+ [ATAN 関数](ATAN.md)
+ [ATAN2 関数](ATAN2.md)
+ [CBRT 関数](CBRT.md)
+ [CEILING (または CEIL）関数](CEILING_FLOOR.md)
+ [COS 関数](COS.md)
+ [COT 関数](COT.md)
+ [DEGREES 関数](DEGREES.md)
+ [DIV 関数](DIV.md)
+ [EXP 関数](EXP.md)
+ [FLOOR 関数](FLOOR.md)
+ [LN 関数](LN.md)
+ [LOG 関数](LOG.md)
+ [MOD 関数](MOD.md)
+ [PI 関数](PI.md)
+ [POWER 関数](POWER.md)
+ [RADIANS 関数](RADIANS.md)
+ [RAND 関数](RAND.md)
+ [RANDOM 関数](RANDOM.md)
+ [ROUND 関数](ROUND.md)
+ [SIGN 関数](SIGN.md)
+ [SIN 関数](SIN.md)
+ [SQRT 関数](SQRT.md)
+ [TRUNC 関数](TRUNC.md)
# 数学演算子の記号
次の表に、サポートされる数学演算子の一覧を示します。
## サポートされている演算子
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/clean-rooms/latest/sql-reference/OPERATOR_SYMBOLS.html)
## 例
特定の取引において支払われたコミッションに手数料 2.00 USD を加算します。
```
select commission, (commission + 2.00) as comm
from sales where salesid=10000;
commission | comm
-----------+-------
28.05 | 30.05
(1 row)
```
特定の取引において販売価格の 20% を計算します。
```
select pricepaid, (pricepaid * .20) as twentypct
from sales where salesid=10000;
pricepaid | twentypct
----------+-----------
187.00 | 37.400
(1 row)
```
継続的な成長パターンに基づいてチケット販売数を予測します。次の例では、サブクエリによって、2008 年に販売されたチケット数が返されます。その結果に、10 年にわたって継続する成長率 5% が指数関数的に乗算されます。
```
select (select sum(qtysold) from sales, date
where sales.dateid=date.dateid and year=2008)
^ ((5::float/100)*10) as qty10years;
qty10years
------------------
587.664019657491
(1 row)
```
日付 ID が 2000 以上である販売の合計支払額および合計コミッションを求め、その後、合計支払額から合計コミッションを減算します。
```
select sum (pricepaid) as sum_price, dateid,
sum (commission) as sum_comm, (sum (pricepaid) - sum (commission)) as value
from sales where dateid >= 2000
group by dateid order by dateid limit 10;
sum_price | dateid | sum_comm | value
-----------+--------+----------+-----------
364445.00 | 2044 | 54666.75 | 309778.25
349344.00 | 2112 | 52401.60 | 296942.40
343756.00 | 2124 | 51563.40 | 292192.60
378595.00 | 2116 | 56789.25 | 321805.75
328725.00 | 2080 | 49308.75 | 279416.25
349554.00 | 2028 | 52433.10 | 297120.90
249207.00 | 2164 | 37381.05 | 211825.95
285202.00 | 2064 | 42780.30 | 242421.70
320945.00 | 2012 | 48141.75 | 272803.25
321096.00 | 2016 | 48164.40 | 272931.60
(10 rows)
```
# ABS 関数
ABS は、数値の絶対値を計算します。この数値は、リテラルでも、数値に評価される式でも構いません。
## 構文
```
ABS (number)
```
## 引数
*number*
数値、または数値に評価される式。SMALLINT、INTEGER、BIGINT、DECIMAL、FLOAT4、または FLOAT8 型にすることができます。
## 戻り型
ABS は、その引数と同じデータ型を返します。
## 例
-38 の絶対数を計算する
```
select abs (-38);
abs
-------
38
(1 row)
```
(14-76) の絶対数を計算する
```
select abs (14-76);
abs
-------
62
(1 row)
```
# ACOS 関数
ACOS は、数値のアークコサイン (逆余弦) を返す三角関数です。戻り値はラジアンで、`0`～`PI` の範囲内です。
## 構文
```
ACOS(number)
```
## 引数
*number*
入力パラメータは `DOUBLE PRECISION` 数です。
## 戻り型
`DOUBLE PRECISION`
## 例
`-1` のアークコサイン (逆余弦) を返すには、次の例を使用します。
```
SELECT ACOS(-1);
+-------------------+
| acos |
+-------------------+
| 3.141592653589793 |
+-------------------+
```
# ASIN 関数
ASIN は、数値のアークサイン (逆正弦) を返す三角関数です。戻り値はラジアンで、`PI/2`～`-PI/2` の範囲内です。
## 構文
```
ASIN(number)
```
## 引数
*number*
入力パラメータは `DOUBLE PRECISION` 数です。
## 戻り型
`DOUBLE PRECISION`
## 例
`1` のアークサイン (正弦) を返すには、次の例を使用します。
```
SELECT ASIN(1) AS halfpi;
+--------------------+
| halfpi |
+--------------------+
| 1.5707963267948966 |
+--------------------+
```
# ATAN 関数
ATAN は、数値のアークタンジェント (逆正接) を返す三角関数です。戻り値はラジアンで、`-PI`～`PI` の範囲内です。
## 構文
```
ATAN(number)
```
## 引数
*number*
入力パラメータは `DOUBLE PRECISION` 数です。
## 戻り型
`DOUBLE PRECISION`
## 例
`1` のアークタンジェント (逆正接) を返し、その値に 4 を乗算するには、次の例を使用します。
```
SELECT ATAN(1) * 4 AS pi;
+-------------------+
| pi |
+-------------------+
| 3.141592653589793 |
+-------------------+
```
# ATAN2 関数
ATAN2 は、一方の数値をもう一方の数値で除算した値のアークタンジェント (逆正接) を返す三角関数です。戻り値はラジアンで、`PI/2`～`-PI/2` の範囲内です。
## 構文
```
ATAN2(number1, number2)
```
## 引数
*number1*
`DOUBLE PRECISION` 数。
*number2*
`DOUBLE PRECISION` 数。
## 戻り型
`DOUBLE PRECISION`
## 例
`2/2` のアークタンジェント (逆正接) を返し、その値に 4 を乗算するには、次の例を使用します。
```
SELECT ATAN2(2,2) * 4 AS PI;
+-------------------+
| pi |
+-------------------+
| 3.141592653589793 |
+-------------------+
```
# CBRT 関数
CBRT 関数は、数値の立方根を計算する数学関数です。
## 構文
```
CBRT (number)
```
## 引数
CBRT は、引数として DOUBLE PRECISION 型の数値を取ります。
## 戻り型
CBRT は DOUBLE PRECISION 型の数値を返します。
## 例
特定の取引において支払われたコミッションの立方根を計算します。
```
select cbrt(commission) from sales where salesid=10000;
cbrt
------------------
3.03839539048843
(1 row)
```
# CEILING (または CEIL）関数
CEILING 関数または CEIL 関数は、数値を最も近い整数に切り上げるために使用します。([FLOOR 関数](FLOOR.md)は、数値を最も近い整数に切り下げます。)
## 構文
```
CEIL | CEILING(number)
```
## 引数
*number*
数値、または数値に評価される式。SMALLINT、INTEGER、BIGINT、DECIMAL、FLOAT4、または FLOAT8 型にすることができます。
## 戻り型
CEILING および CEIL は、引数と同じデータ型を返します。
## 例
特定の取引において支払われたコミッションの切り上げ値を計算します。
```
select ceiling(commission) from sales
where salesid=10000;
ceiling
---------
29
(1 row)
```
# COS 関数
COS は、数値のコサイン (余弦) を返す三角関数です。戻り値はラジアンで、`-1` 以上 `1` 以下です。
## 構文
```
COS(double_precision)
```
## 引数
*number*
入力パラメータは倍精度の数値です。
## 戻り型
COS 関数は、倍精度の数値を返します。
## 例
次の例は、0 のコサイン (余弦) を返します。
```
select cos(0);
cos
-----
1
(1 row)
```
次の例は、PI のコサイン (余弦) を返します。
```
select cos(pi());
cos
-----
-1
(1 row)
```
# COT 関数
COT は、数値のコタンジェント (余接) を返す三角関数です。入力パラメータは 0 以外である必要があります。
## 構文
```
COT(number)
```
## 引数
*number*
入力パラメータは `DOUBLE PRECISION` 数です。
## 戻り型
`DOUBLE PRECISION`
## 例
1 のコタンジェント (余接) を返すには、次の例を使用します。
```
SELECT COT(1);
+--------------------+
| cot |
+--------------------+
| 0.6420926159343306 |
+--------------------+
```
# DEGREES 関数
ラジアンで指定された角度を、その値に相当する度数に変換します。
## 構文
```
DEGREES(number)
```
## 引数
*number*
入力パラメータは `DOUBLE PRECISION` 数です。
## 戻り型
`DOUBLE PRECISION`
## 例
0.5 ラジアンに相当する度数を返すには、次の例を使用します。
```
SELECT DEGREES(.5);
+-------------------+
| degrees |
+-------------------+
| 28.64788975654116 |
+-------------------+
```
PI ラジアンを度数に変換するには、次の例を使用します。
```
SELECT DEGREES(pi());
+---------+
| degrees |
+---------+
| 180 |
+---------+
```
# DIV 関数
DIV 演算子は、除算除算の積分部分を返します。
## 構文
```
dividend div divisor
```
## 引数
*分配*
数値または間隔に評価される式。
*除数*
`dividend` が間隔の場合は一致する間隔タイプ、それ以外の場合は数値。
## 戻り型
`BIGINT`
## 例
次の例では、リステーブルから 2 つの列を選択します。各リスの一意の識別子を含む `id` 列と、年齢`calculated`列の整数除算を 2 で`age div 2`表す 列です。`age div 2` 計算は`age`列で整数除算を実行し、実質的に経過時間を最も近い偶数に切り下げます。たとえば、`age`列に 3、5、7、10 などの値が含まれている場合、`age div 2`列にはそれぞれ 1、2、3、5 の値が含まれます。
```
SELECT id, age div 2 FROM squirrels
```
このクエリは、年齢範囲に基づいてデータをグループ化または分析する必要があり、最も近い偶数に切り下げて年齢値を簡素化する場合に役立ちます。結果の出力は、`squirrels`テーブル内のリスごとに `id`と経過時間を 2 で割ったものになります。
# EXP 関数
EXP 関数では、数値式、または式の累乗で累乗された自然対数 `e` の基数に対して指数関数を実装します。EXP 関数は、[LN 関数](LN.md)の逆です。
## 構文
```
EXP (expression)
```
## 引数
*expression*
式のデータ型は INTEGER、DECIMAL、または DOUBLE PRECISION である必要があります。
## 戻り型
EXP は DOUBLE PRECISION 型の数値を返します。
## 例
EXP 関数は、継続的な成長パターンに基づいてチケット販売を予測するために使用します。次の例では、サブクエリによって、2008 年に販売されたチケット数が返されます。その結果に、10 年にわたって継続する成長率 7% を指定する EXP 関数の結果が乗算されます。
```
select (select sum(qtysold) from sales, date
where sales.dateid=date.dateid
and year=2008) * exp((7::float/100)*10) qty2018;
qty2018
------------------
695447.483772222
(1 row)
```
# FLOOR 関数
FLOOR 関数は、数値を次の整数に切り捨てます。
## 構文
```
FLOOR (number)
```
## 引数
*number*
数値、または数値に評価される式。SMALLINT、INTEGER、BIGINT、DECIMAL、FLOAT4、または FLOAT8 型にすることができます。
## 戻り型
FLOOR は、その引数と同じデータ型を返します。
## 例
この例では、FLOOR 関数を使用する前と後に特定の販売取引に対して支払われたコミッションの値を示します。
```
select commission from sales
where salesid=10000;
floor
-------
28.05
(1 row)
select floor(commission) from sales
where salesid=10000;
floor
-------
28
(1 row)
```
# LN 関数
LN 関数は、入力パラメータの自然対数を返します。
## 構文
```
LN(expression)
```
## 引数
*expression*
関数の対象となる列または式。
この関数は、式が AWS Clean Rooms ユーザーが作成したテーブル、または AWS Clean Rooms STL または STV システムテーブルを参照している場合、一部のデータ型にエラーを返します。
式の参照先がユーザー作成テーブルまたはシステムテーブルである場合、式のデータ型が以下のいずれかであるときに、エラーが発生します。
+ BOOLEAN
+ CHAR
+ DATE
+ DECIMAL または NUMERIC
+ TIMESTAMP
+ VARCHAR
以下のデータ型の式は、ユーザー作成テーブルおよび STL または STV システムテーブルで、正常に実行されます。
+ BIGINT
+ DOUBLE PRECISION
+ INTEGER
+ REAL
+ SMALLINT
## 戻り型
LN 関数は、式と同じ型を返します。
## 例
次の例は、数値 2.718281828 の自然対数、または e を底とする対数を返します。
```
select ln(2.718281828);
ln
--------------------
0.9999999998311267
(1 row)
```
解は 1 の近似値になることに注意してください。
次の例は、USERS テーブル内の USERID 列の値の自然対数を返します。
```
select username, ln(userid) from users order by userid limit 10;
username | ln
----------+-------------------
JSG99FHE | 0
PGL08LJI | 0.693147180559945
IFT66TXU | 1.09861228866811
XDZ38RDD | 1.38629436111989
AEB55QTM | 1.6094379124341
NDQ15VBM | 1.79175946922805
OWY35QYB | 1.94591014905531
AZG78YIP | 2.07944154167984
MSD36KVR | 2.19722457733622
WKW41AIW | 2.30258509299405
(10 rows)
```
# LOG 関数
`expr` で の対数を返します`base`。
## 構文
```
LOG(base, expr)
```
## 引数
expr**
この式は整数、10 進数、または浮動小数点数データ型である必要があります。
*base*
対数計算のベース。倍精度データ型の正の数 (1 と等しくない) である必要があります。
## 戻り型
LOG 関数は、倍精度の数値を返します。
## 例
次の例は、数値 100 の 10 を底とする対数を返します。
```
select log(10, 100);
--------
2
(1 row)
```
# MOD 関数
2 つの数値の余りを返します。*モジュロ*演算とも呼ばれます。結果を計算するには、最初のパラメータを 2 番目のパラメータで除算します。
## 構文
```
MOD(number1, number2)
```
## 引数
*number1*
最初の入力パラメータは INTEGER 型、SMALLINT 型、BIGINT 型、または DECIMAL 型の数値です。一方のパラメータが DECIMAL 型である場合は、もう一方のパラメータも DECIMAL 型である必要があります。一方のパラメータが INTEGER である場合、もう一方のパラメータは INTEGER、SMALLINT、または BIGINT のいずれかにします。両方のパラメータを SMALLINT または BIGINT にすることもできますが、一方のパラメータが BIGINT である場合に、もう一方のパラメータを SMALLINT にすることはできません。
*number2*
2 番目のパラメータは INTEGER 型、SMALLINT 型、BIGINT 型、または DECIMAL 型の数値です。*number1* と同じデータ型ルールが *number2* に適用されます。
## 戻り型
有効な戻り型は DECIMAL、INT、SMALLINT、および BIGINT です。両方の入力パラメータが同じ型である場合、MOD 関数の戻り型は、入力パラメータと同じ数値型になります。ただし、一方の入力パラメータが INTEGER である場合は、戻り型も INTEGER になります。
## 使用に関する注意事項
*%* をモジュロ演算子として使用できます。
## 例
次の例は、ある数値を別の数値で除算したときの余りを返します。
```
SELECT MOD(10, 4);
mod
------
2
```
次の例は、小数の結果を返します。
```
SELECT MOD(10.5, 4);
mod
------
2.5
```
パラメータ値をキャストできます。
```
SELECT MOD(CAST(16.4 as integer), 5);
mod
------
1
```
最初のパラメータを 2 で割って偶数かどうかをチェックします。
```
SELECT mod(5,2) = 0 as is_even;
is_even
--------
false
```
*%* をモジュロ演算子として使用できます。
```
SELECT 11 % 4 as remainder;
remainder
-----------
3
```
次の例は、CATEGORY テーブル内の奇数カテゴリーの情報を返します。
```
select catid, catname
from category
where mod(catid,2)=1
order by 1,2;
catid | catname
-------+-----------
1 | MLB
3 | NFL
5 | MLS
7 | Plays
9 | Pop
11 | Classical
(6 rows)
```
# PI 関数
pi 関数は、PI の値を小数第 14 位まで返します。
## 構文
```
PI()
```
## 戻り型
`DOUBLE PRECISION`
## 例
pi の値を返すには、次の例を使用します。
```
SELECT PI();
+-------------------+
| pi |
+-------------------+
| 3.141592653589793 |
+-------------------+
```
# POWER 関数
POWER 関数は指数関数であり、最初の数値式がべき乗の底、2 番目の数値式がべき乗の指数です。例えば、2 の 3 乗は `POWER(2,3)` と表され、結果は `8` になります。
## 構文
```
{POWER(expression1, expression2)
```
## 引数
*expression1*
べき乗の底とする数値式。`INTEGER`、`DECIMAL`、または `FLOAT` データ型である必要があります。
*expression2*
*expression1* を底とするべき乗の指数。`INTEGER`、`DECIMAL`、または `FLOAT` データ型である必要があります。
## 戻り型
`DOUBLE PRECISION`
## 例
```
SELECT (SELECT SUM(qtysold) FROM sales, date
WHERE sales.dateid=date.dateid
AND year=2008) * POW((1+7::FLOAT/100),10) qty2010;
+-------------------+
| qty2010 |
+-------------------+
| 679353.7540885945 |
+-------------------+
```
# RADIANS 関数
RADIANS 関数は、角度 (度数) をそれに相当するラジアンに変換します。
## 構文
```
RADIANS(number)
```
## 引数
*number*
入力パラメータは `DOUBLE PRECISION` 数です。
## 戻り型
`DOUBLE PRECISION`
## 例
180 度に相当するラジアンを返すには、次の例を使用します。
```
SELECT RADIANS(180);
+-------------------+
| radians |
+-------------------+
| 3.141592653589793 |
+-------------------+
```
# RAND 関数
RAND 関数は、0 から 1 までのランダムな浮動小数点数を生成します。RAND 関数は、呼び出されるたびに新しい乱数を生成します。
## 構文
```
RAND()
```
## 戻り型
RANDOM は DOUBLE を返します。
## 例
次の例では、`squirrels`テーブル内の行ごとに 0 から 1 までのランダムな浮動小数点数の列を生成します。結果の出力は、ランダムな 10 進値のリストを含む単一の列になり、リステーブルの行ごとに 1 つの値が含まれます。
```
SELECT rand() FROM squirrels
```
このタイプのクエリは、ランダムなイベントをシミュレートしたり、データ分析にランダム性を導入したりするなど、乱数を生成する必要がある場合に便利です。`squirrels` テーブルのコンテキストでは、各リスにランダムな値を割り当てて、さらなる処理や分析に使用できる場合があります。
# RANDOM 関数
RANDOM 関数は、0.0 (この値を含む) ～1.0 (この値は含まない) のランダム値を生成します。
## 構文
```
RANDOM()
```
## 戻り型
RANDOM は DOUBLE PRECISION 型の数値を返します。
## 例
1. 0～99 のランダム値を計算します。ランダムな数値が 0～1 である場合、このクエリは、0～100 のランダムな数値を生成します。
```
select cast (random() * 100 as int);
INTEGER
------
24
(1 row)
```
1. 10 個のアイテムの均一なランダムサンプルを取得します。
```
select *
from sales
order by random()
limit 10;
```
10 個のアイテムのランダムサンプルを取得しますが、料金に比例してアイテムを選択します。例えば、別の料金の 2 倍のアイテムは、クエリ結果に表示される可能性が 2 倍になります。
```
select *
from sales
order by log(1 - random()) / pricepaid
limit 10;
```
1. 次の例では、SET コマンドを使用して SEED 値を設定します。これにより RANDOM が予測可能な順序で数値を生成します。
まず、SEED 値を最初に設定せずに、3 つの整数の乱数を返します。
```
select cast (random() * 100 as int);
INTEGER
------
6
(1 row)
select cast (random() * 100 as int);
INTEGER
------
68
(1 row)
select cast (random() * 100 as int);
INTEGER
------
56
(1 row)
```
次に、SEED 値を `.25` に設定して、さらに 3 つの整数の乱数を返します。
```
set seed to .25;
select cast (random() * 100 as int);
INTEGER
------
21
(1 row)
select cast (random() * 100 as int);
INTEGER
------
79
(1 row)
select cast (random() * 100 as int);
INTEGER
------
12
(1 row)
```
最後に、SEED 値を `.25` にリセットして、RANDOM が前の 3 つの呼び出しと同じ結果を返すことを確認します。
```
set seed to .25;
select cast (random() * 100 as int);
INTEGER
------
21
(1 row)
select cast (random() * 100 as int);
INTEGER
------
79
(1 row)
select cast (random() * 100 as int);
INTEGER
------
12
(1 row)
```
# ROUND 関数
ROUND 関数は、数値を四捨五入して、最も近い整数または 10 進数にします。
ROUND 関数にはオプションで、2 番目の引数として整数を指定できます。この整数は、四捨五入後の小数点以下または小数点以上の桁数を指定します。2 番目の引数を指定しない場合、関数は最も近い整数に四捨五入されます。2 番目の引数 *>n* が指定されている場合、関数は小数点以下 *n* 桁の精度で最も近い数値に四捨五入されます。
## 構文
```
ROUND (number [ , integer ] )
```
## 引数
*number*
数値、または数値に評価される式。DECIMAL または FLOAT8 type. AWS Clean Rooms can は、暗黙的な変換ルールに従って他のデータ型を変換できます。
*integer* (オプション)
いずれかの方向で小数点以上または小数点以下の桁数を示す整数。
## 戻り型
ROUND は、入力引数と同じ数値データ型を返します。
## 例
特定の取引において支払われたコミッションを四捨五入して、最も近い整数にします。
```
select commission, round(commission)
from sales where salesid=10000;
commission | round
-----------+-------
28.05 | 28
(1 row)
```
特定の取引において支払われたコミッションを四捨五入して、小数点以下第 1 位までの数値にします。
```
select commission, round(commission, 1)
from sales where salesid=10000;
commission | round
-----------+-------
28.05 | 28.1
(1 row)
```
上記と同じクエリで、小数点以上 1 桁 (つまり 1 の位) までの数値にします。
```
select commission, round(commission, -1)
from sales where salesid=10000;
commission | round
-----------+-------
28.05 | 30
(1 row)
```
# SIGN 関数
SIGN 関数は、数の符号 (正または負) を返します。SIGN 関数の結果は、引数の符号を示す `1`、`-1`、または `0` です。
## 構文
```
SIGN (number)
```
## 引数
*number*
数値、または数値に評価される式。DECIMALor FLOAT8 type. AWS Clean Rooms can は、暗黙的な変換ルールに従って他のデータ型を変換できます。
## 戻り型
SIGN は、入力引数と同じ数値データ型を返します。入力が DECIMAL の場合、出力は DECIMAL(1,0) になります。
## 例
SALES テーブルから、特定の取引において支払われたコミッションの符号を判別するには、次の例を使用します。
```
SELECT commission, SIGN(commission)
FROM sales WHERE salesid=10000;
+------------+------+
| commission | sign |
+------------+------+
| 28.05 | 1 |
+------------+------+
```
# SIN 関数
SIN は、数値のサイン (正弦) を返す三角関数です。戻り値は、`-1`～`1` です。
## 構文
```
SIN(number)
```
## 引数
*number*
ラジアン単位の `DOUBLE PRECISION` 数。
## 戻り型
`DOUBLE PRECISION`
## 例
`-PI` のサイン (正弦) を返すには、次の例を使用します。
```
SELECT SIN(-PI());
+-------------------------+
| sin |
+-------------------------+
| -0.00000000000000012246 |
+-------------------------+
```
# SQRT 関数
SQRT 関数は、数値の平方根を返します。平方根は、与えられた値を得るためにそれ自体を掛けた数値です。
## 構文
```
SQRT (expression)
```
## 引数
*expression*
この式は整数、10 進数、または浮動小数点数データ型である必要があります。式には関数を含めることができます。システムが暗黙的にタイプの変換を行う場合があります。
## 戻り型
SQRT は DOUBLE PRECISION 型の数値を返します。
## 例
次の例では、数値の平方根を返します。
```
select sqrt(16);
sqrt
---------------
4
```
次の例では、暗黙的なタイプの変換を実行します。
```
select sqrt('16');
sqrt
---------------
4
```
次の例では、関数をネストしてより複雑なタスクを実行します。
```
select sqrt(round(16.4));
sqrt
---------------
4
```
次の例では、円のエリアを指定したときの半径の長さが得られます。例えば、エリアを平方インチで指定すると、半径をインチで計算します。サンプルのエリアは 20 です。
```
select sqrt(20/pi());
```
これにより 5.046265044040321 という値が返されます。
次の例では、SALES テーブルから COMMISSION 値の平方根を返します。COMMISSION 列は DECIMAL 型列です。この例は、より複雑な条件ロジックを含むクエリで関数を使用する方法を示しています。
```
select sqrt(commission)
from sales where salesid < 10 order by salesid;
sqrt
------------------
10.4498803820905
3.37638860322683
7.24568837309472
5.1234753829798
...
```
次のクエリでは、上記と同じ COMMISSION 値の四捨五入された平方根を返します。
```
select salesid, commission, round(sqrt(commission))
from sales where salesid < 10 order by salesid;
salesid | commission | round
--------+------------+-------
1 | 109.20 | 10
2 | 11.40 | 3
3 | 52.50 | 7
4 | 26.25 | 5
...
```
のサンプルデータの詳細については AWS Clean Rooms、[「サンプルデータベース](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)」を参照してください。
# TRUNC 関数
TRUNC 関数は、数値を前の整数または小数に切り捨てます。
TRUNC 関数にはオプションで、2 番目の引数として整数を指定できます。この整数は、四捨五入後の小数点以下または小数点以上の桁数を指定します。2 番目の引数を指定しない場合、関数は最も近い整数に四捨五入されます。2 番目の引数 *>n* が指定されている場合、関数は小数点以下 *>n* 桁以上の精度で最も近い数値に四捨五入されます。この関数は、タイムスタンプも切り捨て、日付を返します。
## 構文
```
TRUNC (number [ , integer ] |
timestamp )
```
## 引数
*number*
数値、または数値に評価される式。DECIMAL または FLOAT8 type. AWS Clean Rooms can は、暗黙的な変換ルールに従って他のデータ型を変換できます。
*integer* (オプション)
小数点以上または小数点以下の桁数を示す整数。この整数が指定されなかった場合は、数値が切り捨てられて整数になります。この整数が指定された場合は、数値が切り捨てられて、指定された桁数になります。
*timestamp*
この関数は、タイムスタンプから取得した日付も返します。(タイムスタンプの値 `00:00:00` を時刻として返すには、関数の結果をタイムスタンプにキャストします。)
## 戻り型
TRUNC は、最初の入力引数と同じデータ型を返します。タイムスタンプの場合、TRUNC は日付を返します。
## 例
特定の販売取引について支払われたコミッションを切り捨てます。
```
select commission, trunc(commission)
from sales where salesid=784;
commission | trunc
-----------+-------
111.15 | 111
(1 row)
```
同じコミッション値を切り捨てて、小数点以下第 1 位までの数値にします。
```
select commission, trunc(commission,1)
from sales where salesid=784;
commission | trunc
-----------+-------
111.15 | 111.1
(1 row)
```
コミッションを切り捨てますが、2 番目の引数に負の値が指定されています。`111.15` は切り捨てられて、`110`になります。
```
select commission, trunc(commission,-1)
from sales where salesid=784;
commission | trunc
-----------+-------
111.15 | 110
(1 row)
```
SYSDATE 関数 (タイムスタンプを返す) の結果から日付部分を返します。
```
select sysdate;
timestamp
----------------------------
2011-07-21 10:32:38.248109
(1 row)
select trunc(sysdate);
trunc
------------
2011-07-21
(1 row)
```
TRUNC 関数を TIMESTAMP 列に適用します。戻り型は日付です。
```
select trunc(starttime) from event
order by eventid limit 1;
trunc
------------
2008-01-25
(1 row)
```
# スカラー関数
このセクションでは、 AWS Clean Rooms Spark SQL でサポートされているスカラー関数について説明します。スカラー関数は、1 つ以上の値を入力として受け取り、1 つの値を出力として返す関数です。スカラー関数は個々の行または要素で動作し、入力ごとに 1 つの結果を生成します。
SIZE などのスカラー関数は、集計関数 (カウント、合計、平均) やテーブル生成関数 (爆発、フラット化) など、他のタイプの SQL 関数とは異なります。これらの他の関数タイプは複数の行で動作するか、複数の行を生成しますが、スカラー関数は個々の行または要素で動作します。
**Topics**
+ [SIZE 関数](size.md)
# SIZE 関数
SIZE 関数は、既存の配列、マップ、または文字列を引数として受け取り、そのデータ構造のサイズまたは長さを表す単一の値を返します。新しいデータ構造は作成されません。これは、新しいデータ構造を作成するのではなく、既存のデータ構造のプロパティをクエリおよび分析するために使用されます。
この関数は、配列内の要素の数または文字列の長さを決定するのに役立ちます。SQL で配列やその他のデータ構造を使用する場合、データのサイズやカーディナリティに関する情報を取得できるため、特に便利です。
## 構文
```
size(expr)
```
## 引数
expr**
ARRAY、MAP、または STRING 式。
## 戻り型
SIZE 関数は INTEGER を返します。
## 例
この例では、SIZE 関数が配列 に適用され`['b', 'd', 'c', 'a']`、配列内の要素の数`4`である値 を返します。
```
SELECT size(array('b', 'd', 'c', 'a'));
4
```
この例では、SIZE 関数がマップ に適用され`{'a': 1, 'b': 2}`、マップ内のキーと値のペアの数`2`である値 を返します。
```
SELECT size(map('a', 1, 'b', 2));
2
```
この例では、SIZE 関数が文字列 に適用され`'hello world'`、文字列内の文字数`11`である値 を返します。
```
SELECT size('hello world');
11
```
# 文字列関数
文字列関数は、文字列、または文字列に評価される式を処理します。これらの関数の *string* 引数がリテラル値である場合は、その値を一重引用符で囲む必要があります。サポートされるデータ型には、CHAR や VARCHAR があります。
次のセクションでは、サポートされる関数の関数名と構文を示し、それらについて説明します。文字列のオフセットはすべて 1 から始まります。
**Topics**
+ [\$1\$1 (連結）演算子](concat_op.md)
+ [BTRIM 関数](BTRIM.md)
+ [CONCAT 関数](CONCAT.md)
+ [FORMAT\$1STRING 関数](FORMAT_STRING.md)
+ [LEFT 関数および RIGHT 関数](LEFT.md)
+ [LENGTH 関数](LENGTH.md)
+ [LOWER 関数](LOWER.md)
+ [LPAD 関数および RPAD 関数](LPAD.md)
+ [LTRIM 関数](LTRIM.md)
+ [POSITION 関数](POSITION.md)
+ [REGEXP\$1COUNT 関数](REGEXP_COUNT.md)
+ [REGEXP\$1INSTR 関数](REGEXP_INSTR.md)
+ [REGEXP\$1REPLACE 関数](REGEXP_REPLACE.md)
+ [REGEXP\$1SUBSTR 関数](REGEXP_SUBSTR.md)
+ [REPEAT 関数](REPEAT.md)
+ [REPLACE 関数](REPLACE.md)
+ [REVERSE 関数](REVERSE.md)
+ [RTRIM 関数](RTRIM.md)
+ [SPLIT 関数](split.md)
+ [SPLIT\$1PART 関数](SPLIT_PART.md)
+ [SUBSTRING 関数](SUBSTRING.md)
+ [TRANSLATE 関数](TRANSLATE.md)
+ [TRIM 関数](TRIM.md)
+ [UPPER 関数](UPPER.md)
+ [UUID 関数](UUID.md)
# \$1\$1 (連結）演算子
\$1\$1 記号の両側の 2 つの表現を連結し、その結果の表現を返します。
連結演算子は [CONCAT 関数](CONCAT.md) に似ています。
**注記**
CONCAT 関数ならびに連結演算子のどちらにおいても、一方または両方の表現が null である場合は、連結の結果も null になります。
## 構文
```
expression1 || expression2
```
## 引数
*expression1*, *expression2*
両方の引数を、固定長または可変長の文字列または式にすることができます。
## 戻り型
\$1\$1 演算子は文字列を返します。文字列の型は、入力引数の型と同じです。
## 例
次の例では、USERS テーブルの FIRSTNAME フィールドと LASTNAME フィールドを連結します。
```
select firstname || ' ' || lastname
from users
order by 1
limit 10;
concat
-----------------
Aaron Banks
Aaron Booth
Aaron Browning
Aaron Burnett
Aaron Casey
Aaron Cash
Aaron Castro
Aaron Dickerson
Aaron Dixon
Aaron Dotson
(10 rows)
```
Null を含む可能性がある列を連結するには、[NVL および COALESCE 関数](NVL_function.md)式を使用します。次の例は、NVL を使用して、NULL が発生するたびに 0 を返します。
```
select venuename || ' seats ' || nvl(venueseats, 0)
from venue where venuestate = 'NV' or venuestate = 'NC'
order by 1
limit 10;
seating
-----------------------------------
Ballys Hotel seats 0
Bank of America Stadium seats 73298
Bellagio Hotel seats 0
Caesars Palace seats 0
Harrahs Hotel seats 0
Hilton Hotel seats 0
Luxor Hotel seats 0
Mandalay Bay Hotel seats 0
Mirage Hotel seats 0
New York New York seats 0
```
# BTRIM 関数
BTRIM 関数は、先頭および末尾の空白を削除するか、またはオプションで指定された文字列と一致する先頭および末尾の文字を削除することによって、文字列を切り捨てます。
## 構文
```
BTRIM(string [, trim_chars ] )
```
## 引数
*string*
切り捨てる入力 VARCHAR 文字列。
*trim\$1chars*
イッチする文字を含む VARCHAR 文字列。
## 戻り型
BTRIM 関数は、VARCHAR 型の文字列を返します。
## 例
次の例では、文字列 `' abc '` の先頭および末尾の空白を切り捨てます。
```
select ' abc ' as untrim, btrim(' abc ') as trim;
untrim | trim
----------+------
abc | abc
```
次の例では、文字列 `'xyzaxyzbxyzcxyz'` から先頭および末尾の文字列 `'xyz'` を削除します。先頭および末尾にある `'xyz'` は削除されますが、文字列内部にあるその文字列は削除されません。
```
select 'xyzaxyzbxyzcxyz' as untrim,
btrim('xyzaxyzbxyzcxyz', 'xyz') as trim;
untrim | trim
-----------------+-----------
xyzaxyzbxyzcxyz | axyzbxyzc
```
次の例では、*trim\$1chars* リスト `'tes'` のいずれかの文字と一致する文字列 `'setuphistorycassettes'` の先頭と末尾の部分を削除します。入力文字列の先頭または末尾にある *trim\$1chars* リストに含まれていない別の文字の前に出現する `t`、`e` または `s` が削除されます。
```
SELECT btrim('setuphistorycassettes', 'tes');
btrim
-----------------
uphistoryca
```
# CONCAT 関数
CONCAT 関数は、2 つの式を連結し、結果の表現を返します。3 つ以上の式を連結するには、CONCAT 関数をネストして使用します。2 つの式の間に連結演算子 (`||`) を指定した場合も、CONCAT 関数と同じ結果が返されます。
**注記**
CONCAT 関数ならびに連結演算子のどちらにおいても、一方または両方の表現が null である場合は、連結の結果も null になります。
## 構文
```
CONCAT ( expression1, expression2 )
```
## 引数
*expression1*, *expression2*
どちらの引数にも、固定長文字列、可変長文字列、バイナリ式、またはこれらの入力のいずれかとして評価される式を指定できます。
## 戻り型
CONCAT は式を返します。式のデータ型は、入力引数の型と同じです。
入力式が異なる型である場合、 は暗黙的に型をキャスト AWS Clean Rooms しようとします。値を型キャストできない場合は、エラーが返されます。
## 例
次の例では、2 つの文字リテラルを連結します。
```
select concat('December 25, ', '2008');
concat
-------------------
December 25, 2008
(1 row)
```
次のクエリでは、CONCAT ではなく `||` 演算子を使用しており、同じ結果が返されます。
```
select 'December 25, '||'2008';
concat
-------------------
December 25, 2008
(1 row)
```
次の例では、2 つの CONCAT 関数を使用して、3 つの文字列を連結します。
```
select concat('Thursday, ', concat('December 25, ', '2008'));
concat
-----------------------------
Thursday, December 25, 2008
(1 row)
```
Null を含む可能性がある列を連結するには、[NVL および COALESCE 関数](NVL_function.md)を使用します。次の例は、NVL を使用して、NULL が発生するたびに 0 を返します。
```
select concat(venuename, concat(' seats ', nvl(venueseats, 0))) as seating
from venue where venuestate = 'NV' or venuestate = 'NC'
order by 1
limit 5;
seating
-----------------------------------
Ballys Hotel seats 0
Bank of America Stadium seats 73298
Bellagio Hotel seats 0
Caesars Palace seats 0
Harrahs Hotel seats 0
(5 rows)
```
次のクエリでは、VENUE テーブル内の CITY 値と STATE 値を連結します。
```
select concat(venuecity, venuestate)
from venue
where venueseats > 75000
order by venueseats;
concat
-------------------
DenverCO
Kansas CityMO
East RutherfordNJ
LandoverMD
(4 rows)
```
次のクエリでは、ネストされた CONCAT 関数を使用しています。このクエリは、VENUE テーブル内の CITY 値と STATE 値を連結しますが、結果の文字列をカンマおよびスペースで区切ります。
```
select concat(concat(venuecity,', '),venuestate)
from venue
where venueseats > 75000
order by venueseats;
concat
---------------------
Denver, CO
Kansas City, MO
East Rutherford, NJ
Landover, MD
(4 rows)
```
# FORMAT\$1STRING 関数
FORMAT\$1STRING 関数は、テンプレート文字列のプレースホルダーを指定された引数に置き換えることで、フォーマットされた文字列を作成します。printf 形式の文字列からフォーマットされた文字列を返します。
FORMAT\$1STRING 関数は、テンプレート文字列のプレースホルダーを引数として渡された対応する値に置き換えることで機能します。このタイプの文字列フォーマットは、出力メッセージ、レポート、またはその他のタイプの情報テキストを生成する場合など、静的テキストと動的データの組み合わせを含む文字列を動的に構築する必要がある場合に役立ちます。FORMAT\$1STRING 関数は、これらのタイプのフォーマットされた文字列を作成するための簡潔で読みやすい方法を提供するため、出力を生成するコードの管理と更新が容易になります。
## 構文
```
format_string(strfmt, obj, ...)
```
## 引数
*strfmt*
STRING 式。
*obj*
STRING 式または数値式。
## 戻り型
FORMAT\$1STRING は STRING を返します。
## 例
次の例には、2 つのプレースホルダーを含むテンプレート文字列が含まれています。10 進数 (整数) 値`%d`の場合は 、文字列値`%s`の場合は です。`%d` プレースホルダーは小数点 (整数) 値 (`100`) に置き換えられ、%s プレースホルダーは文字列値 () に置き換えられます`"days"`。出力は、プレースホルダーが指定された引数 に置き換えられたテンプレート文字列です`"Hello World 100 days"`。
```
SELECT format_string("Hello World %d %s", 100, "days");
Hello World 100 days
```
# LEFT 関数および RIGHT 関数
これらの関数は、文字列の左端または右端にある指定数の文字を返します。
number はバイト数ではなく文字数に基づくため、マルチバイト文字は 1 文字としてカウントされます。
## 構文
```
LEFT ( string, integer )
RIGHT ( string, integer )
```
## 引数
*string*
文字列、または文字列に評価される式。
*integer*
正の整数。
## 戻り型
LEFT および RIGHT は VARCHAR 型の文字列を返します。
## 例
次の例は、ID が 1000 から 1005 であるイベント名の左端 5 文字および右端 5 文字を返します。
```
select eventid, eventname,
left(eventname,5) as left_5,
right(eventname,5) as right_5
from event
where eventid between 1000 and 1005
order by 1;
eventid | eventname | left_5 | right_5
--------+----------------+--------+---------
1000 | Gypsy | Gypsy | Gypsy
1001 | Chicago | Chica | icago
1002 | The King and I | The K | and I
1003 | Pal Joey | Pal J | Joey
1004 | Grease | Greas | rease
1005 | Chicago | Chica | icago
(6 rows)
```
# LENGTH 関数
# LOWER 関数
文字列を小文字に変換します。LOWER は、UTF-8 マルチバイト文字に対応しています (1 文字につき最大で 4 バイトまで)。
## 構文
```
LOWER(string)
```
## 引数
*string*
入力パラメータは VARCHAR 文字列 (または CHAR など、暗黙的に VARCHAR に変換できるその他のデータ型) です。
## 戻り型
LOWER 関数は、入力文字列のデータ型と同じデータ型の文字列を返します。
## 例
次の例では、CATNAME フィールドを小文字に変換します。
```
select catname, lower(catname) from category order by 1,2;
catname | lower
----------+-----------
Classical | classical
Jazz | jazz
MLB | mlb
MLS | mls
Musicals | musicals
NBA | nba
NFL | nfl
NHL | nhl
Opera | opera
Plays | plays
Pop | pop
(11 rows)
```
# LPAD 関数および RPAD 関数
これらの関数は、指定された長さに基づいて、文字列の前または後に文字を付加します。
## 構文
```
LPAD (string1, length, [ string2 ])
```
```
RPAD (string1, length, [ string2 ])
```
## 引数
*string1*
文字列、または文字列に評価される式 (文字列の列名など)。
*length*
関数の結果の長さを定義する整数。文字列の長さはバイト数ではなく文字数に基づくため、マルチバイト文字は 1 文字としてカウントされます。指定された長さより *string1* が長い場合は、(右側が) 切り捨てられます。*length* が負の数値である場合は、関数の結果が空の文字列になります。
*string2*
*string1* の前または後に付加する 1 つ以上の文字。この引数はオプションです。指定されなかった場合は、スペースが使用されます。
## 戻り型
これらの関数は VARCHAR データ型を返します。
## 例
指定された一連のイベント名を切り捨てて 20 文字にします。20 文字に満たない名前の前にはスペースを付加します。
```
select lpad(eventname,20) from event
where eventid between 1 and 5 order by 1;
lpad
--------------------
Salome
Il Trovatore
Boris Godunov
Gotterdammerung
La Cenerentola (Cind
(5 rows)
```
上記と同じ一連のイベント名を切り捨てて 20 文字にします。ただし、20 文字に満たない名前の後には `0123456789` を付加します。
```
select rpad(eventname,20,'0123456789') from event
where eventid between 1 and 5 order by 1;
rpad
--------------------
Boris Godunov0123456
Gotterdammerung01234
Il Trovatore01234567
La Cenerentola (Cind
Salome01234567890123
(5 rows)
```
# LTRIM 関数
文字列の先頭から文字を切り捨てます。トリム文字リスト内の文字のみを含む最長の文字列を削除します。入力文字列にトリム文字が表示されない場合、トリミングは完了です。
## 構文
```
LTRIM( string [, trim_chars] )
```
## 引数
*string*
トリミングする文字列列、式、または文字列リテラル。
*trim\$1chars*
*文字列*の先頭からトリミングする文字を表す、文字列の列、式、または文字列リテラル。指定しなかった場合、スペースがトリム文字として使用されます。
## 戻り型
LTRIM 関数は、入力*文字列*のデータ型 (CHAR または VARCHAR) と同じデータ型の文字列を返します。
## 例
次の例は、`listime` 列から年をトリミングします。文字列リテラル `'2008-'` のトリム文字は、左からトリミングされる文字を示します。トリム文字 `'028-'` を使用した場合も、同じ結果が得られます。
```
select listid, listtime, ltrim(listtime, '2008-')
from listing
order by 1, 2, 3
limit 10;
listid | listtime | ltrim
-------+---------------------+----------------
1 | 2008-01-24 06:43:29 | 1-24 06:43:29
2 | 2008-03-05 12:25:29 | 3-05 12:25:29
3 | 2008-11-01 07:35:33 | 11-01 07:35:33
4 | 2008-05-24 01:18:37 | 5-24 01:18:37
5 | 2008-05-17 02:29:11 | 5-17 02:29:11
6 | 2008-08-15 02:08:13 | 15 02:08:13
7 | 2008-11-15 09:38:15 | 11-15 09:38:15
8 | 2008-11-09 05:07:30 | 11-09 05:07:30
9 | 2008-09-09 08:03:36 | 9-09 08:03:36
10 | 2008-06-17 09:44:54 | 6-17 09:44:54
```
LTRIM は、*文字列*の先頭にあるとき、*trim\$1chars* の文字をすべて削除します。次の例は、文字 'C'、'D'、および 'G' が VENUENAME の先頭にある場合 (VARCHAR 列) 、これらの文字を切り捨てます。
```
select venueid, venuename, ltrim(venuename, 'CDG')
from venue
where venuename like '%Park'
order by 2
limit 7;
venueid | venuename | btrim
--------+----------------------------+--------------------------
121 | ATT Park | ATT Park
109 | Citizens Bank Park | itizens Bank Park
102 | Comerica Park | omerica Park
9 | Dick's Sporting Goods Park | ick's Sporting Goods Park
97 | Fenway Park | Fenway Park
112 | Great American Ball Park | reat American Ball Park
114 | Miller Park | Miller Park
```
次の例では、`venueid` 列から取得されたしたトリム文字 `2` を使用します。
```
select ltrim('2008-01-24 06:43:29', venueid)
from venue where venueid=2;
ltrim
------------------
008-01-24 06:43:29
```
次の例では、`2` が `'0'` トリム文字の前にあるため、文字はトリミングされません。
```
select ltrim('2008-01-24 06:43:29', '0');
ltrim
-------------------
2008-01-24 06:43:29
```
次の例では、デフォルトのスペーストリム文字を使用して、文字列の先頭から 2 つのスペースをトリミングします。
```
select ltrim(' 2008-01-24 06:43:29');
ltrim
-------------------
2008-01-24 06:43:29
```
# POSITION 関数
文字列内の指定されたサブ文字列の位置を返します。
## 構文
```
POSITION(substring IN string )
```
## 引数
*substring*
*string* 内を検索するサブ文字列。
*string*
検索する文字列または列。
## 戻り型
POSITION 関数は、サブ文字列の位置 (0 ではなく 1 から始まる) に対応する整数を返します。位置はバイト数ではなく文字数に基づくため、マルチバイト文字は 1 文字としてカウントされます。
## 使用に関する注意事項
文字列内のサブ文字列がない場合、POSITION は 0 を返します。
```
select position('dog' in 'fish');
position
----------
0
(1 row)
```
## 例
次の例では、`fish`という語の中での文字列 `dogfish` の位置を示します。
```
select position('fish' in 'dogfish');
position
----------
4
(1 row)
```
次の例は、SALES テーブル内で COMMISSION が 999.00 を上回る販売取引の数を返します。
```
select distinct position('.' in commission), count (position('.' in commission))
from sales where position('.' in commission) > 4 group by position('.' in commission)
order by 1,2;
position | count
---------+-------
5 | 629
(1 row)
```
# REGEXP\$1COUNT 関数
文字列で正規表現パターンを検索し、このパターンが文字列内に出現する回数を示す整数を返します。一致がない場合、この関数は 0 を返します。
## 構文
```
REGEXP_COUNT ( source_string, pattern [, position [, parameters ] ] )
```
## 引数
*source\$1string*
検索する文字列式 (列名など)。
*pattern*
正規表現パターンを表す文字列リテラル。
*position*
検索を開始する *source\$1string* 内の位置を示す正の整数。position はバイト数ではなく文字数に基づくため、マルチバイト文字は 1 文字としてカウントされます。デフォルトは 1 です。*position* が 1 より小さい場合、*source\$1string* の最初の文字から検索が開始されます。*position* が *source\$1string* の文字数より大きい場合、結果は 0 になります。
*パラメータ*
関数がパターンと一致するかを示す 1 つ以上のリテラル文字列。取り得る値には以下のものがあります。
+ c – 大文字と小文字を区別する一致を実行します。デフォルトでは大文字と小文字を区別するマッチングを使用します。
+ i – 大文字と小文字を区別しない一致を実行します。
+ p – Perl 互換正規表現 (PCRE) 言語でパターンを解釈します。
## 戻り型
整数
## 例
次の例は、3 文字のシーケンスが出現する回数をカウントします。
```
SELECT regexp_count('abcdefghijklmnopqrstuvwxyz', '[a-z]{3}');
regexp_count
--------------
8
```
次の例は、最上位ドメイン名が `org` または `edu` である回数をカウントします。
```
SELECT email, regexp_count(email,'@[^.]*\\.(org|edu)')FROM users
ORDER BY userid LIMIT 4;
email | regexp_count
-----------------------------------------------+--------------
Etiam.laoreet.libero@sodalesMaurisblandit.edu | 1
Suspendisse.tristique@nonnisiAenean.edu | 1
amet.faucibus.ut@condimentumegetvolutpat.ca | 0
sed@lacusUtnec.ca | 0
```
次の例では、大文字と小文字を区別しない一致を使用して、文字列 `FOX` の出現をカウントします。
```
SELECT regexp_count('the fox', 'FOX', 1, 'i');
regexp_count
--------------
1
```
次の例では、PCRE 言語で記述されたパターンを使用して、少なくとも 1 つの数字と 1 つの小文字を含む単語を検索します。PCRE で特定の先読みの意味を持つ `?=` 演算子を使用します。この例では、大文字と小文字を区別して、このような単語の出現回数をカウントします。
```
SELECT regexp_count('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 'p');
regexp_count
--------------
2
```
次の例では、PCRE 言語で記述されたパターンを使用して、少なくとも 1 つの数字と 1 つの小文字を含む単語を検索します。これは、PCRE で特定の意味を持つ `?=` 演算子を使用します。この例では、このような単語の出現回数をカウントしますが、大文字と小文字を区別しない一致結果を使用する点で前の例とは異なります。
```
SELECT regexp_count('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 'ip');
regexp_count
--------------
3
```
# REGEXP\$1INSTR 関数
文字列で正規表現パターンを検索し、一致するサブ文字列の開始位置を示す整数を返します。一致がない場合、この関数は 0 を返します。REGEXP\$1INSTR は [ 関数に似ていますが、文字列で正規表現パターンを検索することができます。](POSITION.md)
## 構文
```
REGEXP_INSTR ( source_string, pattern [, position [, occurrence] [, option [, parameters ] ] ] ] )
```
## 引数
*source\$1string*
検索する文字列式 (列名など)。
*pattern*
正規表現パターンを表す文字列リテラル。
*position*
検索を開始する *source\$1string* 内の位置を示す正の整数。position はバイト数ではなく文字数に基づくため、マルチバイト文字は 1 文字としてカウントされます。デフォルトは 1 です。*position* が 1 より小さい場合、*source\$1string* の最初の文字から検索が開始されます。*position* が *source\$1string* の文字数より大きい場合、結果は 0 になります。
*occurrence*
このパターンのどの出現を使用するかを示す正の整数。REGEXP\$1INSTR は、最初の*出現* - 1 一致をスキップします。デフォルトは 1 です。*出現*が 1 未満、または*ソース文字列*の文字数以上の場合、検索は無視され、結果は 0 となります。
*option*
一致の先頭文字の戻り位置 (`0`)、あるいは続く一致の後尾の最初の文字位置 (`1`) のどちらかを示す値。ゼロ以外の値は 1 と同じです。デフォルト値は 0 です。
*パラメータ*
関数がパターンと一致するかを示す 1 つ以上のリテラル文字列。取り得る値には以下のものがあります。
+ c – 大文字と小文字を区別する一致を実行します。デフォルトでは大文字と小文字を区別するマッチングを使用します。
+ i – 大文字と小文字を区別しない一致を実行します。
+ e – 部分式を使用して部分文字列を抽出します。
*パターン*に部分式が含まれる場合、REGEXP\$1INSTR は最初の部分式を*パターン*で使用して部分文字列を一致させます。REGEXP\$1INSTR は最初の部分式のみを考慮します。追加の部分式は無視されます。パターンに部分式がない場合、REGEXP\$1INSTR は「e」パラメータを無視します。
+ p – Perl 互換正規表現 (PCRE) 言語でパターンを解釈します。
## 戻り型
整数
## 例
次の例は、ドメイン名を開始する `@` 文字を検索し、最初の一致の開始位置を返します。
```
SELECT email, regexp_instr(email, '@[^.]*')
FROM users
ORDER BY userid LIMIT 4;
email | regexp_instr
-----------------------------------------------+--------------
Etiam.laoreet.libero@example.com | 21
Suspendisse.tristique@nonnisiAenean.edu | 22
amet.faucibus.ut@condimentumegetvolutpat.ca | 17
sed@lacusUtnec.ca | 4
```
次の例は、`Center`という単語のバリエーションを検索し、最初の一致の開始位置を返します。
```
SELECT venuename, regexp_instr(venuename,'[cC]ent(er|re)$')
FROM venue
WHERE regexp_instr(venuename,'[cC]ent(er|re)$') > 0
ORDER BY venueid LIMIT 4;
venuename | regexp_instr
-----------------------+--------------
The Home Depot Center | 16
Izod Center | 6
Wachovia Center | 10
Air Canada Centre | 12
```
次の例は、大文字と小文字を区別しない一致ロジックを使用して、文字列 `FOX` が最初に出現する開始位置を検索します。
```
SELECT regexp_instr('the fox', 'FOX', 1, 1, 0, 'i');
regexp_instr
--------------
5
```
次の例では、PCRE 言語で記述されたパターンを使用して、少なくとも 1 つの数字と 1 つの小文字を含む単語を検索します。PCRE で特定の先読みの意味を持つ `?=` 演算子を使用します。この例では、2 番目の単語の開始位置を見つけます。
```
SELECT regexp_instr('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 2, 0, 'p');
regexp_instr
--------------
21
```
次の例では、PCRE 言語で記述されたパターンを使用して、少なくとも 1 つの数字と 1 つの小文字を含む単語を検索します。PCRE で特定の先読みの意味を持つ `?=` 演算子を使用します。この例では、2 番目の単語の開始位置を検索しますが、大文字と小文字を区別しない一致結果を使用する点で前の例とは異なります。
```
SELECT regexp_instr('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 2, 0, 'ip');
regexp_instr
--------------
15
```
# REGEXP\$1REPLACE 関数
文字列で正規表現パターンを検索し、このパターンのすべての出現を特定の文字列に置き換えます。REGEXP\$1REPLACE は [REPLACE 関数](REPLACE.md) 関数に似ていますが、文字列で正規表現パターンを検索することができます。
REGEXP\$1REPLACE は、[TRANSLATE 関数](TRANSLATE.md)や [REPLACE 関数](REPLACE.md) と似ています。ただし、TRANSLATE は複数の単一文字置換を行い、REPLACE は 1 つの文字列全体を別の文字列に置換しますが、REGEXP\$1REPLACE を使用すると正規表現パターンの文字列を検索できます。
## 構文
```
REGEXP_REPLACE ( source_string, pattern [, replace_string [ , position [, parameters ] ] ] )
```
## 引数
*source\$1string*
検索する文字列式 (列名など)。
*pattern*
正規表現パターンを表す文字列リテラル。
*replace\$1string*
パターンのすべての出現に置き換わる列名などの文字列式。デフォルトは空の文字列 ("") です。
*position*
検索を開始する *source\$1string* 内の位置を示す正の整数。position はバイト数ではなく文字数に基づくため、マルチバイト文字は 1 文字としてカウントされます。デフォルトは 1 です。*position* が 1 より小さい場合、*source\$1string* の最初の文字から検索が開始されます。*position* が *source\$1string* の文字数より大きい場合、結果は *source\$1string* になります。
*パラメータ*
関数がパターンと一致するかを示す 1 つ以上のリテラル文字列。取り得る値には以下のものがあります。
+ c – 大文字と小文字を区別する一致を実行します。デフォルトでは大文字と小文字を区別するマッチングを使用します。
+ i – 大文字と小文字を区別しない一致を実行します。
+ p – Perl 互換正規表現 (PCRE) 言語でパターンを解釈します。
## 戻り型
VARCHAR
*pattern* または *replace\$1string* のいずれかが NULL の場合、戻り値は NULL です。
## 例
次の例は、メールアドレスから `@` とドメイン名を削除します。
```
SELECT email, regexp_replace(email, '@.*\\.(org|gov|com|edu|ca)$')
FROM users
ORDER BY userid LIMIT 4;
email | regexp_replace
-----------------------------------------------+----------------
Etiam.laoreet.libero@sodalesMaurisblandit.edu | Etiam.laoreet.libero
Suspendisse.tristique@nonnisiAenean.edu | Suspendisse.tristique
amet.faucibus.ut@condimentumegetvolutpat.ca | amet.faucibus.ut
sed@lacusUtnec.ca | sed
```
次の例は、E メールアドレスのドメイン名を値 `internal.company.com` に置き換えます。
```
SELECT email, regexp_replace(email, '@.*\\.[[:alpha:]]{2,3}',
'@internal.company.com') FROM users
ORDER BY userid LIMIT 4;
email | regexp_replace
-----------------------------------------------+--------------------------------------------
Etiam.laoreet.libero@sodalesMaurisblandit.edu | Etiam.laoreet.libero@internal.company.com
Suspendisse.tristique@nonnisiAenean.edu | Suspendisse.tristique@internal.company.com
amet.faucibus.ut@condimentumegetvolutpat.ca | amet.faucibus.ut@internal.company.com
sed@lacusUtnec.ca | sed@internal.company.com
```
次の例は、大文字と小文字を区別しない一致を使用して、値 `quick brown fox` 内の文字列 `FOX` のすべての出現箇所を置き換えます。
```
SELECT regexp_replace('the fox', 'FOX', 'quick brown fox', 1, 'i');
regexp_replace
---------------------
the quick brown fox
```
次の例では、PCRE 言語で記述されたパターンを使用して、少なくとも 1 つの数字と 1 つの小文字を含む単語を検索します。PCRE で特定の先読みの意味を持つ `?=` 演算子を使用します。この例では、そのような単語が出現するたびに値 `[hidden]` に置き換えられます。
```
SELECT regexp_replace('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', '[hidden]', 1, 'p');
regexp_replace
-------------------------------
[hidden] plain A1234 [hidden]
```
次の例では、PCRE 言語で記述されたパターンを使用して、少なくとも 1 つの数字と 1 つの小文字を含む単語を検索します。PCRE で特定の先読みの意味を持つ `?=` 演算子を使用します。この例では、このような単語が出現するたびに値 `[hidden]` に置き換えられますが、大文字と小文字を区別しない一致結果を使用するという点で前の例とは異なります。
```
SELECT regexp_replace('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', '[hidden]', 1, 'ip');
regexp_replace
----------------------------------
[hidden] plain [hidden] [hidden]
```
# REGEXP\$1SUBSTR 関数
正規表現パターンで検索して、文字列から文字を返します。REGEXP\$1SUBSTR は [SUBSTRING 関数](SUBSTRING.md) 関数に似ていますが、文字列で正規表現パターンを検索することができます。この関数が正規表現を文字列内のどの文字とも一致させることができない場合、空の文字列を返します。
## 構文
```
REGEXP_SUBSTR ( source_string, pattern [, position [, occurrence [, parameters ] ] ] )
```
## 引数
*source\$1string*
検索する文字列式。
*pattern*
正規表現パターンを表す文字列リテラル。
*position*
検索を開始する *source\$1string* 内の位置を示す正の整数。位置はバイト数ではなく文字数に基づくため、マルチバイト文字は 1 文字としてカウントされます。デフォルトは 1 です。*position* が 1 より小さい場合、*source\$1string* の最初の文字から検索が開始されます。*position* が *source\$1string* の文字数より大きい場合、結果は空の文字列 ("") になります。
*occurrence*
このパターンのどの出現を使用するかを示す正の整数。REGEXP\$1SUBSTR は、最初の*出現* - 1 一致をスキップします。デフォルトは 1 です。*出現*が 1 未満、または*ソース文字列*の文字数以上の場合、検索は無視され、結果は NULL となります。
*パラメータ*
関数がパターンと一致するかを示す 1 つ以上のリテラル文字列。取り得る値には以下のものがあります。
+ c – 大文字と小文字を区別する一致を実行します。デフォルトでは大文字と小文字を区別するマッチングを使用します。
+ i – 大文字と小文字を区別しない一致を実行します。
+ e – 部分式を使用して部分文字列を抽出します。
*パターン*に部分式が含まれる場合、REGEXP\$1SUBSTR は最初の部分式を*パターン*で使用して部分文字列を一致させます。部分式は、かっこで囲まれたパターン内の式です。例えば、`'This is a (\\w+)'` というパターンでは、最初の式と `'This is a '` という文字列とそれに続く単語が一致します。`e` パラメータを指定した REGEXP\$1SUBSTR は、*パターン*を返す代わりに、部分式の中の文字列だけを返します。
REGEXP\$1SUBSTR は最初の部分式のみを考慮します。追加の部分式は無視されます。パターンに部分式がない場合、REGEXP\$1SUBSTR は「e」パラメータを無視します。
+ p – Perl 互換正規表現 (PCRE) 言語でパターンを解釈します。
## 戻り型
VARCHAR
## 例
次の例では、メールアドレスの @ 文字とドメイン拡張の間の分が返されます。
```
SELECT email, regexp_substr(email,'@[^.]*')
FROM users
ORDER BY userid LIMIT 4;
email | regexp_substr
-----------------------------------------------+--------------------------
Etiam.laoreet.libero@sodalesMaurisblandit.edu | @sodalesMaurisblandit
Suspendisse.tristique@nonnisiAenean.edu | @nonnisiAenean
amet.faucibus.ut@condimentumegetvolutpat.ca | @condimentumegetvolutpat
sed@lacusUtnec.ca | @lacusUtnec
```
次の例は、大文字と小文字を区別しない一致を使用して、文字列 `FOX` の最初の出現に対応する入力の部分を返します。
```
SELECT regexp_substr('the fox', 'FOX', 1, 1, 'i');
regexp_substr
---------------
fox
```
次の例では、小文字で始まる入力の最初の部分を返します。これは、同じ SELECT ステートメントで `c` パラメータを指定しない場合と機能的には同じです。
```
SELECT regexp_substr('THE SECRET CODE IS THE LOWERCASE PART OF 1931abc0EZ.', '[a-z]+', 1, 1, 'c');
regexp_substr
---------------
abc
```
次の例では、PCRE 言語で記述されたパターンを使用して、少なくとも 1 つの数字と 1 つの小文字を含む単語を検索します。PCRE で特定の先読みの意味を持つ `?=` 演算子を使用します。この例では、2 番目の単語に対応する入力部分を返します。
```
SELECT regexp_substr('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 2, 'p');
regexp_substr
---------------
a1234
```
次の例では、PCRE 言語で記述されたパターンを使用して、少なくとも 1 つの数字と 1 つの小文字を含む単語を検索します。PCRE で特定の先読みの意味を持つ `?=` 演算子を使用します。この例では、2 番目の単語に対応する入力部分を返しますが、大文字と小文字を区別しない一致結果を使用する点で前の例とは異なります。
```
SELECT regexp_substr('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 2, 'ip');
regexp_substr
---------------
A1234
```
次の例では、部分式を使用して、大文字と小文字を区別しないマッチングにより、パターン `'this is a (\\w+)'` と一致する 2 番目の文字列を見つけます。かっこ内の部分式を返します。
```
select regexp_substr(
'This is a cat, this is a dog. This is a mouse.',
'this is a (\\w+)', 1, 2, 'ie');
regexp_substr
---------------
dog
```
# REPEAT 関数
指定された回数だけ文字列を繰り返します。入力パラメータが数値である場合、REPEAT はそれを文字列として扱います。
## 構文
```
REPEAT(string, integer)
```
## 引数
*string*
最初の入力パラメータは、繰り返す文字列です。
*integer*
2 番目のパラメータは、文字列を繰り返す回数を示す整数です。
## 戻り型
REPEAT 関数は文字列を返します。
## 例
次の例では、CATEGORY テーブル内の CATID 列の値を 3 回繰り返します。
```
select catid, repeat(catid,3)
from category
order by 1,2;
catid | repeat
-------+--------
1 | 111
2 | 222
3 | 333
4 | 444
5 | 555
6 | 666
7 | 777
8 | 888
9 | 999
10 | 101010
11 | 111111
(11 rows)
```
# REPLACE 関数
既存の文字列内の一連の文字をすべて、指定された他の文字に置き換えます。
REPLACE は、[TRANSLATE 関数](TRANSLATE.md)や [REGEXP\$1REPLACE 関数](REGEXP_REPLACE.md) と似ています。ただし、TRANSLATE は複数の単一文字置換を行い、REGEXP\$1REPLACE を使用すると正規表現パターンの文字列を検索できますが、REPLACE は 1 つの文字列全体を別の文字列に置換します。
## 構文
```
REPLACE(string1, old_chars, new_chars)
```
## 引数
*string*
検索する CHAR 型または VARCHAR 型の文字列。
*old\$1chars*
置き換える CHAR 型または VARCHAR 型の文字列。
*new\$1chars*
*old\$1string* を置き換える新しい CHAR 型または VARCHAR 型の文字列。
## 戻り型
VARCHAR
*old\$1chars* または *new\$1chars* のいずれかが NULL の場合、戻り値は NULL です。
## 例
次の例では、CATGROUP フィールド内の文字列 `Shows` を `Theatre` に変換します。
```
select catid, catgroup,
replace(catgroup, 'Shows', 'Theatre')
from category
order by 1,2,3;
catid | catgroup | replace
-------+----------+----------
1 | Sports | Sports
2 | Sports | Sports
3 | Sports | Sports
4 | Sports | Sports
5 | Sports | Sports
6 | Shows | Theatre
7 | Shows | Theatre
8 | Shows | Theatre
9 | Concerts | Concerts
10 | Concerts | Concerts
11 | Concerts | Concerts
(11 rows)
```
# REVERSE 関数
REVERSE 関数は、文字列に対して機能し、文字を逆順に返します。たとえば、`reverse('abcde')`は `edcba` を返します。この関数は、数値データ型と日付データ型に加え、文字データ型に対しても機能します。ただしほとんどの場合、文字列に対して実用的な値が生成されます。
## 構文
```
REVERSE ( expression )
```
## 引数
*expression*
文字反転のターゲットを表す文字、日付、タイムスタンプ、または数値のデータ型を使用した式。すべての式は、可変長文字列に暗黙的に変換されます。固定幅文字列の末尾の空白は無視されます。
## 戻り型
REVERSE は VARCHAR を返します。
## 例
USERS テーブルから、5 つの異なる都市名およびそれらに対応する反転した名前を選択します。
```
select distinct city as cityname, reverse(cityname)
from users order by city limit 5;
cityname | reverse
---------+----------
Aberdeen | needrebA
Abilene | enelibA
Ada | adA
Agat | tagA
Agawam | mawagA
(5 rows)
```
文字列として変換された 5 つの販売 ID およびそれらに対応する反転した ID を選択します。
```
select salesid, reverse(salesid)::varchar
from sales order by salesid desc limit 5;
salesid | reverse
--------+---------
172456 | 654271
172455 | 554271
172454 | 454271
172453 | 354271
172452 | 254271
(5 rows)
```
# RTRIM 関数
RTRIM 関数は、指定された一連の文字を文字列の末尾から切り捨てます。トリム文字リスト内の文字のみを含む最長の文字列を削除します。入力文字列にトリム文字が表示されない場合、トリミングは完了です。
## 構文
```
RTRIM( string, trim_chars )
```
## 引数
*string*
トリミングする文字列列、式、または文字列リテラル。
*trim\$1chars*
*文字列*の末尾から切り捨てる文字を表す、文字列の列、式、または文字列リテラル。指定しなかった場合、スペースがトリム文字として使用されます。
## 戻り型
*string* 引数と同じデータ型の文字列。
## 例
次の例では、文字列 `' abc '` の先頭および末尾の空白を切り捨てます。
```
select ' abc ' as untrim, rtrim(' abc ') as trim;
untrim | trim
----------+------
abc | abc
```
次の例では、文字列 `'xyzaxyzbxyzcxyz'` から末尾の文字列 `'xyz'` を削除します。末尾にある `'xyz'` は削除されましたが、文字列内部にあるその文字列は削除されません。
```
select 'xyzaxyzbxyzcxyz' as untrim,
rtrim('xyzaxyzbxyzcxyz', 'xyz') as trim;
untrim | trim
-----------------+-----------
xyzaxyzbxyzcxyz | xyzaxyzbxyzc
```
次の例では、*trim\$1chars* リスト `'tes'` のいずれかの文字と一致する文字列 `'setuphistorycassettes'` の末尾の部分を削除します。入力文字列の末尾にある *trim\$1chars* リストに含まれていない別の文字の前に出現する `t`、`e` または `s` が削除されます。
```
SELECT rtrim('setuphistorycassettes', 'tes');
rtrim
-----------------
setuphistoryca
```
次の例は、文字 'Park' が存在する VENUENAME の末尾から、これらの文字を切り捨てます。
```
select venueid, venuename, rtrim(venuename, 'Park')
from venue
order by 1, 2, 3
limit 10;
venueid | venuename | rtrim
--------+----------------------------+-------------------------
1 | Toyota Park | Toyota
2 | Columbus Crew Stadium | Columbus Crew Stadium
3 | RFK Stadium | RFK Stadium
4 | CommunityAmerica Ballpark | CommunityAmerica Ballp
5 | Gillette Stadium | Gillette Stadium
6 | New York Giants Stadium | New York Giants Stadium
7 | BMO Field | BMO Field
8 | The Home Depot Center | The Home Depot Cente
9 | Dick's Sporting Goods Park | Dick's Sporting Goods
10 | Pizza Hut Park | Pizza Hut
```
RTRIM は、文字 `P`、`a`、`r`、または `k` が VENUENAME の末尾にあるとき、それらをすべて削除することに注意してください。
# SPLIT 関数
SPLIT 関数を使用すると、より大きな文字列から部分文字列を抽出し、配列として使用できます。SPLIT 関数は、特定の区切り文字またはパターンに基づいて文字列を個々のコンポーネントに分割する必要がある場合に便利です。
## 構文
```
split(str, regex, limit)
```
## 引数
*str*
分割する文字列式。
*[正規表現]*
正規表現を表す文字列。*正規表現*文字列は Java 正規表現である必要があります。
*制限*
*正規表現*が適用される回数を制御する整数式。
+ limit > 0: 結果の配列の長さは制限を超えず、結果の配列の最後のエントリには、最後に一致した*正規表現*を超えるすべての入力が含まれます。
+ limit <= 0: *正規表現*は可能な限り複数回適用され、結果の配列は任意のサイズにすることができます。
## 戻り型
SPLIT 関数は ARRAY を返します。
の場合`limit > 0`: 結果の配列の長さは制限を超えず、結果の配列の最後のエントリには、最後に一致した正規表現を超えるすべての入力が含まれます。
の場合`limit <= 0`: 正規表現は可能な限り複数回適用され、結果の配列は任意のサイズにすることができます。
## 例
この例では、SPLIT 関数は、文字 `'A'`、、`'B'`または `'C'` (正規表現パターン で指定) に遭遇する`'oneAtwoBthreeC'`場所に入力文字列を分割します`'[ABC]'`。結果の出力は、`"one"`、、`"two"`、`"three"`および空の文字列 の 4 つの要素の配列です`""`。
```
SELECT split('oneAtwoBthreeC', '[ABC]');
["one","two","three",""]
```
# SPLIT\$1PART 関数
指定された区切り記号で文字列を分割し、指定された位置にあるパートを返します。
## 構文
```
SPLIT_PART(string, delimiter, position)
```
## 引数
*string*
分割する文字列の列、式、または文字列リテラル。文字列には CHAR 型または VARCHAR 型を指定できます。
*delimiter*
入力*文字列*のセクションを示す区切り文字列。
*delimiter* がリテラルである場合は、それを一重引用符で囲みます。
*position*
返す*文字列*の部分の位置 (1 からカウント)。1 以上の整数である必要があります。*位置*が文字列の部分の数より大きい場合、SPLIT\$1PART は空の文字列を返します。*文字列*で*区切り文字*が見つからない場合、戻り値には指定された部分の内容が含まれます。これは、*文字列*全体または空の値である可能性があります。
## 戻り型
CHAR 文字列または VARCHAR 文字列 (*文字列*パラメータと同じ型)。
## 例
次の例では、`$` 区切り文字を使用して文字列リテラルを複数の部分に分割し、2 番目の部分を返します。
```
select split_part('abc$def$ghi','$',2)
split_part
----------
def
```
次の例では、`$` 区切り文字を使用して文字列リテラルを複数の部分に分割します。`4` の部分が見つからないため、空の文字列が返されます。
```
select split_part('abc$def$ghi','$',4)
split_part
----------
```
次の例では、`#` 区切り文字を使用して文字列リテラルを複数の部分に分割します。区切り文字が見つからないため、最初の部分である文字列全体が返されます。
```
select split_part('abc$def$ghi','#',1)
split_part
------------
abc$def$ghi
```
次の例は、タイムスタンプフィールド LISTTIME を年コンポーネント、月コンポーネント、および日コンポーネントに分割します。
```
select listtime, split_part(listtime,'-',1) as year,
split_part(listtime,'-',2) as month,
split_part(split_part(listtime,'-',3),' ',1) as day
from listing limit 5;
listtime | year | month | day
---------------------+------+-------+------
2008-03-05 12:25:29 | 2008 | 03 | 05
2008-09-09 08:03:36 | 2008 | 09 | 09
2008-09-26 05:43:12 | 2008 | 09 | 26
2008-10-04 02:00:30 | 2008 | 10 | 04
2008-01-06 08:33:11 | 2008 | 01 | 06
```
次の例は、LISTTIME タイムスタンプフィールドを選択し、それを `'-'` 文字で分割して月 (LISTTIME 文字列の 2 番目の部分) を取得してから、各月のエントリ数をカウントします。
```
select split_part(listtime,'-',2) as month, count(*)
from listing
group by split_part(listtime,'-',2)
order by 1, 2;
month | count
-------+-------
01 | 18543
02 | 16620
03 | 17594
04 | 16822
05 | 17618
06 | 17158
07 | 17626
08 | 17881
09 | 17378
10 | 17756
11 | 12912
12 | 4589
```
# SUBSTRING 関数
文字列内で、指定された開始位置からの文字列のサブセットを返します。
入力が文字列の場合、抽出される文字の開始位置および文字数はバイト数ではなく文字数に基づきます。つまり、マルチバイト文字は 1 文字としてカウントされます。入力がバイナリ式の場合、開始位置と抽出される部分文字列はバイト数に基づきます。負の長さを指定することはできませんが、開始位置を負に指定することは可能です。
## 構文
```
SUBSTRING(charactestring FROM start_position [ FOR numbecharacters ] )
```
```
SUBSTRING(charactestring, start_position, numbecharacters )
```
```
SUBSTRING(binary_expression, start_byte, numbebytes )
```
```
SUBSTRING(binary_expression, start_byte )
```
## 引数
*charactestring*
検索する文字列。文字データ型以外のデータ型は、文字列のように扱われます。
*start\$1position*
文字列内で抽出を開始する位置 (1 から始まる)。*start\$1position* はバイト数ではなく文字数に基づくため、マルチバイト文字は 1 文字としてカウントされます。負の数を指定することもできます。
*numbecharacters*
抽出する文字の数 (サブ文字列の長さ)。*数値文字*はバイト数ではなく文字数に基づいているため、マルチバイト文字は 1 文字としてカウントされます。負の数を指定することはできません。
*start\$1byte*
バイナリ表現内の抽出を開始する (先頭を 1 とする) 位置。負の数を指定することもできます。
*numbebytes*
抽出するバイト数 (サブ文字列の長さ)。負の数を指定することはできません。
## 戻り型
VARCHAR
## 文字列の使用に関する注意事項
次の例では、6 番目の文字で始まる 4 文字の文字列を返します。
```
select substring('caterpillar',6,4);
substring
-----------
pill
(1 row)
```
*start\$1position* \$1 *numbecharacters* が*文字列*の長さを超える場合、SUBSTRING は *start\$1position* から文字列の末尾まで部分文字列を返します。例:
```
select substring('caterpillar',6,8);
substring
-----------
pillar
(1 row)
```
`start_position` が負の数または 0 である場合、SUBSTRING 関数は、文字列の先頭文字から `start_position` \$1 `numbecharacters` -1 文字までをサブ文字列として返します。次に例を示します。
```
select substring('caterpillar',-2,6);
substring
-----------
cat
(1 row)
```
`start_position` \$1 `numbecharacters` -1 が 0 以下である場合、SUBSTRING は空の文字列を返します。次に例を示します。
```
select substring('caterpillar',-5,4);
substring
-----------
(1 row)
```
## 例
次の例は、LISTING テーブル内の LISTTIME 文字列から月を返します。
```
select listid, listtime,
substring(listtime, 6, 2) as month
from listing
order by 1, 2, 3
limit 10;
listid | listtime | month
--------+---------------------+-------
1 | 2008-01-24 06:43:29 | 01
2 | 2008-03-05 12:25:29 | 03
3 | 2008-11-01 07:35:33 | 11
4 | 2008-05-24 01:18:37 | 05
5 | 2008-05-17 02:29:11 | 05
6 | 2008-08-15 02:08:13 | 08
7 | 2008-11-15 09:38:15 | 11
8 | 2008-11-09 05:07:30 | 11
9 | 2008-09-09 08:03:36 | 09
10 | 2008-06-17 09:44:54 | 06
(10 rows)
```
次の例は上記と同じですが、FROM...FOR オプションを使用します。
```
select listid, listtime,
substring(listtime from 6 for 2) as month
from listing
order by 1, 2, 3
limit 10;
listid | listtime | month
--------+---------------------+-------
1 | 2008-01-24 06:43:29 | 01
2 | 2008-03-05 12:25:29 | 03
3 | 2008-11-01 07:35:33 | 11
4 | 2008-05-24 01:18:37 | 05
5 | 2008-05-17 02:29:11 | 05
6 | 2008-08-15 02:08:13 | 08
7 | 2008-11-15 09:38:15 | 11
8 | 2008-11-09 05:07:30 | 11
9 | 2008-09-09 08:03:36 | 09
10 | 2008-06-17 09:44:54 | 06
(10 rows)
```
文字列にマルチバイト文字が含まれる可能性がある場合、SUBSTRING を使用して文字列の先頭部分を期待どおりに抽出することはできません。これは、マルチバイト文字列の長さを、文字数ではなくバイト数に基づいて指定する必要があるためです。バイト数での長さに基づいて文字列の最初のセグメントを取得するためには、文字列を VARCHAR(*byte\$1length*) として CAST することで文字列を切り捨てます。このとき、*byte\$1length* は必要な長さとなります。次の例では、文字列 `'Fourscore and seven'` から最初の 5 バイトを抽出します。
```
select cast('Fourscore and seven' as varchar(5));
varchar
-------
Fours
```
次の例では、入力文字列 `Ana` の最後のスペースの後に表示される最初の名前 `Silva, Ana` を返します。
```
select reverse(substring(reverse('Silva, Ana'), 1, position(' ' IN reverse('Silva, Ana'))))
reverse
-----------
Ana
```
# TRANSLATE 関数
任意の式において、指定された文字をすべて、指定された別の文字に置き換えます。既存の文字は、*characters\$1to\$1replace* 引数および *characters\$1to\$1substitute* 引数内の位置により置換文字にマッピングされます。*characters\$1to\$1replace* 引数で *characters\$1to\$1substitute* 引数よりも多くの文字が指定されている場合、*characters\$1to\$1replace* 引数からの余分な文字は戻り値で省略されます。
TRANSLATE は、[REPLACE 関数](REPLACE.md)や [REGEXP\$1REPLACE 関数](REGEXP_REPLACE.md) と似ています。ただし、REPLACE は 1 つの文字列全体を別の文字列に置換し、REGEXP\$1REPLACE を使用すると正規表現パターンの文字列を検索できますが、TRANSLATE は複数の単一文字置換を行います。
いずれかの引数が null である場合、戻り値は NULL になります。
## 構文
```
TRANSLATE ( expression, characters_to_replace, characters_to_substitute )
```
## 引数
*expression*
変換する式。
*characters\$1to\$1replace*
置換する文字を含む文字列。
*characters\$1to\$1substitute*
代入する文字を含む文字列。
## 戻り型
VARCHAR
## 例
以下の例では、文字列内の複数の文字が置換されます。
```
select translate('mint tea', 'inea', 'osin');
translate
-----------
most tin
```
次の例では、列内のすべての値のアットマーク (@) がピリオドに置き換えられます。
```
select email, translate(email, '@', '.') as obfuscated_email
from users limit 10;
email obfuscated_email
-------------------------------------------------------------------------------------------
Etiam.laoreet.libero@sodalesMaurisblandit.edu Etiam.laoreet.libero.sodalesMaurisblandit.edu
amet.faucibus.ut@condimentumegetvolutpat.ca amet.faucibus.ut.condimentumegetvolutpat.ca
turpis@accumsanlaoreet.org turpis.accumsanlaoreet.org
ullamcorper.nisl@Cras.edu ullamcorper.nisl.Cras.edu
arcu.Curabitur@senectusetnetus.com arcu.Curabitur.senectusetnetus.com
ac@velit.ca ac.velit.ca
Aliquam.vulputate.ullamcorper@amalesuada.org Aliquam.vulputate.ullamcorper.amalesuada.org
vel.est@velitegestas.edu vel.est.velitegestas.edu
dolor.nonummy@ipsumdolorsit.ca dolor.nonummy.ipsumdolorsit.ca
et@Nunclaoreet.ca et.Nunclaoreet.ca
```
次の例では、列内のすべての値のスペースがアンダースコアに置き換えられ、ピリオドが削除されます。
```
select city, translate(city, ' .', '_') from users
where city like 'Sain%' or city like 'St%'
group by city
order by city;
city translate
--------------+------------------
Saint Albans Saint_Albans
Saint Cloud Saint_Cloud
Saint Joseph Saint_Joseph
Saint Louis Saint_Louis
Saint Paul Saint_Paul
St. George St_George
St. Marys St_Marys
St. Petersburg St_Petersburg
Stafford Stafford
Stamford Stamford
Stanton Stanton
Starkville Starkville
Statesboro Statesboro
Staunton Staunton
Steubenville Steubenville
Stevens Point Stevens_Point
Stillwater Stillwater
Stockton Stockton
Sturgis Sturgis
```
# TRIM 関数
先頭および末尾の空白を削除するか、またはオプションで指定された文字列と一致する先頭および末尾の文字を削除することによって、文字列を切り捨てます。
## 構文
```
TRIM( [ BOTH ] [ trim_chars FROM ] string
```
## 引数
*trim\$1chars*
(オプション) 文字列から切り捨てられる文字。このパラメータを省略すると、空白が切り捨てられます。
*string*
切り捨てる文字列。
## 戻り型
TRIM 関数は、VARCHAR 型または CHAR 型の文字列を返します。SQL コマンドで TRIM 関数を使用する場合、 は結果を VARCHAR に AWS Clean Rooms 暗黙的に変換します。SQL 関数の SELECT リストで TRIM 関数を使用する場合、 AWS Clean Rooms は結果を暗黙的に変換せず、データ型の不一致エラーを回避するために明示的な変換を実行する必要がある場合があります。明示的な変換については、 [CAST 関数](CAST_function.md)関数を参照してください。
## 例
次の例では、文字列 `' abc '` の先頭および末尾の空白を切り捨てます。
```
select ' abc ' as untrim, trim(' abc ') as trim;
untrim | trim
----------+------
abc | abc
```
次の例では、文字列 `"dog"` を囲む二重引用符を削除します。
```
select trim('"' FROM '"dog"');
btrim
-------
dog
```
LTRIM は、*文字列*の先頭にあるとき、*trim\$1chars* の文字をすべて削除します。次の例は、文字 'C'、'D'、および 'G' が VENUENAME の先頭にある場合 (VARCHAR 列) 、これらの文字を切り捨てます。
```
select venueid, venuename, trim(venuename, 'CDG')
from venue
where venuename like '%Park'
order by 2
limit 7;
venueid | venuename | btrim
--------+----------------------------+--------------------------
121 | ATT Park | ATT Park
109 | Citizens Bank Park | itizens Bank Park
102 | Comerica Park | omerica Park
9 | Dick's Sporting Goods Park | ick's Sporting Goods Park
97 | Fenway Park | Fenway Park
112 | Great American Ball Park | reat American Ball Park
114 | Miller Park | Miller Park
```
# UPPER 関数
文字列を大文字に変換します。UPPER は、UTF-8 マルチバイト文字に対応しています (1 文字につき最大で 4 バイトまで)。
## 構文
```
UPPER(string)
```
## 引数
*string*
入力パラメータは VARCHAR 文字列 (または CHAR など、暗黙的に VARCHAR に変換できるその他のデータ型) です。
## 戻り型
UPPER 関数は、入力文字列のデータ型と同じデータ型の文字列を返します。
## 例
次の例は、CATNAME フィールドを大文字に変換します。
```
select catname, upper(catname) from category order by 1,2;
catname | upper
----------+-----------
Classical | CLASSICAL
Jazz | JAZZ
MLB | MLB
MLS | MLS
Musicals | MUSICALS
NBA | NBA
NFL | NFL
NHL | NHL
Opera | OPERA
Plays | PLAYS
Pop | POP
(11 rows)
```
# UUID 関数
UUID 関数は、Universally Unique Identifier (UUID) を生成します。
UUIDsはグローバルに一意の識別子であり、次のようなさまざまな目的で一意の識別子を提供するために一般的に使用されます。
+ データベースレコードまたはその他のデータエンティティの識別。
+ ファイル、ディレクトリ、またはその他のリソースの一意の名前またはキーを生成します。
+ 分散システム全体のデータを追跡し、関連付けます。
+ ネットワークパケット、ソフトウェアコンポーネント、またはその他のデジタルアセットに一意の識別子を提供します。
UUID 関数は、分散システム間および長期間にわたっても、非常に高い確率で一意の UUID 値を生成します。UUIDsは通常、現在のタイムスタンプ、コンピュータのネットワークアドレス、およびその他のランダムまたは擬似ランダムデータの組み合わせを使用して生成され、生成された各 UUID が他の UUID と競合する可能性はほとんどありません。
SQL クエリのコンテキストでは、UUID 関数を使用して、データベースに挿入される新しいレコードの一意の識別子を生成したり、データのパーティショニング、インデックス作成、または一意の識別子が必要なその他の目的で一意のキーを提供したりできます。
**注記**
UUID 関数は非決定的です。
## 構文
```
uuid()
```
## 引数
UUID 関数は引数を取りません。
## 戻り型
UUID は、ユニバーサル一意識別子 (UUID) 文字列を返します。値は正規 UUID 36 文字の文字列として返されます。
## 例
次の例では、Universally Unique Identifier (UUID) を生成します。出力は、Universally Unique Identifier を表す 36 文字の文字列です。
```
SELECT uuid();
46707d92-02f4-4817-8116-a4c3b23e6266
```
# プライバシー関連の機能
AWS Clean Rooms には、以下の仕様のプライバシー関連のコンプライアンスに準拠するのに役立つ機能が用意されています。
+ **グローバルプライバシープラットフォーム (GPP)** – オンラインプライバシーとデータ使用のためのグローバルで標準化されたフレームワークを確立する、Interactive Advertising Bureau (IAB) からの仕様。GPP の技術仕様の詳細については、[GitHub のグローバルプライバシープラットフォームのドキュメント](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform)を参照してください。
+ **Transparency and Framework Framework (TCF)** – 2020 年に開始された GPP の主要なコンポーネントであり、企業が EU 一般データ保護規則 (GDPR) などのプライバシー規制に準拠するための標準化された技術フレームワークを提供します。TCF を使用すると、お客様はデータ収集と処理への同意を付与または拒否できます。TCF の技術仕様の詳細については、[GitHub の TCF ドキュメント](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/tree/master/TCFv2)を参照してください。
**Topics**
+ [consent\$1gpp\$1v1\$1decode 関数](consent_gpp_v1_decode.md)
+ [consent\$1tcf\$1v2\$1decode 関数](consent_tcf_v2_decode.md)
# consent\$1gpp\$1v1\$1decode 関数
`consent_gpp_v1_decode` 関数は、グローバルプライバシープラットフォーム (GPP) v1 同意データをデコードするために使用されます。エンコードされた同意文字列を入力として受け取り、デコードされた同意データを返します。これには、ユーザーのプライバシー設定と同意の選択に関する情報が含まれます。この関数は、GPP v1 の同意情報を含むデータを操作する場合に便利です。これは、構造化された形式で同意データにアクセスして分析できるためです。
## 構文
```
consent_gpp_v1_decode(gpp_string)
```
## 引数
*gpp\$1string*
エンコードされた GPP v1 同意文字列。
## 戻り値
返されるディクショナリには、次のキーと値のペアが含まれます。
+ `version`: 使用されている GPP 仕様のバージョン (現在は 1)。
+ `cmpId`: 同意文字列をエンコードした同意管理プラットフォーム (CMP) の ID。
+ `cmpVersion`: 同意文字列をエンコードした CMP のバージョン。
+ `consentScreen`: ユーザーが同意した CMP UI の画面の ID。
+ `consentLanguage`: 同意情報の言語コード。
+ `vendorListVersion`: 使用されるベンダーリストのバージョン。
+ `publisherCountryCode`: パブリッシャーの国コード。
+ `purposeConsent`: ユーザーが同意した目的を表す整数のリスト。
+ `purposeLegitimateInterest`: ユーザーの正当な利益が透過的に伝達された目的 IDs のリスト。
+ `specialFeatureOptIns`: ユーザーがオプトインした特別な機能を表す整数のリスト。
+ `vendorConsent`: ユーザーが同意したベンダー IDs のリスト。
+ `vendorLegitimateInterest`: ユーザーの正当な利益が透過的に伝達されているベンダー IDs のリスト。
## 例
次の例では、エンコードされた同意文字列である 1 つの引数を取ります。ユーザーのプライバシー設定、同意の選択、その他のメタデータに関する情報など、デコードされた同意データを含むディクショナリを返します。
```
SELECT * FROM consent_gpp_v1_decode('ABCDEFGHIJK');
```
返される同意データの基本構造には、同意文字列のバージョン、CMP (Consent Management Platform) の詳細、さまざまな目的やベンダーに対するユーザーの同意と正当な利益の選択、およびその他のメタデータに関する情報が含まれます。
```
{
"version": 1,
"cmpId": 12,
"cmpVersion": 34,
"consentScreen": 5,
"consentLanguage": "en",
"vendorListVersion": 89,
"publisherCountryCode": "US",
"purposeConsent": [1],
"purposeLegitimateInterests": [1],
"specialFeatureOptins": [1],
"vendorConsent": [1],
"vendorLegitimateInterests": [1]}
}
```
# consent\$1tcf\$1v2\$1decode 関数
`consent_tcf_v2_decode` 関数は、Transparency and Framework Framework (TCF) v2 同意データをデコードするために使用されます。エンコードされた同意文字列を入力として受け取り、デコードされた同意データを返します。これには、ユーザーのプライバシー設定と同意の選択に関する情報が含まれます。この関数は、構造化された形式で同意データにアクセスして分析できるため、TCF v2 同意情報を含むデータを操作する場合に便利です。
## 構文
```
consent_tcf_v2_decode(tcf_string)
```
## 引数
*tcf\$1string*
エンコードされた TCF v2 同意文字列。
## 戻り値
この`consent_tcf_v2_decode`関数は、Transparency and Framework (TCF) v2 同意文字列からデコードされた同意データを含むディクショナリを返します。
返されるディクショナリには、次のキーと値のペアが含まれます。
**コアセグメント**
+ `version`: 使用されている TCF 仕様のバージョン (現在は 2)。
+ `created`: 同意文字列が作成された日時。
+ `lastUpdated`: 同意文字列が最後に更新された日時。
+ `cmpId`: 同意文字列をエンコードした同意管理プラットフォーム (CMP) の ID。
+ `cmpVersion`: 同意文字列をエンコードした CMP のバージョン。
+ `consentScreen`: ユーザーが同意した CMP UI の画面の ID。
+ `consentLanguage`: 同意情報の言語コード。
+ `vendorListVersion`: 使用されるベンダーリストのバージョン。
+ `tcfPolicyVersion`: 同意文字列が基づいている TCF ポリシーのバージョン。
+ `isServiceSpecific`: 同意が特定のサービスに固有であるか、すべてのサービスに適用されるかを示すブール値。
+ `useNonStandardStacks`: 非標準スタックを使用するかどうかを示すブール値。
+ `specialFeatureOptIns`: ユーザーがオプトインした特別な機能を表す整数のリスト。
+ `purposeConsent`: ユーザーが同意した目的を表す整数のリスト。
+ `purposesLITransparency`: ユーザーが正当な利益の透明性を付与した目的を表す整数のリスト。
+ `purposeOneTreatment`: ユーザーが「目的 1 つの処理」をリクエストしたかどうかを示すブール値 (つまり、すべての目的が均等に扱われます）。
+ `publisherCountryCode`: パブリッシャーの国コード。
+ `vendorConsent`: ユーザーが同意したベンダー IDs のリスト。
+ `vendorLegitimateInterest`: ユーザーの正当な利益が透過的に伝達されているベンダー IDs のリスト。
+ `pubRestrictionEntry`: パブリッシャーの制限のリスト。このフィールドには、目的 ID、制限タイプ、およびその目的制限に基づくベンダー IDs のリストが含まれます。
**孤立したベンダーセグメント**
+ `disclosedVendors`: ユーザーに公開されたベンダーを表す整数のリスト。
**パブリッシャー目的セグメント**
+ `pubPurposesConsent`: ユーザーが同意したパブリッシャー固有の目的を表す整数のリスト。
+ `pubPurposesLITransparency`: ユーザーが正当な利益の透明性を付与したパブリッシャー固有の目的を表す整数のリスト。
+ `customPurposesConsent`: ユーザーが同意したカスタム目的を表す整数のリスト。
+ `customPurposesLITransparency`: ユーザーが正当な利益の透明性を付与したカスタム目的を表す整数のリスト。
この詳細な同意データは、個人データを使用する際のユーザーのプライバシー設定を理解し、尊重するために使用できます。
## 例
次の例では、エンコードされた同意文字列である 1 つの引数を取ります。ユーザーのプライバシー設定、同意の選択、その他のメタデータに関する情報など、デコードされた同意データを含むディクショナリを返します。
```
from aws_clean_rooms.functions import consent_tcf_v2_decode
consent_string = "CO1234567890abcdef"
consent_data = consent_tcf_v2_decode(consent_string)
print(consent_data)
```
返される同意データの基本構造には、同意文字列のバージョン、CMP (Consent Management Platform) の詳細、さまざまな目的やベンダーに対するユーザーの同意と正当な利益の選択、およびその他のメタデータに関する情報が含まれます。
```
/** core segment **/
version: 2,
created: "2023-10-01T12:00:00Z",
lastUpdated: "2023-10-01T12:00:00Z",
cmpId: 1234,
cmpVersion: 5,
consentScreen: 1,
consentLanguage: "en",
vendorListVersion: 2,
tcfPolicyVersion: 2,
isServiceSpecific: false,
useNonStandardStacks: false,
specialFeatureOptIns: [1, 2, 3],
purposeConsent: [1, 2, 3],
purposesLITransparency: [1, 2, 3],
purposeOneTreatment: true,
publisherCountryCode: "US",
vendorConsent: [1, 2, 3],
vendorLegitimateInterest: [1, 2, 3],
pubRestrictionEntry: [
{ purpose: 1, restrictionType: 2, restrictionDescription: "Example restriction" },
],
/** disclosed vendor segment **/
disclosedVendors: [1, 2, 3],
/** publisher purposes segment **/
pubPurposesConsent: [1, 2, 3],
pubPurposesLITransparency: [1, 2, 3],
customPurposesConsent: [1, 2, 3],
customPurposesLITransparency: [1, 2, 3],
};
```
# ウィンドウ関数
ウィンドウ関数を使用すると、分析的なビジネスクエリをより効率的に作成できます。ウィンドウ関数はパーティションまたは結果セットの「ウィンドウ」で演算し、ウィンドウのすべての行に値を返します。それに対して、ウィンドウ以外の関数は、結果セットの行ごとに計算を実行します。結果の行を集計するグループ関数とは異なり、ウィンドウ関数はテーブル式のすべての行を保持します。
戻り値はこのウィンドウの行セットの値を使用して計算されます。ウィンドウはテーブルの各行に、追加の属性を計算するために使用する行のセットを定義します。ウィンドウはウィンドウ仕様 (OVER 句) を使用して定義され、次の 3 つの主要な概念に基づいています。
+ *ウィンドウのパーティション*、列のグループを形成 (PARTITION 句)
+ *ウィンドウの並び順*、各パーティション内の行の順序またはシーケンスの定義 (ORDER BY 句)
+ *ウィンドウのフレーム*、各行に関連して定義され、行のセットをさらに制限 (ROWS 仕様)
ウィンドウ関数は、最後の ORDER BY 句を除いて、クエリで実行される最後の演算のセットです。すべての結合およびすべての WHERE、GROUP BY、および HAVING 句は、ウィンドウ関数が処理される前に完了されます。そのため、ウィンドウ関数は選択リストまたは ORDER BY 句のみに表示できます。複数のウィンドウ関数は、別のフレーム句を持つ 1 つのクエリ内で使用できます。ウィンドウ関数は、CASE などの他のスカラー式でも使用できます。
## ウィンドウ関数の構文の概要
ウィンドウ関数は、次のような標準構文に従います。
```
function (expression) OVER (
[ PARTITION BY expr_list ]
[ ORDER BY order_list [ frame_clause ] ] )
```
ここで、*function* は、このセクションで説明している関数の 1 つです。
*expr\$1list* は次のとおりです。
```
expression | column_name [, expr_list ]
```
*order\$1list* は次のとおりです。
```
expression | column_name [ ASC | DESC ]
[ NULLS FIRST | NULLS LAST ]
[, order_list ]
```
*frame\$1clause* は次のとおりです。
```
ROWS
{ UNBOUNDED PRECEDING | unsigned_value PRECEDING | CURRENT ROW } |
{ BETWEEN
{ UNBOUNDED PRECEDING | unsigned_value { PRECEDING | FOLLOWING } | CURRENT ROW}
AND
{ UNBOUNDED FOLLOWING | unsigned_value { PRECEDING | FOLLOWING } | CURRENT ROW }}
```
### 引数
*function*
ウィンドウ関数。詳細については、個々の関数の説明を参照してください。
OVER
ウィンドウの仕様を定義する句。OVER 句はウィンドウ関数に必須であり、ウィンドウ関数を他の SQL 関数と区別します。
PARTITION BY *expr\$1list*
(オプション) PARTITION BY 句は結果セットをパーティションに再分割します。これは GROUP BY 句と似ています。パーティション句が存在する場合、関数は各パーティションの行に対して計算されます。パーティション句が指定されていない場合、1 つのパーティションにテーブル全体が含まれ、関数は完全なテーブルに対して計算されます。
ランク付け関数 DENSE\$1RANK、NTILE、RANK、および ROW\$1NUMBER では、結果セットのすべての行でグローバルな比較が必要です。PARTITION BY clauseを使用すると、クエリオプティマイザーは、パーティションに応じて複数のスライスにワークロードを分散させることにより、個々の集計を並列で実行できます。PARTITION BY 句がない場合、集計ステップを 1 つのスライスで順次実行する必要があり、特に大規模なクラスターではパフォーマンスに大きな悪影響を与えることがあります。
AWS Clean Roomsは、PARTITION BY 句の文字列リテラルをサポートしていません。
ORDER BY *order\$1list*
(オプション) ウィンドウ関数は、ORDER BY で順序仕様に従ってソートされた各パーティション内の行に適用されます。この ORDER BY 句は、*frame\$1clause* の ORDER BY 句とは異なり、両者はまったく無関係です。ORDER BY 句は、PARTITION BY 句なしで使用できます。
ランク付け関数の場合、ORDER BY 句はランク付けの値に使用する基準を特定します。集計関数の場合、パーティションで分割された行は、集計関数がフレームごとに計算される前に順序付けされる必要があります。ウィンドウ関数の種類の詳細については、「[ウィンドウ関数](#Window_functions)」を参照してください。
列識別子または列識別を検証する式は、順序リストで必要とされます。定数も定数式も、列名の代用として使用することはできません。
NULL 値は独自のグループとして扱われ、NULLS FIRST または NULLS LAST オプションに従ってソートおよびランク付けされます。デフォルトでは、NULL 値は昇順ではソートされて最後にランク付けされ、降順ではソートされて最初にランク付けされます。
AWS Clean Roomsは、ORDER BY 句の文字列リテラルをサポートしていません。
ORDER BY 句を省略した場合、行の順序は不確定になります。
ORDER BY 句がデータの一意の合計順序を生成しない場合などAWS Clean Rooms、並列システムでは、行の順序は不確定です。つまり、ORDER BY 式が重複した値を生成する場合 (部分的な順序付け）、それらの行の戻り順序は の実行ごとに異なる場合がありますAWS Clean Rooms。そのため、ウィンドウ関数は予期しない結果または矛盾した結果を返す場合があります。詳細については、「[ウィンドウ関数用データの一意の並び順](#Examples_order_by_WF)」を参照してください。
*column\$1name*
パーティション化または順序付けされる列の名前。
ASC \$1 DESC
次のように、式のソート順を定義するオプション:
+ ASC: 昇順 (数値の場合は低から高、文字列の場合は「A」から「Z」など) オプションを指定しない場合、データはデフォルトでは昇順にソートされます。
+ DESC: 降順 (数値の場合は高から低、文字列の場合は「Z」から「A」)。
NULLS FIRST \$1 NULLS LAST
NULL を NULL 以外の値より先に順序付けするか、NULL 以外の値の後に順序付けするかを指定するオプション。デフォルトでは、NULL は昇順ではソートされて最後にランク付けされ、降順ではソートされて最初にランク付けされます。
*frame\$1clause*
集計関数では、ORDER BY を使用する場合、フレーム句は関数のウィンドウで行のセットをさらに絞り込みます。これは、順序付けされた結果内の行のセットを含めるか、または除外できるようにします。フレーム句は ROWS キーワードおよび関連する指定子で構成されます。
frame 句は、ランク付け関数には適用されません。また、集計関数の OVER 句の中に ORDER BY 句がない場合は、フレーム句は必要ありません。ORDER BY 句が集計関数に使用される場合、明示的なフレーム句が必要です。
ORDER BY 句が指定されていない場合、暗黙的なフレームはバインドされません (ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING と同じ)。
ROWS
この句は、現在の行からの物理オフセットを指定してウィンドウフレームを定義します。
この句は、現在のウィンドウの行、または現在の行の値を組み合わせるパーティションを指定します。また、現在の行の前後に配置される行の位置を指定する引数を使用します。すべてのウィンドウフレームの参照点は現在の行です。ウィンドウフレームがパーティションで次にスライドすると、各行は順に現在の行になります。
フレームは、次のように現在の行までと現在の行を含む行の簡易セットである場合があります。
```
{UNBOUNDED PRECEDING | offset PRECEDING | CURRENT ROW}
```
また、次の 2 つの境界の間の行のセットである場合があります。
```
BETWEEN
{ UNBOUNDED PRECEDING | offset { PRECEDING | FOLLOWING } | CURRENT ROW }
AND
{ UNBOUNDED FOLLOWING | offset { PRECEDING | FOLLOWING } | CURRENT ROW }
```
UNBOUNDED PRECEDING はウィンドウがパーティションの最初の行で開始することを示し、*offset* PRECEDING はウィンドウが現在の行の前のオフセット値と等しい行数で開始することを示します。デフォルトは UNBOUNDED PRECEDING です。
CURRENT ROW は、ウィンドウが現在の行で開始または終了することを示します。
UNBOUNDED FOLLOWING はウィンドウがパーティションの最後の行で終了することを示し、*offset* FOLLOWING はウィンドウが現在の行の後のオフセット値と等しい行数で終了することを示します。
*offset* は、現在の行の前後にある物理的な行数を識別します。この場合、*offset* は、正の数値に評価される定数である必要があります。例えば、5 FOLLOWING は現在の行より 5 行後のフレームを終了します。
BETWEEN が指定されていない場合、フレームは現在の行により暗黙的に区切られます。例えば、`ROWS 5 PRECEDING` は `ROWS BETWEEN 5 PRECEDING AND CURRENT ROW` と同じです。また、`ROWS UNBOUNDED FOLLOWING`は `ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING` と同じです。
開始境界が終了境界よりも大きいフレームを指定することはできません。例えば、以下のフレームはいずれも指定することができません。
```
between 5 following and 5 preceding
between current row and 2 preceding
between 3 following and current row
```
## ウィンドウ関数用データの一意の並び順
ウィンドウ関数の ORDER BY 句がデータの一意および全体の並び順を生成しない場合、行の順序は不確定になります。ORDER BY 式が重複した値 (部分的な順序付け) を生成する場合、これらの行の戻り値の順序は実行時によって異なる可能性があります。この場合、ウィンドウ関数は予期しない結果または矛盾した結果を返す場合があります。
例えば、次のクエリは、複数の実行にわたって異なる結果を返します。これらの異なる結果は、`order by dateid` が SUM Window 関数でデータの一意の順序を生成しないために発生します。
```
select dateid, pricepaid,
sum(pricepaid) over(order by dateid rows unbounded preceding) as sumpaid
from sales
group by dateid, pricepaid;
dateid | pricepaid | sumpaid
--------+-----------+-------------
1827 | 1730.00 | 1730.00
1827 | 708.00 | 2438.00
1827 | 234.00 | 2672.00
...
select dateid, pricepaid,
sum(pricepaid) over(order by dateid rows unbounded preceding) as sumpaid
from sales
group by dateid, pricepaid;
dateid | pricepaid | sumpaid
--------+-----------+-------------
1827 | 234.00 | 234.00
1827 | 472.00 | 706.00
1827 | 347.00 | 1053.00
...
```
この場合、2 番目の ORDER BY 列をウィンドウ関数に追加すると問題を解決できます。
```
select dateid, pricepaid,
sum(pricepaid) over(order by dateid, pricepaid rows unbounded preceding) as sumpaid
from sales
group by dateid, pricepaid;
dateid | pricepaid | sumpaid
--------+-----------+---------
1827 | 234.00 | 234.00
1827 | 337.00 | 571.00
1827 | 347.00 | 918.00
...
```
## サポートされている関数
AWS Clean RoomsSpark SQL は、集計とランキングの 2 種類のウィンドウ関数をサポートしています。
サポートされる集約関数は次のとおりです。
+ [CUME\$1DIST ウィンドウ関数](WF_CUME_DIST.md)
+ [DENSE\$1RANK ウィンドウ関数](WF_DENSE_RANK.md)
+ [最初のウィンドウ関数](WF_FIRST.md)
+ [FIRST\$1VALUE ウィンドウ関数](WF_first_value.md)
+ [LAG ウィンドウ関数](WF_LAG.md)
+ [LAST ウィンドウ関数](WF-LAST.md)
+ [LAST\$1VALUE ウィンドウ関数](WF_last_value.md)
+ [LEAD ウィンドウ関数](WF_LEAD.md)
サポートされる集計関数は次のとおりです。
+ [DENSE\$1RANK ウィンドウ関数](WF_DENSE_RANK.md)
+ [PERCENT\$1RANK ウィンドウ関数](WF_PERCENT_RANK.md)
+ [RANK ウィンドウ関数](WF_RANK.md)
+ [ROW\$1NUMBER ウィンドウ関数](WF_ROW_NUMBER.md)
## ウィンドウ関数例のサンプルテーブル
ウィンドウ関数別の例をそれぞれの説明と共に参照できます。一部の例で使用している WINSALES という名前のテーブルには、以下のテーブルのように 11 行が含まれています。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/clean-rooms/latest/sql-reference/Window_functions.html)
# CUME\$1DIST ウィンドウ関数
ウィンドウまたはパーティション内の値の累積分布を計算します。昇順の場合、累積分布は以下の式を使用して特定されます。
`count of rows with values <= x / count of rows in the window or partition`
ここで、*x* は ORDER BY 句で指定された列の現在の行の値と等しくなります。以下のデータセットは、この式の使用方法を示しています。
```
Row# Value Calculation CUME_DIST
1 2500 (1)/(5) 0.2
2 2600 (2)/(5) 0.4
3 2800 (3)/(5) 0.6
4 2900 (4)/(5) 0.8
5 3100 (5)/(5) 1.0
```
戻り値の範囲は、0～1 (0 は含みませんが 1 は含みます) です。
## 構文
```
CUME_DIST ()
OVER (
[ PARTITION BY partition_expression ]
[ ORDER BY order_list ]
)
```
## 引数
OVER
ウィンドウのパーティションを指定する句。OVER 句にウィンドウフレーム仕様を含めることはできません。
PARTITION BY *partition\$1expression*
省略可能。OVER 句の各グループのレコードの範囲を設定する式。
ORDER BY *order\$1list*
累積分布を計算する式。式は、数値データ型を含んでいるか、そのデータ型に暗黙的に変換できる必要があります。ORDER BY を省略した場合、すべての行について戻り値は 1 です。
ORDER BY で一意の並べ替えが行われない場合、行の順序は不確定になります。詳細については、「[ウィンドウ関数用データの一意の並び順](Window_functions.md#Examples_order_by_WF)」を参照してください。
## 戻り型
FLOAT8
## 例
次の例は、各販売者の数量の累積配布を計算します。
```
select sellerid, qty, cume_dist()
over (partition by sellerid order by qty)
from winsales;
sellerid qty cume_dist
--------------------------------------------------
1 10.00 0.33
1 10.64 0.67
1 30.37 1
3 10.04 0.25
3 15.15 0.5
3 20.75 0.75
3 30.55 1
2 20.09 0.5
2 20.12 1
4 10.12 0.5
4 40.23 1
```
WINSALES テーブルの説明については、「[ウィンドウ関数例のサンプルテーブル](Window_functions.md#Window_function_example)」を参照してください。
# DENSE\$1RANK ウィンドウ関数
DENSE\$1RANK ウィンドウ関数は、OVER 句の ORDER BY 式に基づいて、値のグループの値のランクを特定します。オプションの PARTITION BY 句がある場合、ランク付けは行のグループごとにリセットされます。ランク付け条件が同じ値の行は、同じランクを受け取ります。DENSE\$1RANK 関数はある点において RANK とは異なります。2 行以上で同点となった場合、ランク付けされた値の順位に差はありません。例えば、2 行が 1 位にランク付けされると、次のランクは 2 位になります。
同じクエリに PARTITION BY および ORDER BY 句のあるランク付け関数を使用することができます。
## 構文
```
DENSE_RANK () OVER
(
[ PARTITION BY expr_list ]
[ ORDER BY order_list ]
)
```
## 引数
( )
この関数は引数を受け取りませんが、空のかっこは必要です。
OVER
DENSE\$1RANK 関数のウィンドウ句。
PARTITION BY *expr\$1list*
省略可能。ウィンドウを定義する 1 つ以上の式。
ORDER BY *order\$1list*
省略可能。ランク付けの値が基とする式。PARTITION BY が指定されていない場合、ORDER BY はテーブル全体を使用します。ORDER BY を省略した場合、すべての行について戻り値は 1 です。
ORDER BY で一意の並べ替えが行われない場合、行の順序は不確定になります。詳細については、「[ウィンドウ関数用データの一意の並び順](Window_functions.md#Examples_order_by_WF)」を参照してください。
## 戻り型
INTEGER
## 例
次の例では、販売数量によってテーブルを順序付けして (降順)、各行にデンス値のランクと標準のランクの両方を割り当てます。結果はウィンドウ関数の結果が提供された後にソートされます。
```
select salesid, qty,
dense_rank() over(order by qty desc) as d_rnk,
rank() over(order by qty desc) as rnk
from winsales
order by 2,1;
salesid | qty | d_rnk | rnk
---------+-----+-------+-----
10001 | 10 | 5 | 8
10006 | 10 | 5 | 8
30001 | 10 | 5 | 8
40005 | 10 | 5 | 8
30003 | 15 | 4 | 7
20001 | 20 | 3 | 4
20002 | 20 | 3 | 4
30004 | 20 | 3 | 4
10005 | 30 | 2 | 2
30007 | 30 | 2 | 2
40001 | 40 | 1 | 1
(11 rows)
```
DENSE\$1RANK および RANK 関数が同じクエリで並べて使用される場合、同じ行のセットに割り当てるランク付けの違いに注意してください。WINSALES テーブルの説明については、「[ウィンドウ関数例のサンプルテーブル](Window_functions.md#Window_function_example)」を参照してください。
次の例では、SELLERID によってテーブルをパーティション分割し、数量によって各パーティションを順序付けして (降順)、行ごとにデンス値のランクを割り当てます。結果はウィンドウ関数の結果が提供された後にソートされます。
```
select salesid, sellerid, qty,
dense_rank() over(partition by sellerid order by qty desc) as d_rnk
from winsales
order by 2,3,1;
salesid | sellerid | qty | d_rnk
---------+----------+-----+-------
10001 | 1 | 10 | 2
10006 | 1 | 10 | 2
10005 | 1 | 30 | 1
20001 | 2 | 20 | 1
20002 | 2 | 20 | 1
30001 | 3 | 10 | 4
30003 | 3 | 15 | 3
30004 | 3 | 20 | 2
30007 | 3 | 30 | 1
40005 | 4 | 10 | 2
40001 | 4 | 40 | 1
(11 rows)
```
WINSALES テーブルの説明については、「[ウィンドウ関数例のサンプルテーブル](Window_functions.md#Window_function_example)」を参照してください。
# 最初のウィンドウ関数
順序付けられた行のセットがある場合、FIRST はウィンドウフレームの最初の行に関して指定された式の値を返します。
フレームの最後の行を選択する方法については、「[LAST ウィンドウ関数](WF-LAST.md)」を参照してください。
## 構文
```
FIRST( expression )[ IGNORE NULLS | RESPECT NULLS ]
OVER (
[ PARTITION BY expr_list ]
[ ORDER BY order_list frame_clause ]
)
```
## 引数
*expression*
関数の対象となる列または式。
IGNORE NULLS
このオプションを FIRST で使用すると、関数は NULL (すべての値が NULL の場合は NULL) ではないフレームの最初の値を返します。
RESPECT NULLS
が使用する行の決定に null 値を含めるAWS Clean Rooms必要があることを示します。IGNORE NULLS を指定しない場合、RESPECT NULLS はデフォルトでサポートされます。
OVER
関数にウィンドウ句を導入します。
PARTITION BY *expr\$1list*
1 つ以上の式で関数のウィンドウを定義します。
ORDER BY *order\$1list*
各パーティション内の行をソートします。PARTITION BY 句が指定されていない場合、ORDER BY はテーブル全体をソートします。ORDER BY 句を指定する場合、*frame\$1clause* も指定する必要があります。
FIRST 関数の結果は、データの順序によって異なります。以下の場合、結果は不確定になります。
+ ORDER BY 句が指定されておらず、パーティションに式に使用する 2 つの異なる値が含まれる場合
+ 式が ORDER BY リストの同じ値に対応する異なる値を検証する場合。
*frame\$1clause*
ORDER BY 句が集計関数に使用される場合、明示的なフレーム句が必要です。フレーム句は順序付けた結果の行のセットを含めるか除外して、関数のウィンドウの行のセットを絞り込みます。フレーム句は ROWS キーワードおよび関連する指定子で構成されます。「[ウィンドウ関数の構文の概要](Window_functions.md#Window_function_synopsis)」を参照してください。
## 戻り型
これらの関数は、プリミティブAWS Clean Roomsデータ型を使用する式をサポートします。戻り値の型は*式*のデータ型と同じです。
## 例
次の例は、収容能力によって順序付けられた結果 (高から低) で、VENUE テーブルの各会場の座席数を返します。FIRST 関数は、フレームの最初の行に対応する会場の名前を選択するために使用されます。この場合は、座席数が最も多い行です。結果は州によってパーティションで分割されるため、VENUESTATE 値が変更されると、新しい最初の値が選択されます。ウィンドウフレームはバインドされていないため、同じ最初の値が各パーティションの行ごとに選択されます。
カリフォルニアでは、`Qualcomm Stadium`が最高座席数 (`70561`) であるため、この名前は `CA` パーティションのすべての行に対する最初の値です。
```
select venuestate, venueseats, venuename,
first(venuename)
over(partition by venuestate
order by venueseats desc
rows between unbounded preceding and unbounded following)
from (select * from venue where venueseats >0)
order by venuestate;
venuestate | venueseats | venuename | first
-----------+------------+--------------------------------+------------------------------
CA | 70561 | Qualcomm Stadium | Qualcomm Stadium
CA | 69843 | Monster Park | Qualcomm Stadium
CA | 63026 | McAfee Coliseum | Qualcomm Stadium
CA | 56000 | Dodger Stadium | Qualcomm Stadium
CA | 45050 | Angel Stadium of Anaheim | Qualcomm Stadium
CA | 42445 | PETCO Park | Qualcomm Stadium
CA | 41503 | AT&T Park | Qualcomm Stadium
CA | 22000 | Shoreline Amphitheatre | Qualcomm Stadium
CO | 76125 | INVESCO Field | INVESCO Field
CO | 50445 | Coors Field | INVESCO Field
DC | 41888 | Nationals Park | Nationals Park
FL | 74916 | Dolphin Stadium | Dolphin Stadium
FL | 73800 | Jacksonville Municipal Stadium | Dolphin Stadium
FL | 65647 | Raymond James Stadium | Dolphin Stadium
FL | 36048 | Tropicana Field | Dolphin Stadium
...
```
# FIRST\$1VALUE ウィンドウ関数
順序付けられた行のセットとすると、FIRST\$1VALUE はウィンドウフレームの最初の行に関して指定された式の値を返します。
フレームの最後の行を選択する方法については、「[LAST\$1VALUE ウィンドウ関数](WF_last_value.md)」を参照してください。
## 構文
```
FIRST_VALUE( expression )[ IGNORE NULLS | RESPECT NULLS ]
OVER (
[ PARTITION BY expr_list ]
[ ORDER BY order_list frame_clause ]
)
```
## 引数
*expression*
関数の対象となる列または式。
IGNORE NULLS
このオプションが FIRST\$1VALUE で使用される場合、関数は NULL ではないフレームの最初の値 (値がすべて NULL の場合は NULL) を返します。
RESPECT NULLS
が使用する行の決定に null 値を含めるAWS Clean Rooms必要があることを示します。IGNORE NULLS を指定しない場合、RESPECT NULLS はデフォルトでサポートされます。
OVER
関数にウィンドウ句を導入します。
PARTITION BY *expr\$1list*
1 つ以上の式で関数のウィンドウを定義します。
ORDER BY *order\$1list*
各パーティション内の行をソートします。PARTITION BY 句が指定されていない場合、ORDER BY はテーブル全体をソートします。ORDER BY 句を指定する場合、*frame\$1clause* も指定する必要があります。
FIRST\$1VALUE 関数の結果は、データの並び順によって異なります。以下の場合、結果は不確定になります。
+ ORDER BY 句が指定されておらず、パーティションに式に使用する 2 つの異なる値が含まれる場合
+ 式が ORDER BY リストの同じ値に対応する異なる値を検証する場合。
*frame\$1clause*
ORDER BY 句が集計関数に使用される場合、明示的なフレーム句が必要です。フレーム句は順序付けた結果の行のセットを含めるか除外して、関数のウィンドウの行のセットを絞り込みます。フレーム句は ROWS キーワードおよび関連する指定子で構成されます。「[ウィンドウ関数の構文の概要](Window_functions.md#Window_function_synopsis)」を参照してください。
## 戻り型
これらの関数は、プリミティブAWS Clean Roomsデータ型を使用する式をサポートします。戻り値の型は*式*のデータ型と同じです。
## 例
次の例は、収容能力によって順序付けられた結果 (高から低) で、VENUE テーブルの各会場の座席数を返します。FIRST\$1VALUE 関数は、フレームの最初の行 (この場合、最高座席数の行) に対応する会場名を選択するために使用されます。結果は州によってパーティションで分割されるため、VENUESTATE 値が変更されると、新しい最初の値が選択されます。ウィンドウフレームはバインドされていないため、同じ最初の値が各パーティションの行ごとに選択されます。
カリフォルニアでは、`Qualcomm Stadium`が最高座席数 (`70561`) であるため、この名前は `CA` パーティションのすべての行に対する最初の値です。
```
select venuestate, venueseats, venuename,
first_value(venuename)
over(partition by venuestate
order by venueseats desc
rows between unbounded preceding and unbounded following)
from (select * from venue where venueseats >0)
order by venuestate;
venuestate | venueseats | venuename | first_value
-----------+------------+--------------------------------+------------------------------
CA | 70561 | Qualcomm Stadium | Qualcomm Stadium
CA | 69843 | Monster Park | Qualcomm Stadium
CA | 63026 | McAfee Coliseum | Qualcomm Stadium
CA | 56000 | Dodger Stadium | Qualcomm Stadium
CA | 45050 | Angel Stadium of Anaheim | Qualcomm Stadium
CA | 42445 | PETCO Park | Qualcomm Stadium
CA | 41503 | AT&T Park | Qualcomm Stadium
CA | 22000 | Shoreline Amphitheatre | Qualcomm Stadium
CO | 76125 | INVESCO Field | INVESCO Field
CO | 50445 | Coors Field | INVESCO Field
DC | 41888 | Nationals Park | Nationals Park
FL | 74916 | Dolphin Stadium | Dolphin Stadium
FL | 73800 | Jacksonville Municipal Stadium | Dolphin Stadium
FL | 65647 | Raymond James Stadium | Dolphin Stadium
FL | 36048 | Tropicana Field | Dolphin Stadium
...
```
# LAG ウィンドウ関数
LAG ウィンドウ関数は、パーティションの現在の行より上 (前) の指定されたオフセットの行の値を返します。
## 構文
```
LAG (value_expr [, offset ])
[ IGNORE NULLS | RESPECT NULLS ]
OVER ( [ PARTITION BY window_partition ] ORDER BY window_ordering )
```
## 引数
*value\$1expr*
関数の対象となる列または式。
*offset*
値を返す現在の行より前の行数を指定するオプションのパラメータ。オフセットは整数の定数、または整数を検証する式にすることができます。オフセットを指定しない場合、 AWS Clean Roomsをデフォルト値`1`として使用します。`0` のオフセットは現在の行を示します。
IGNORE NULLS
が使用する行を決定する際に null 値をAWS Clean Roomsスキップする必要があることを示すオプションの仕様。IGNORE NULLS がリストされていない場合、Null 値が含まれます。
NVL または COALESCE 式を使用し、Null 値を別の値で置換できます。
RESPECT NULLS
が使用する行の決定に null 値を含めるAWS Clean Rooms必要があることを示します。IGNORE NULLS を指定しない場合、RESPECT NULLS はデフォルトでサポートされます。
OVER
ウィンドウのパーティションおよび並び順を指定します。OVER 句にウィンドウフレーム仕様を含めることはできません。
PARTITION BY *window\$1partition*
OVER 句の各グループのレコードの範囲を設定するオプションの引数。
ORDER BY *window\$1ordering*
各パーティション内の行をソートします。
LAG ウィンドウ関数は、任意のAWS Clean Roomsデータ型を使用する式をサポートします。戻り値の型は *value\$1expr* の型と同じです。
## 例
次の例は、購入者 ID 3 の購入者に販売されたチケット数と購入者 3 がチケットを購入した時刻を示します。購入者 3 の以前の販売と各販売を比較するには、クエリは販売ごとに以前の販売数を返します。2008 年 1 月 16 日より前に購入されていないため、最初の以前の販売数は Null です。
```
select buyerid, saletime, qtysold,
lag(qtysold,1) over (order by buyerid, saletime) as prev_qtysold
from sales where buyerid = 3 order by buyerid, saletime;
buyerid | saletime | qtysold | prev_qtysold
---------+---------------------+---------+--------------
3 | 2008-01-16 01:06:09 | 1 |
3 | 2008-01-28 02:10:01 | 1 | 1
3 | 2008-03-12 10:39:53 | 1 | 1
3 | 2008-03-13 02:56:07 | 1 | 1
3 | 2008-03-29 08:21:39 | 2 | 1
3 | 2008-04-27 02:39:01 | 1 | 2
3 | 2008-08-16 07:04:37 | 2 | 1
3 | 2008-08-22 11:45:26 | 2 | 2
3 | 2008-09-12 09:11:25 | 1 | 2
3 | 2008-10-01 06:22:37 | 1 | 1
3 | 2008-10-20 01:55:51 | 2 | 1
3 | 2008-10-28 01:30:40 | 1 | 2
(12 rows)
```
# LAST ウィンドウ関数
順序付けられた行のセットがある場合、LAST 関数はフレーム内の最後の行に関する式の値を返します。
フレームの最初の行を選択する方法については、「[最初のウィンドウ関数](WF_FIRST.md)」を参照してください。
## 構文
```
LAST( expression )[ IGNORE NULLS | RESPECT NULLS ]
OVER (
[ PARTITION BY expr_list ]
[ ORDER BY order_list frame_clause ]
)
```
## 引数
*expression*
関数の対象となる列または式。
IGNORE NULLS
この関数は NULL ではないフレームの最後の値 (値がすべて NULL の場合は NULL) を返します。
RESPECT NULLS
が使用する行の決定に null 値を含めるAWS Clean Rooms必要があることを示します。IGNORE NULLS を指定しない場合、RESPECT NULLS はデフォルトでサポートされます。
OVER
関数にウィンドウ句を導入します。
PARTITION BY *expr\$1list*
1 つ以上の式で関数のウィンドウを定義します。
ORDER BY *order\$1list*
各パーティション内の行をソートします。PARTITION BY 句が指定されていない場合、ORDER BY はテーブル全体をソートします。ORDER BY 句を指定する場合、*frame\$1clause* も指定する必要があります。
結果は、データの並び順によって異なります。以下の場合、結果は不確定になります。
+ ORDER BY 句が指定されておらず、パーティションに式に使用する 2 つの異なる値が含まれる場合
+ 式が ORDER BY リストの同じ値に対応する異なる値を検証する場合。
*frame\$1clause*
ORDER BY 句が集計関数に使用される場合、明示的なフレーム句が必要です。フレーム句は順序付けた結果の行のセットを含めるか除外して、関数のウィンドウの行のセットを絞り込みます。フレーム句は ROWS キーワードおよび関連する指定子で構成されます。「[ウィンドウ関数の構文の概要](Window_functions.md#Window_function_synopsis)」を参照してください。
## 戻り型
これらの関数は、プリミティブAWS Clean Roomsデータ型を使用する式をサポートします。戻り値の型は*式*のデータ型と同じです。
## 例
次の例は、収容能力によって順序付けられた結果 (高から低) で、VENUE テーブルの各会場の座席数を返します。LAST 関数は、フレームの最後の行に対応する会場の名前を選択するために使用されます。この場合は、座席数が最も少ない行です。結果は州によってパーティションで分割されるため、VENUESTATE 値が変更されると、新しい最後の値が選択されます。ウィンドウフレームはバインドされていないため、同じ最後の値が各パーティションの行ごとに選択されます。
カリフォルニアでは、`Shoreline Amphitheatre`の座席数が一番低い (`22000`) ため、この値がパーティションのすべての行に返されます。
```
select venuestate, venueseats, venuename,
last(venuename)
over(partition by venuestate
order by venueseats desc
rows between unbounded preceding and unbounded following)
from (select * from venue where venueseats >0)
order by venuestate;
venuestate | venueseats | venuename | last
-----------+------------+--------------------------------+------------------------------
CA | 70561 | Qualcomm Stadium | Shoreline Amphitheatre
CA | 69843 | Monster Park | Shoreline Amphitheatre
CA | 63026 | McAfee Coliseum | Shoreline Amphitheatre
CA | 56000 | Dodger Stadium | Shoreline Amphitheatre
CA | 45050 | Angel Stadium of Anaheim | Shoreline Amphitheatre
CA | 42445 | PETCO Park | Shoreline Amphitheatre
CA | 41503 | AT&T Park | Shoreline Amphitheatre
CA | 22000 | Shoreline Amphitheatre | Shoreline Amphitheatre
CO | 76125 | INVESCO Field | Coors Field
CO | 50445 | Coors Field | Coors Field
DC | 41888 | Nationals Park | Nationals Park
FL | 74916 | Dolphin Stadium | Tropicana Field
FL | 73800 | Jacksonville Municipal Stadium | Tropicana Field
FL | 65647 | Raymond James Stadium | Tropicana Field
FL | 36048 | Tropicana Field | Tropicana Field
...
```
# LAST\$1VALUE ウィンドウ関数
順序付けられた行のセットを考慮し、LAST\$1VALUE 関数は、フレームの最後の行に関する式の値を返します。
フレームの最初の行を選択する方法については、「[FIRST\$1VALUE ウィンドウ関数](WF_first_value.md)」を参照してください。
## 構文
```
LAST_VALUE( expression )[ IGNORE NULLS | RESPECT NULLS ]
OVER (
[ PARTITION BY expr_list ]
[ ORDER BY order_list frame_clause ]
)
```
## 引数
*expression*
関数の対象となる列または式。
IGNORE NULLS
この関数は NULL ではないフレームの最後の値 (値がすべて NULL の場合は NULL) を返します。
RESPECT NULLS
が使用する行の決定に null 値を含めるAWS Clean Rooms必要があることを示します。IGNORE NULLS を指定しない場合、RESPECT NULLS はデフォルトでサポートされます。
OVER
関数にウィンドウ句を導入します。
PARTITION BY *expr\$1list*
1 つ以上の式で関数のウィンドウを定義します。
ORDER BY *order\$1list*
各パーティション内の行をソートします。PARTITION BY 句が指定されていない場合、ORDER BY はテーブル全体をソートします。ORDER BY 句を指定する場合、*frame\$1clause* も指定する必要があります。
結果は、データの並び順によって異なります。以下の場合、結果は不確定になります。
+ ORDER BY 句が指定されておらず、パーティションに式に使用する 2 つの異なる値が含まれる場合
+ 式が ORDER BY リストの同じ値に対応する異なる値を検証する場合。
*frame\$1clause*
ORDER BY 句が集計関数に使用される場合、明示的なフレーム句が必要です。フレーム句は順序付けた結果の行のセットを含めるか除外して、関数のウィンドウの行のセットを絞り込みます。フレーム句は ROWS キーワードおよび関連する指定子で構成されます。「[ウィンドウ関数の構文の概要](Window_functions.md#Window_function_synopsis)」を参照してください。
## 戻り型
これらの関数は、プリミティブAWS Clean Roomsデータ型を使用する式をサポートします。戻り値の型は*式*のデータ型と同じです。
## 例
次の例は、収容能力によって順序付けられた結果 (高から低) で、VENUE テーブルの各会場の座席数を返します。LAST\$1VALUE 関数は、フレームの最後の行 (この場合、最小座席数の行) に対応する会場名を選択するために使用されます。結果は州によってパーティションで分割されるため、VENUESTATE 値が変更されると、新しい最後の値が選択されます。ウィンドウフレームはバインドされていないため、同じ最後の値が各パーティションの行ごとに選択されます。
カリフォルニアでは、`Shoreline Amphitheatre`の座席数が一番低い (`22000`) ため、この値がパーティションのすべての行に返されます。
```
select venuestate, venueseats, venuename,
last_value(venuename)
over(partition by venuestate
order by venueseats desc
rows between unbounded preceding and unbounded following)
from (select * from venue where venueseats >0)
order by venuestate;
venuestate | venueseats | venuename | last_value
-----------+------------+--------------------------------+------------------------------
CA | 70561 | Qualcomm Stadium | Shoreline Amphitheatre
CA | 69843 | Monster Park | Shoreline Amphitheatre
CA | 63026 | McAfee Coliseum | Shoreline Amphitheatre
CA | 56000 | Dodger Stadium | Shoreline Amphitheatre
CA | 45050 | Angel Stadium of Anaheim | Shoreline Amphitheatre
CA | 42445 | PETCO Park | Shoreline Amphitheatre
CA | 41503 | AT&T Park | Shoreline Amphitheatre
CA | 22000 | Shoreline Amphitheatre | Shoreline Amphitheatre
CO | 76125 | INVESCO Field | Coors Field
CO | 50445 | Coors Field | Coors Field
DC | 41888 | Nationals Park | Nationals Park
FL | 74916 | Dolphin Stadium | Tropicana Field
FL | 73800 | Jacksonville Municipal Stadium | Tropicana Field
FL | 65647 | Raymond James Stadium | Tropicana Field
FL | 36048 | Tropicana Field | Tropicana Field
...
```
# LEAD ウィンドウ関数
LEAD ウィンドウ関数は、パーティションの現在の行より下 (後) の指定されたオフセットの行の値を返します。
## 構文
```
LEAD (value_expr [, offset ])
[ IGNORE NULLS | RESPECT NULLS ]
OVER ( [ PARTITION BY window_partition ] ORDER BY window_ordering )
```
## 引数
*value\$1expr*
関数の対象となる列または式。
*offset*
値を返す現在の行より下の行数を指定するオプションのパラメータ。オフセットは整数の定数、または整数を検証する式にすることができます。オフセットを指定しない場合、 AWS Clean Roomsをデフォルト値`1`として使用します。`0` のオフセットは現在の行を示します。
IGNORE NULLS
が使用する行を決定する際に null 値をAWS Clean Roomsスキップする必要があることを示すオプションの仕様。IGNORE NULLS がリストされていない場合、Null 値が含まれます。
NVL または COALESCE 式を使用し、Null 値を別の値で置換できます。
RESPECT NULLS
が使用する行の決定に null 値を含めるAWS Clean Rooms必要があることを示します。IGNORE NULLS を指定しない場合、RESPECT NULLS はデフォルトでサポートされます。
OVER
ウィンドウのパーティションおよび並び順を指定します。OVER 句にウィンドウフレーム仕様を含めることはできません。
PARTITION BY *window\$1partition*
OVER 句の各グループのレコードの範囲を設定するオプションの引数。
ORDER BY *window\$1ordering*
各パーティション内の行をソートします。
LEAD ウィンドウ関数は、任意のAWS Clean Roomsデータ型を使用する式をサポートしています。戻り値の型は *value\$1expr* の型と同じです。
## 例
次の例は、チケットが 2008 年 1 月 1 日および 2008 年 1 月 2 日に販売された SALES テーブルのイベントの手数料、および次の販売のチケット販売に支払った手数料を示します。
```
select eventid, commission, saletime,
lead(commission, 1) over (order by saletime) as next_comm
from sales where saletime between '2008-01-01 00:00:00' and '2008-01-02 12:59:59'
order by saletime;
eventid | commission | saletime | next_comm
---------+------------+---------------------+-----------
6213 | 52.05 | 2008-01-01 01:00:19 | 106.20
7003 | 106.20 | 2008-01-01 02:30:52 | 103.20
8762 | 103.20 | 2008-01-01 03:50:02 | 70.80
1150 | 70.80 | 2008-01-01 06:06:57 | 50.55
1749 | 50.55 | 2008-01-01 07:05:02 | 125.40
8649 | 125.40 | 2008-01-01 07:26:20 | 35.10
2903 | 35.10 | 2008-01-01 09:41:06 | 259.50
6605 | 259.50 | 2008-01-01 12:50:55 | 628.80
6870 | 628.80 | 2008-01-01 12:59:34 | 74.10
6977 | 74.10 | 2008-01-02 01:11:16 | 13.50
4650 | 13.50 | 2008-01-02 01:40:59 | 26.55
4515 | 26.55 | 2008-01-02 01:52:35 | 22.80
5465 | 22.80 | 2008-01-02 02:28:01 | 45.60
5465 | 45.60 | 2008-01-02 02:28:02 | 53.10
7003 | 53.10 | 2008-01-02 02:31:12 | 70.35
4124 | 70.35 | 2008-01-02 03:12:50 | 36.15
1673 | 36.15 | 2008-01-02 03:15:00 | 1300.80
...
(39 rows)
```
# PERCENT\$1RANK ウィンドウ関数
指定の行のパーセントランクを計算します。パーセントランクは、以下の式を使用して特定されます。
`(x - 1) / (the number of rows in the window or partition - 1)`
ここで、*x* は現在の行のランクです。以下のデータセットは、この式の使用方法を示しています。
```
Row# Value Rank Calculation PERCENT_RANK
1 15 1 (1-1)/(7-1) 0.0000
2 20 2 (2-1)/(7-1) 0.1666
3 20 2 (2-1)/(7-1) 0.1666
4 20 2 (2-1)/(7-1) 0.1666
5 30 5 (5-1)/(7-1) 0.6666
6 30 5 (5-1)/(7-1) 0.6666
7 40 7 (7-1)/(7-1) 1.0000
```
戻り値の範囲は、0～1 (0 と 1 を含みます) です。どのセットも、最初の行の PERCENT\$1RANK は 0 になります。
## 構文
```
PERCENT_RANK ()
OVER (
[ PARTITION BY partition_expression ]
[ ORDER BY order_list ]
)
```
## 引数
( )
この関数は引数を受け取りませんが、空のかっこは必要です。
OVER
ウィンドウのパーティションを指定する句。OVER 句にウィンドウフレーム仕様を含めることはできません。
PARTITION BY *partition\$1expression*
省略可能。OVER 句の各グループのレコードの範囲を設定する式。
ORDER BY *order\$1list*
省略可能。パーセントランクを計算する式。式は、数値データ型を含んでいるか、そのデータ型に暗黙的に変換できる必要があります。ORDER BY を省略した場合、すべての行について戻り値は 0 です。
ORDER BY で一意のソートが行われない場合、行の順序は不確定になります。詳細については、「[ウィンドウ関数用データの一意の並び順](Window_functions.md#Examples_order_by_WF)」を参照してください。
## 戻り型
FLOAT8
## 例
以下の例では、各販売者の販売数量のパーセントランクを計算します。
```
select sellerid, qty, percent_rank()
over (partition by sellerid order by qty)
from winsales;
sellerid qty percent_rank
----------------------------------------
1 10.00 0.0
1 10.64 0.5
1 30.37 1.0
3 10.04 0.0
3 15.15 0.33
3 20.75 0.67
3 30.55 1.0
2 20.09 0.0
2 20.12 1.0
4 10.12 0.0
4 40.23 1.0
```
WINSALES テーブルの説明については、「[ウィンドウ関数例のサンプルテーブル](Window_functions.md#Window_function_example)」を参照してください。
# RANK ウィンドウ関数
RANK ウィンドウ関数は、OVER 句の ORDER BY 式に基づいて、値のグループの値のランクを決定します。オプションの PARTITION BY 句がある場合、ランク付けは行のグループごとにリセットされます。ランク付け条件の値が等しい行は同じランクを受け取ります。 は、結合された行の数を結合されたランクAWS Clean Roomsに追加して次のランクを計算するため、ランクは連続した数値ではない可能性があります。例えば、2 行が 1 位にランク付けされると、次のランクは 3 位になります。
RANK と [DENSE\$1RANK ウィンドウ関数](WF_DENSE_RANK.md) では異なる点があり、DENSE\$1RANK では、2 行以上で同点となった場合、ランク付けされた値の順位に差はありません。例えば、2 行が 1 位にランク付けされると、次のランクは 2 位になります。
同じクエリに PARTITION BY および ORDER BY 句のあるランク付け関数を使用することができます。
## 構文
```
RANK () OVER
(
[ PARTITION BY expr_list ]
[ ORDER BY order_list ]
)
```
## 引数
( )
この関数は引数を受け取りませんが、空のかっこは必要です。
OVER
RANK 関数のウィンドウ句。
PARTITION BY *expr\$1list*
省略可能。ウィンドウを定義する 1 つ以上の式。
ORDER BY *order\$1list*
省略可能。ランク付けの値が基とする列を定義します。PARTITION BY が指定されていない場合、ORDER BY はテーブル全体を使用します。ORDER BY を省略した場合、すべての行について戻り値は 1 です。
ORDER BY で一意のソートが行われない場合、行の順序は不確定になります。詳細については、「[ウィンドウ関数用データの一意の並び順](Window_functions.md#Examples_order_by_WF)」を参照してください。
## 戻り型
INTEGER
## 例
次の例では、販売数量でテーブルで順序付けして (デフォルトは昇順)、行ごとにランクを割り当てます。1 のランク値は、もっとも高いランクの値です。結果はウィンドウ関数の結果が提供された後にソートされます。
```
select salesid, qty,
rank() over (order by qty) as rnk
from winsales
order by 2,1;
salesid | qty | rnk
--------+-----+-----
10001 | 10 | 1
10006 | 10 | 1
30001 | 10 | 1
40005 | 10 | 1
30003 | 15 | 5
20001 | 20 | 6
20002 | 20 | 6
30004 | 20 | 6
10005 | 30 | 9
30007 | 30 | 9
40001 | 40 | 11
(11 rows)
```
この例の外部 ORDER BY 句には、このクエリが実行されるたびに が一貫してソートされた結果をAWS Clean Rooms返すように、列 2 と 1 が含まれていることに注意してください。例えば、販売 ID 10001 および 10006 の行は、QTY と RNK の値が同じです。列 1 によって最終的な結果セットを順序付けると、行 10001 は常に 10006 の前になります。WINSALES テーブルの説明については、「[ウィンドウ関数例のサンプルテーブル](Window_functions.md#Window_function_example)」を参照してください。
次の例では、ウィンドウ関数 (`order by qty desc`) の順序付けは逆順になります。これで、最高ランク値が最大の QTY 値に適用されます。
```
select salesid, qty,
rank() over (order by qty desc) as rank
from winsales
order by 2,1;
salesid | qty | rank
---------+-----+-----
10001 | 10 | 8
10006 | 10 | 8
30001 | 10 | 8
40005 | 10 | 8
30003 | 15 | 7
20001 | 20 | 4
20002 | 20 | 4
30004 | 20 | 4
10005 | 30 | 2
30007 | 30 | 2
40001 | 40 | 1
(11 rows)
```
WINSALES テーブルの説明については、「[ウィンドウ関数例のサンプルテーブル](Window_functions.md#Window_function_example)」を参照してください。
次の例では、SELLERID によってテーブルをパーティション分割し、数量で各パーティションを順序付けして (降順)、行ごとにランクを割り当てます。結果はウィンドウ関数の結果が提供された後にソートされます。
```
select salesid, sellerid, qty, rank() over
(partition by sellerid
order by qty desc) as rank
from winsales
order by 2,3,1;
salesid | sellerid | qty | rank
--------+----------+-----+-----
10001 | 1 | 10 | 2
10006 | 1 | 10 | 2
10005 | 1 | 30 | 1
20001 | 2 | 20 | 1
20002 | 2 | 20 | 1
30001 | 3 | 10 | 4
30003 | 3 | 15 | 3
30004 | 3 | 20 | 2
30007 | 3 | 30 | 1
40005 | 4 | 10 | 2
40001 | 4 | 40 | 1
(11 rows)
```
# ROW\$1NUMBER ウィンドウ関数
OVER 句の ORDER BY 式に基づいて、行グループ内における (1 からカウントした) 現在の行の序数が決まります。オプションの PARTITION BY 句がある場合、序数は行グループごとにリセットされます。ORDER BY 式で同じ値を持つ行には、確定的でない方法で異なる行番号が割り当てられます。
## 構文
```
ROW_NUMBER () OVER
(
[ PARTITION BY expr_list ]
[ ORDER BY order_list ]
)
```
## 引数
( )
この関数は引数を受け取りませんが、空のかっこは必要です。
OVER
ROW\$1NUMBER 関数のウィンドウ句。
PARTITION BY *expr\$1list*
省略可能。ROW\$1NUMBER 関数を定義する 1 つ以上の式。
ORDER BY *order\$1list*
省略可能。行番号の基になる列を定義する式。PARTITION BY が指定されていない場合、ORDER BY はテーブル全体を使用します。
ORDER BY で一意の順序付けが行われない、または省略した場合、行の順序は不確定になります。詳細については、「[ウィンドウ関数用データの一意の並び順](Window_functions.md#Examples_order_by_WF)」を参照してください。
## 戻り型
BIGINT
## 例
次の例では、SELLERID によってテーブルをパーティション化し、QTY によって各パーティションを (昇順で) 順序付けし、各行に行番号を割り当てます。結果はウィンドウ関数の結果が提供された後にソートされます。
```
select salesid, sellerid, qty,
row_number() over
(partition by sellerid
order by qty asc) as row
from winsales
order by 2,4;
salesid | sellerid | qty | row
---------+----------+-----+-----
10006 | 1 | 10 | 1
10001 | 1 | 10 | 2
10005 | 1 | 30 | 3
20001 | 2 | 20 | 1
20002 | 2 | 20 | 2
30001 | 3 | 10 | 1
30003 | 3 | 15 | 2
30004 | 3 | 20 | 3
30007 | 3 | 30 | 4
40005 | 4 | 10 | 1
40001 | 4 | 40 | 2
(11 rows)
```
WINSALES テーブルの説明については、「[ウィンドウ関数例のサンプルテーブル](Window_functions.md#Window_function_example)」を参照してください。