> ActQL_ v0.0-alpha
目次
リファレンス

型と関数

プログラムが扱う値の型、パラメーターの宣言の仕方、そして関数と演算の一覧を系統ごとにまとめます。名前は言語の仕様の正式なもので、SQLでの綴りが違う場合は併記します。値の厳密な規則、NULLの規則、失敗の規則は仕様にあります。このページはリファレンスとして活用してください。

スカラー型

型SQLでの綴り中身
stringSTRINGUnicodeのテキスト。書いたまま保持する（正規化しない）。
numberNUMBER、FLOAT64、DOUBLE有限のIEEE-754倍精度浮動小数点数。
decimal(P,S)DECIMAL(P,S)精度とスケールを持つ正確な10進数。金額にはこれを使う。
booleanBOOLEANTRUE または FALSE。
timestampTIMESTAMP時刻。正規形はUTCの YYYY-MM-DDTHH:mm:ss.sssZ。
dateDATE暦の日付 YYYY-MM-DD。timestampとは別の型。
json型のないJSON。静的なフィールド情報を持たない。
object宣言された型付きのフィールドを持つ、閉じたレコード。
arrayARRAY<T>宣言された1つの要素型を持つ値のリスト。
vector次元数の決まった32ビット浮動小数点数のベクトル。
resource_ref外部システムのリソースへの不透明な参照。
content_refコンテンツ（Artifact）への不透明な参照。メディアタイプを持つことがある。

すべての列とフィールドには、型と nullable かどうかが決まっています。NULL は、スキーマが nullable と言っている場所にだけ入ります。外部システムが省略することのある列は、nullable な列とは別の概念です。SQL互換性を参照してください。

パラメーター

プログラムは、型、nullable かどうか、任意の既定値を付けてパラメーターを宣言します。値は実行時に渡します（CLIでは --params、SDKでは parameters オプション）。クエリテキストの中では @name と書きます。

規則意味
宣言できる型上のスカラー型、object、それらの array。vector は不可。
既定値値がないときに一度だけ適用される。明示的な NULL は「ない」とは違う。
使える場所式が書ける場所ならどこでも。LIMIT/OFFSET と、作者のガードにも使える。
できないことテキストに補間すること、演算を選ぶのに使うこと、リソースの名前に使うこと。

変換

関数SQL結果
to_string(x)CAST(x AS STRING)文字列、数値、decimal、boolean、timestamp、dateの正規の綴り。
to_number(x)CAST(x AS NUMBER)文字列か数値から。数値でないテキストは失敗する。
to_boolean(x)CAST(x AS BOOLEAN)文字列かbooleanから。
to_timestamp(x)CAST(x AS TIMESTAMP)文字列かtimestampから。
to_decimal(x)CAST(x AS DECIMAL(P,S))正確に変換する。丸めるのではなく失敗する。
try_number、try_timestamp、try_decimal同じ変換で、不正な入力のときは失敗する代わりに NULL を返す。
quantize(d, scale)decimalをスケールに丸める（decimalの丸めはこれだけ）。

文字列

関数結果
len(s) / LENGTHUnicodeスカラー値の数。
byte_length(s) / BYTE_LENGTH、OCTET_LENGTHUTF-8のバイト数。
lower、upper固定したUnicodeテーブルによる大文字小文字の変換。
trim、ltrim、rtrim (s[, chars])空白か、指定した文字を取り除く。
left、right (s, n)先頭または末尾の n スカラー値。
lpad、rpad (s, n[, pattern])n スカラー値になるよう埋めるか切り詰める。
substring(s, pos[, len])1始まりのスカラー値の位置。
concat(…) / CONCAT、||連結する。いずれかの引数が NULL なら NULL（ACTQL.CONCAT はNULLを飛ばす）。
replace(s, from, to)すべての出現を置き換える。
split(s[, delimiter])分割した配列。区切りの既定は ,。
split_part(s, delimiter, i)1つの部分。1始まりで、負の数は末尾から数える。
contains、starts_with、ends_with完全一致。
instr(s, sub[, pos[, occurrence]])、strpos(s, sub)位置。1始まりで、見つからなければ0。
translate(s, from, to)文字を対応付けるか削除する。
unicode(s) / UNICODE先頭のスカラー値のコードポイント。
utf8_truncate(s, max_bytes)バイト数の予算に収まる最長の接頭辞。スカラー値の途中で切らない。
nfkc(s)、case_fold(s)Unicodeの正規化と畳み込み（text-timeプロファイル）。
regex_match、regex_extract、regex_replace固定した正規表現の文法（text-timeプロファイル）。
templateto_string と厳密な連結の上に作られた、書くためのマクロ。

数値

関数結果
+ - * /倍精度の算術。ゼロ除算は失敗する。
abs、sign、floor、round(x[, n])、trunc(x[, n])GoogleSQLと同じ。round は半分をゼロから遠い方に丸める。
sqrt、cbrt、pow、exp、ln、log(x, base)、log10定義域の誤り（負の平方根、正でない対数）は失敗する。
sin、cos、tan、asin、acos、atan、atan2、sinh、cosh、tanh、asinh、acosh、atanh三角関数。
greatest(…)、least(…)1つ以上の数値に対して。いずれかが NULL なら NULL。
safe_add、safe_subtract、safe_multiply、safe_divide、safe_negateオーバーフローやゼロ除算のとき、失敗する代わりに NULL を返す。
negate数値とdecimalの単項マイナス。

decimalには add、subtract、multiply、比較、sum、min、max、decimal_divide(d, divisor)、quantize を使います。decimalの avg は拒否されます。sum、count、decimal_divide で明示的に書いてください。

日付と時刻

関数結果
date_trunc(t, unit)ms、s、m、h、d（固定のUTC単位）に切り詰める。
date_add(t, n, unit)固定の単位を足す。dateには日単位だけ使える。
date_diff(a, b, unit)単位での差。ゼロに向かって切り捨てる。
parse_timestamp(format, s)、format_timestamp(format, t)固定したtimestampの文法（text-timeプロファイル）。
calendar_bucket、calendar_series暦を考慮したバケット（月、週、タイムゾーン）。calendarプロファイル。

固定の単位は暦の計算をしません。1日はちょうど86,400,000ミリ秒です。月やタイムゾーンにはcalendarプロファイルを使ってください。

条件と比較

関数結果
if(cond, a, b) / IF選ばれた分岐だけを評価する。
case / CASE WHEN … END最初に真になった分岐。どれも真でなく ELSE もなければ NULL。
coalesce(…) / COALESCE、IFNULL最初のNULLでない引数。
nullif(a, b) / NULLIF等しければ NULL。
in、not_in / IN (…)、IN UNNEST(…)所属。NULLの規則はGoogleSQLのとおり。要素に NULL があると、一致しない場合の結果は NULL（1 IN (NULL) は NULL）。UNNEST に渡した配列が NULL または空なら空集合（1 IN UNNEST(CAST(NULL AS ARRAY<INT64>)) は FALSE）。

object、array、JSON

形結果
{field: expr, …}、[expr, …]閉じたobjectかarrayを作る。
obj.field、obj.*型付きのアクセス。受け手が nullable なら NULL になる。
UNNEST(array)配列をレコードに展開する（宣言された値テーブル）。
ARRAY_AGG、STRING_AGG配列や区切り付きの文字列に集計する。

集計とウィンドウ

count、count_if、sum、avg、min、max、array_agg、string_agg に、任意の絞り込みと並び順を付けられます。加えて、PARTITION BY / ORDER BY / フレームによるウィンドウ（分析）形式があります。浮動小数点数の合計は、復旧時に取り込んだ値を再生します。結果が正確でなければならない場合は decimal を使ってください。

ベクトル演算

以下の各呼び出しの形と引数は、構文リファレンスにあります。

演算結果
vector_score(a, b, 'cosine' | 'dot' | 'l2')レコード内の類似度（l2 は距離の符号を反転したもの）。SQL: VECTOR_COSINE_SIMILARITY、VECTOR_INNER_PRODUCT、VECTOR_L2_DISTANCE。
vector_concat(a, b, …) / VECTOR_CONCATベクトルを連結する。
nearest / |> NEAREST問い合わせのレコードごとに、指標で近い候補をK件。
normalize_vectors、score_vectors、pool_vectorsVectors Carrierに対する演算。
merge_rankings順位付きのリストを融合する（rrf、max、weighted_sum のスコアポリシー）。
to_vectors、vectorsレコードとVectorsの橋渡し。

グラフ演算

以下の各呼び出しの形と引数は、構文リファレンスにあります。

演算結果
GRAPH (NODE TABLES (…) [EDGE TABLES (…)])RelationからGraphを作る。
MATCH patternGoogleSQLの要素パターンのプロファイルによるパターンマッチ。match_nodes、match_edges はID、ラベル、述語で要素を選ぶ。
reach、traverse、shortest_path、components、degree、graph_bounds到達可能性、歩き方、経路、連結成分、次数、範囲。
subgraph、graft_graph、union_graphs、subtract_graphs、normalize_graphグラフ全体に対する構造の演算。
graphs_equal、graph_diff、apply_graph_delta、mean_graphs比較、差分、差分の適用、平均。
node_rows、edge_rows、graphRelationとGraphの橋渡し。

イベント演算

以下の各呼び出しの形と引数は、構文リファレンスにあります。

演算結果
to_events、eventsレコードとEvents Carrierの橋渡し。
window_events、row_window固定ウィンドウとスライディングウィンドウ（イベントまたはレコードに対して）。
session間隔によるセッションの割り当て。
watermark_events、watermark_rowsウォーターマークのラベル付け。
dedupe_eventsキーによるイベントの重複排除。
sequence順序付きのイベントパターンの照合。
asof_join、interval_join時刻に基づく結合。
time_series、calendar_series、calendar_bucket系列の生成と、暦のバケット。
lag、window_groupリレーショナルなナビゲーションと、ウィンドウ付きのグループ化。

その他の演算

演算結果
infer / |> INFERレコードごとにLLMに問い合わせる。LLMとINFERを参照。
serialize / |> SERIALIZEレコードをコンテンツ（content_ref）にする。
assert_rows / |> ASSERT UNIQUE BY一意性を証明するか、失敗する。
valuesリテラルの有限なRelation。

プログラムにしかない演算

top_k、top_k_by、json_pick、nest、dedupe_rows、search_candidates、text_rank は、JSON/YAMLのプログラム文書には存在しますが、SQLやPipeでの書き方がありません。構文リファレンスに、同じ結果を得られるSQLがある場合はそれとあわせて一覧があります。

各環境が現時点にこのうちどれを実行できるかは、実装状況にあります。

Source: actql/actql/docs/reference/types-and-functions.md at d904416674e4 · Edit on GitHub

SQL互換性

Previous Page

実装状況

What runs today in each environment and for each Connector: implemented, experimental or planned.