本記事は、Manipulate data in FQL の日本語訳です（2024年5月14日更新）。

Flows Query Language (FQL) を使用すると、さまざまな方法で数学関数を実行したり、文字列や配列を操作したり、レスポンス内のデータを操作したりできます。サンプルデータと FQL の例を以下に示します。

文字列を扱う

文字列を挿入して説明で結果をグループ化して合計する
文字列の長さを返す
文字列の一部を返す
文字列を数値に変換する
パターンの最初の出現箇所の前の文字列を取得する
パターンの最初の出現箇所の後の文字列を取得する
文字列をすべて大文字に変換する
文字列をすべて小文字に変換する
文字列をトリムする
文字列をパディングする
文字列を要素の配列に分割する
文字列の配列をひとつの文字列に結合する
文字列を別の文字列に置き換える
文字列を Base64 エンコードする
文字列を Base64 デコードする
文字列を JSON に変換する

URL を扱う

URL コンポーネントをエンコードする
URL コンポーネントをデコードする
URL 全体をエンコードする
URL 全体をデコードする

日付と時刻を扱う

ISO 8601 形式で現在時刻を取得する
エポックからの Unix ミリ秒単位で現在時刻を取得する
指定した日付書式から Unix エポック時間に変換する
Unix エポック時間から指定した日付書式に変換する
日付から日・月・年を取得する
日付から時刻を取得する
日付から曜日を取得する
二つの日付を比較する
日付を一日加える
二つの日付の差を求める
時刻と日付のフォーマット

ロジックと配列を扱う

配列に追加する
If-then-else
配列を分割する
配列のそれぞれの値に対してアクションを実行する
値をフィルタリングする
配列を単一の値にまとめる
配列をソートする

オブジェクトを扱う

オブジェクトのそれぞれの値に対してアクションを実行する

サンプル JSON

以下の例では、この JSON データを使用しています：

    {
        "customer_info": {
            "customer field": "Customer data",
            "unformatted_customer_field": " customer \n stuff ",
            "total_value": "281.01",
            "associated_usernames": ["user1", "myuser", "online_user"]
        },
        "payments": [
            {
                "invoice_number": "101301",
                "date": "2022-09-11T16:12:34.494Z",
                "description": "recurring subscription",
                "amount": 110.48
            },
            {
                "invoice_number": "101302",
                "date": "2022-09-29T14:45:13.148Z",
                "description": "one time purchase",
                "amount": 24.49
            },
            {
                "invoice_number": "101303",
                "date": "2022-10-11T16:12:34.683Z",
                "description": "recurring subscription",
                "amount": 110.48
            },
            {
                "invoice_number": "101304",
                "date": "2022-10-12T11:45:22.182Z",
                "description": "recurring subscription deluxe",
                "amount": 35.56
            }
        ]
    }

文字列を挿入して説明で結果をグループ化して合計する

以下の例では、payments 配列のすべての description の値を取得し、annual cost という文字列を追加しています。次に、各 description フィールドの下の amount 値を取得し、それを 12 倍して対応する結果に追加します。結果は description フィールドごとにグループ化されます。

FQL	`payments.{description & " annual cost" : amount*12}`
結果	`[` `{"recurring subscription annual cost": 1325.76},` `{"one time purchase annual cost": 293.88},` `{"recurring subscription annual cost": 1325.76},` `{"recurring subscription deluxe annual cost": 426.72}` `]`

文字列の長さを返す

$length() 関数は、指定した文字列の長さを返します。以下の例は、payment 配列の最初のキーと値のペア description の文字列の長さを返します。

FQL	`$length(payments[0].description)`
結果	`22`

文字列の一部を返す

$substring() 関数は、指定した文字列の一部を返します。以下の例では、3 はオフセットを指定し、6 はオプションで選択する文字数を表します。オフセットには負の数を使用することもできます。

FQL	`$substring(payments[0].description, 3, 6)`
結果	`"urring"`

パターンの最初の出現箇所の前の文字列を取得する

以下の例では、$substringBefore() 関数は、指定した subscription が現れる前の部分文字列を返します。subscription が見つからない場合は、文字列全体を返します。

FQL	`$substringBefore(payments[0].description, "subscription")`
結果	`"recurring "`

パターンの最初の出現箇所の後の文字列を取得する

関数 $substringAfter() は、パターンを見つけるとその直後に続く部分文字列を返します。以下の例は、payments 配列の最初のオブジェクトの中のキーと値のペア description の recurring の後に続く部分文字列を返します。

FQL	`$substringAfter(payments[0].description, "recurring")`
結果	`" subscription"`

文字列をすべて大文字に変換する

$uppercase() 関数は、文字列のすべての文字を大文字に変換します。

FQL	`$uppercase(payments[0].description)`
結果	`"RECURRING SUBSCRIPTION"`

文字列をすべて小文字に変換する

$lowercase() 関数は、文字列のすべての文字を小文字に変換します。

FQL	`$lowercase(customer_info."customer field")`
結果	`"customer data"`

文字列をトリムする

$trim() 関数は、余分な先頭および末尾の空白を削除し、改行文字、キャリッジリターン文字、行フィード文字、タブ文字を単一の空白文字に変換し、連続する空白を単一の空白文字に削減します。

FQL	`$trim(customer_info.unformatted_customer_field)`
結果	`"customer stuff"`

文字列をパディングする

$pad() 関数は、文字列の長さの合計が2つ目のパラメーターと等しくなるように文字列にスペースや文字を追加します。2つ目のパラメーターが正の数の場合は、文字列の末尾を3つ目のパラメーターでパディングします。2つ目のパラメーターが負の数の場合、文字列の先頭を3つ目のパラメーターで埋めます（3つ目のパラメーターの文字は、指定されなければデフォルトで空白になります)。

FQL	`$pad(customer_info."customer field", 15, "#")`
結果	`"Customer data##"`

文字列を要素の配列に分割する

$split() 関数は、2つ目のパラメーターで指定した区切り文字で分割した文字列を返します。文字列の代わりに正規表現を使用することもできます。

FQL	`$split(payments[1].description, " ", 2)`
結果	`["one","time"]`

文字列の配列をひとつの文字列に結合する

$join() 関数は、文字列の配列から単一の文字列を作成します。以下の例は、associated_usernames キーから配列を取得し、配列の値をひとつの文字列として返します。

FQL	`$join(customer_info.associated_usernames)`
結果	`"user1myuseronline_user"`

文字列を別の文字列に置き換える

以下の例では、$replace() 関数が最初のパラメータ文字列から recurring のインスタンスを探し出し、最初に見つかったインスタンスを限定して（オプションで指定した 1 を使用）renewing に置き換えています。recurring のかわりに正規表現を使用することもできます。

FQL	`$replace(payments[0].description,"recurring", "renewing", 1)`
結果	`"renewing subscription"`

文字列を Base64 エンコードする

$base64encode() 関数は、文字列を base64 エンコーディングに変換します。以下の例は、文字列 "some data here" を "c29tZSBkYXRhIGhlcmU=" に変換します。

FQL	`$base64encode("some data here")`
結果	`"c29tZSBkYXRhIGhlcmU="`

文字列を Base64 デコードする

$base64decode() 関数は、base64 エンコードされた文字列を人間が読める文字列に変換します。以下の例は、"c29tZSBkYXRhIGhlcmU=" を "some data here" に変換します。

FQL	`$base64decode("c29tZSBkYXRhIGhlcmU=")`
結果	`"some data here"`

文字列を JSON に変換する

$jsonParse() 関数を使用すると、文字列を JSON にフォーマットして FQL でクエリできるようにします。以下の例では、{"Feedback Type": "Bug Report"} という文字列が input という名前の変数に格納されていると仮定しています。

FQL	`$jsonParse(input)`
結果	`{"Feedback Type":"Bug Report"}`

文字列を数値に変換する

文字列を数値に変換するには $number() 関数を使用します。以下の例は、customer_info オブジェクトの "281.01" という文字列を 281.01 という数値に変換します。

FQL	`$number(customer_info.total_value)`
結果	`281.01`

数値を合計する

$sum() 関数は、オブジェクトや配列の中のキーと値のペアのすべてのインスタンスから値を取得し、その値を加算して結果を返します。以下の例は、payment 配列のすべての amount フィールドの値を取得し、それらの合計を返します。

FQL	`$sum(payments.amount)`
結果	`"$281.01"`

二つの数値の差の絶対値を取得する

$abs() 関数は、二つの数値の差の絶対値を返します。差の絶対値は、数直線上の 2 つの値の間の距離です。差の絶対値は常に正です。

FQL	`$abs(4.56 - 6.78)`
結果	`2.22`

数値を切り上げる

関数 $ceil() は、数値を次の整数に切り上げます。

FQL	`$ceil(3.45)`
結果	`4`

数値を切り捨てる

$floor() 関数は、数値の小数点以下を切り捨てます。

FQL	`$floor(3.99)`
結果	`3`

数値のべき乗を求める

関数 $power() は、最初の数値を2つ目の数値のべき乗にします。以下の例は、2（基数）を 3（指数）のべき乗にします。

FQL	`$power(2,3)`
結果	`8`

数値の平方根を求める

関数 $sqrt() は、数値の平方根を返します。

FQL	`$sqrt(9)`
結果	`3`

数値を16進数または2進数に変換する

$formatBase() 関数は、数値を16進数や2進数に変換します。以下の例では 3000 を16進数に変換しています。16 の代わりに基数 2 を使用すると、3000 を2進数に変換します。

FQL	`$formatBase(3000, 16)`
結果	`"bb8"`

新しいランダムな請求書番号を生成する

$round($random()) 関数は、ランダムな整数を生成します。以下の例は、1 から 1000 までの整数をランダムに生成し、その値を "Invoice number " という文字列に付加して返します。

FQL	`"Invoice number " & $round($random()*1000)`
結果	`"Invoice number 891"`

数値を文字列に変換する

数値を文字列に変換するには $string() 関数を使用します。以下の例では、payments 配列の最初のオブジェクトの amount キーから数値を取得して "110.48" という文字列に変換しています。

FQL	`$string(payments[0].amount)`
結果	`"110.48"`

URL コンポーネントをエンコードする

$encodeUrlComponent() 関数は、URL コンポーネントの特定の文字を URL エンコードしたものに置き換えます。以下の例は、? を %3F に、= を %3D に置き換えたものです。

FQL	`$encodeUrlComponent("?city=melbourne")`
結果	`"%3Fcity%3Dmelbourne"`

URL コンポーネントをデコードする

$decodeUrlComponent() 関数は、URL コンポーネント内の URL エンコードされた文字を元のバージョンに置き換えます。以下の例は、%3F を ? に、$3D を = に置き換えたものです。

FQL	`$decodeUrlComponent("%3Fcity%3Dmelbourne")`
結果	`"?city=melbourne"`

URL 全体をエンコードする

$encodeUrl() 関数は、URL 内の特定の文字を URL エンコードした文字に置き換えます。以下の例は、こんにちは を %E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF に置き換えたものです。

FQL	`$encodeUrl("https://faketranslatewebsite.com/?phrase=こんにちは")`
結果	`"https://faketranslatewebsite.com/?phrase=%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF"`

URL 全体をデコードする

$decodeUrl() 関数は、URL 内の URL エンコード文字を元のバージョンに置き換えます。以下の例は、%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF を こんにちは に置き換えたものです。

FQL	`$decodeUrl("https://faketranslatewebsite.com/?phrase=%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF")`
結果	`"https://faketranslatewebsite.com/?phrase=こんにちは"`

ISO 8601 形式で現在時刻を取得する

$now() 関数は、現在の時刻を ISO 8601 形式で返します。

FQL	`$now()`
結果	`"2022-11-04T22:36:57.094Z"`

エポックからの Unix ミリ秒単位で現在時刻を取得する

$millis() 関数は、現在の時刻をエポックからの Unix ミリ秒単位で返します。

FQL	`$millis()`
結果	`1667601477254`

指定した日付書式から Unix エポック時間に変換する

関数 $toMillis() は、指定した日付書式を Unix エポック時間に変換します。日付書式の詳細については、後述の書式のセクションを参照してください。

FQL	`$toMillis("10/12/2018 11:39 PM", "[M]/[D]/[Y] [h]:[m] [P]")`
結果	`1539387540000`

Unix エポック時間から指定した日付書式に変換する

$fromMillis() 関数は、Unix エポック時間を別の日付書式に変換します。日付書式の詳細については、後述の書式のセクションを参照してください。

FQL	`$fromMillis(1539387540000, "[Y]-[M]-[D] [H]:[m]:[s] [z]")`
結果	`"2018-10-12 23:39:00 GMT+00:00"`

日付から日・月・年を取得する

$year()、$month()、$day() 関数は、year-month-day 日付フォーマットからそれぞれの要素を返します。

FQL	`$year("2023-02-11") & "-" & $month("2023-02-11") & "-" & $day("2023-02-11")`
結果	`"2023-2-11"`

日付から時刻を取得する

$hours()、$minutes()、$seconds()、$milliseconds() 関数は、指定した日付からそれぞれの値を返します。以下の例では、日付に $now() 関数を使用しています。

FQL	`$hours($now()) & ":" & $minutes($now()) & ":" & $seconds($now()) & ":" & $milliSeconds($now())`
結果	`"19:23:8:143"`

日付から曜日を取得する

関数 $dayOfTheWeek() は、日付を受け取って曜日に対応する数値を返します。0 は日曜日、1 は月曜日、といった具合です。

FQL	`$dayOfTheWeek($now())`
結果	`2`

二つの日付を比較する

$hasSameDate() 関数は、2つの日付と、日付の値を指定するパラメーターを指定します。この関数は、パラメーターで指定した値を比較し、同じ場合は true を、違う場合は false を返します。

FQL	`$hasSameDate("2023-02-01", "2023-02-08", ["month", "year"])`
結果	`true`

日付を一日加える

$datePlus() 関数には、日付（YYYY-MM-DD あるいはエポックからのミリ秒）、加算したい数、そして進めたい日付要素（years、months、days、hours、minutes、seconds、milliseconds のいずれか）を指定します。この関数は、加算した日付をエポックからのミリ秒として返します。

FQL	`$datePlus("2023-02-07", 1, "days")`
結果	`1675814400000`

二つの日付の差を求める

関数 $diffDate() は、2つの日付（書式は YYYY-MM-DD あるいはエポックからのミリ秒）と、それぞれの日付要素（years、months、days、hours、minutes、seconds、milliseconds のいずれか）を受け取り、2つの日付の要素の差を返します。

FQL	`$diffDate("2023-02-08", "2023-01-22", "days")`
結果	`17`

時刻と日付のフォーマット

文字	説明
Y	年
M	数値としての月
D	月の日
d	年の日
F	週の日
W	年の週
w	月の週
H	時（24時間）
h	時（12時間）
P	am/pm マーカー
m	分
s	秒
f	小数秒
Z	タイムゾーン
z	GMT を使用した時間オフセットとして接頭辞を含めるように修正したタイムゾーン
C	暦: 暦の名称または略称
E	時代: 君主の在位期間など、年数の数え方の基準となる名前

配列に追加する

$append() 関数は、2つの配列、配列と1つの値、あるいは2つの文字列を1つの配列にまとめることができます。

FQL	`$append([1,2,3], [4,5,6])`
結果	`[1,2,3,4,5,6]`

If-then-else

$boolean 値は真偽判定です。2番目の値は true の場合の出力で、最後の値は false の場合の出力です。以下の例は、total_value フィールドの値が 250 より大きいかどうかをテストします。値が 250 より大きいので、この関数は "high-value customer" を返します。

FQL	`$boolean(customer_info.total_value > 250) ? "high-value customer" : "not a high-value customer"`
結果	`"high-value customer"`

配列を分割する

$partition() 関数は、配列をより小さな配列に分割し、より小さな配列をリストとして返します。

FQL $partition(payments,2)

結果 [
[{"invoice_number": "101301","date": "2022-09-11T16:12:34.494Z","description": "recurring subscription","amount": 110.48},{"invoice_number": "101302","date": "2022-09-29T14:45:13.148Z","description": "one time purchase","amount": 24.49}],
[{"invoice_number": "101303","date": "2022-10-11T16:12:34.683Z","description": "recurring subscription","amount": 110.48},{"invoice_number": "101304","date": "2022-10-12T11:45:22.182Z","description": "recurring subscription deluxe","amount": 35.56}]
]

配列のそれぞれの値に対してアクションを実行する

この例では、$map() 関数で payments 配列の amount フィールドから数値を取得し、$string() 関数で文字列に変換しています。

FQL	`$map(input.payments[].amount,$string)`
結果	`["110.48", "24.49", "110.48", "35.56"]`

値をフィルタリングする

この例では、$filter() 関数は payments 配列の amount フィールドから 40 より大きい値を返します。

FQL	`$filter(input.payments[].amount,fn($v,$i,$a) { $v > 40})`
結果	`[110.48, 110.48]`

配列を単一の値にまとめる

$reduce() 関数は、配列のすべての要素に関数を適用します。この例では、配列のすべての要素を足し合わせます。

FQL	`$reduce(input.payments[].amount,fn($i, $j){$i + $j})`
結果	`281.01`

配列をソートする

$sort() 関数は、指定した関数で配列をソートします。$j は現在の項目、$i は次の項目です。

FQL	`$sort(input.payments[].amount,fn($i, $j){$i < $j})`
結果	`[110.48, 110.48, 35.56, 24.49]`

オブジェクトのそれぞれの値に対してアクションを実行する

この例では、$each() 関数でオブジェクト内のすべての文字列値を大文字に変換しています。

FQL	`$each({"transaction_id": "inv_80394", "description": "buying 20 units of data"},$uppercase)`
結果	`["INV_80394", "BUYING 20 UNITS OF DATA"]`