HTTPのBinary列チュートリアル
📌
このチュートリアルでは、HTTPの
write APIとquery APIでbinary列を保存・検索する方法を説明します。サンプルテーブルの作成
CREATE TAG TABLE IF NOT EXISTS example (
name varchar(100) primary key,
time datetime basetime,
value double,
bindata binary
);HTTP APIでは、binary列を文字列で表現します。書き込みAPIは入力文字列からエンコーディングを判別し、検索APIはbinaryformatパラメーターで出力形式を選択します。
Binary文字列の規則
書き込みAPIにbinary列の文字列を渡すと、以下の規則でデコードします。
| 入力文字列 | 意味 |
|---|---|
0x0102 | 0xまたは0Xの接頭辞があるため、16進文字列としてデコードします。 |
AQI= | 0xの接頭辞がないため、標準のbase64文字列としてデコードします。 |
検索APIの既定の出力は16進文字列です。
binaryformat | 出力例 | 説明 |
|---|---|---|
省略またはhex | 0x0102 | すべてのバイトを16進文字列で出力します。 |
base64 | AQI= | 標準のbase64文字列で出力します。 |
bytes | [1 2] | バイト値を10進数の配列形式で出力します。 |
preview | 0x0102030405.. | 先頭部分のみを16進文字列で出力します。長い値の確認に使用します。 |
以下の例では、次の値を使用します。
0x0102とAQI=は、同じバイト値を表します。0x0304とAwQ=は、同じバイト値を表します。
JSONによるbinaryデータの入力
この例では、HTTP Write APIにmethod=insertを指定します。JSON入力では、16進文字列とbase64文字列の両方を使用できます。
```http
POST http://127.0.0.1:5654/db/write/example
?timeformat=s
&method=insert
Content-Type: application/json
{
"data": {
"columns": ["name", "time", "value", "bindata"],
"rows": [
["json-hex", 1713675600, 1.23, "0x0102"],
["json-base64", 1713675601, 2.34, "AwQ="]
]
}
}
```CSVによるbinaryデータの入力
この例では、HTTP Write APIにmethod=appendを指定します。CSV入力でもbinary列の値は文字列で、0xの接頭辞があれば16進数、なければbase64としてデコードします。
```http
POST http://127.0.0.1:5654/db/write/example
?timeformat=s
&method=append
&header=columns
Content-Type: text/csv
name,time,value,bindata
csv-hex,1713675610,10.5,0x0102
csv-base64,1713675611,20.5,AwQ=
```既定の形式でのデータ検索
Query APIにformat=jsonを指定します。binaryformatを省略すると、bindata列は16進文字列で返されます。
```http
GET http://127.0.0.1:5654/db/query
?q=select name,time,value,bindata from example where name in ('json-hex','json-base64','csv-hex','csv-base64')
&timeformat=s
&format=json
```{
"data": {
"rows": [
["json-hex", 1713675600, 1.23, "0x0102"],
["json-base64", 1713675601, 2.34, "0x0304"],
["csv-hex", 1713675610, 10.5, "0x0102"],
["csv-base64", 1713675611, 20.5, "0x0304"]
]
}
}Base64形式でのデータ検索
base64文字列でレスポンスを受け取るには、binaryformat=base64を指定します。このオプションは、format=csv、format=ndjson、format=boxにも適用されます。
```http
GET http://127.0.0.1:5654/db/query
?q=select name,time,value,bindata from example where name in ('json-hex','json-base64','csv-hex','csv-base64')
&timeformat=s
&format=csv
&binaryformat=base64
```NAME,TIME,VALUE,BINDATA
json-hex,1713675600,1.23,AQI=
json-base64,1713675601,2.34,AwQ=
csv-hex,1713675610,10.5,AQI=
csv-base64,1713675611,20.5,AwQ=最終更新日