検索 API
共通仕様
認証・エラー形式・レート制限・共通ヘッダーは API 概要・認証 を参照してください。
ログデータを PRQL クエリで検索するための API である。
検索実行
パスパラメータ:
| パラメータ | 型 | 説明 |
|---|---|---|
user_id |
string | ユーザー ID |
リクエストヘッダー:
リクエストボディ:
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
expr |
string | Yes | PRQL クエリ式 |
runAs |
string | No | 実行ユーザーの組織 UUID（管理者向け） |
is_date_histogram |
boolean | No | 日時ヒストグラム用クエリかどうか |
system |
boolean | No | システムテーブルへのクエリかどうか |
リクエスト例:
レスポンス:
レスポンスは列指向バイナリ形式のストリームで返る（Content-Type: application/vnd.apache.arrow.stream）。
この形式に対応したクライアントライブラリで読み込んでデータフレーム化できる。
Python での利用例:
import pyarrow as pa
import requests
response = requests.post(
"https://<your-domain>/api/v2/user/<user_id>/search/",
headers={"Cookie": "jwt=<token>"},
json={"expr": "from `firewall_logs` take 10"}
)
reader = pa.ipc.open_stream(response.content)
table = reader.read_all()
df = table.to_pandas()
print(df)
集計の応答時間について
検索時にフィールドを抽出する schema-on-read のため、集計（group を伴うクエリ）では対象列をスキャンする。
特定キーの絞り込み（point lookup）は速い一方、広い範囲の GROUP BY 集計は応答に時間を要することがある。
これはスキーマ柔軟性、取り込み速度、移行容易性とのトレードオフである。
PRQL クエリリファレンス
基本構文
from `<pipeline名>`
filter <条件>
select {<フィールド>}
group {<フィールド>} (aggregate {<集計>})
sort {<ソート>}
take <件数>
フィルタ演算子
| 演算子 | 説明 | 例 |
|---|---|---|
== |
等価 | filter status == 200 |
!= |
不等価 | filter status != 404 |
> |
より大きい | filter bytes > 1000 |
< |
より小さい | filter bytes < 5000 |
>= |
以上 | filter status >= 400 |
<= |
以下 | filter status <= 499 |
~= |
部分一致（正規表現） | filter message ~= "error" |
集計関数
| 関数 | 説明 | 例 |
|---|---|---|
count |
件数 | aggregate {n = count this} |
sum |
合計 | aggregate {total = sum bytes} |
average |
平均 | aggregate {avg_time = average response_time} |
min |
最小値 | aggregate {min_val = min value} |
max |
最大値 | aggregate {max_val = max value} |
クエリ例
Top 10 送信元 IP
from `firewall_logs`
filter action == "DENY"
group {src_ip} (
aggregate {cnt = count this}
)
sort {-cnt}
take 10
時間範囲指定
from `auth_logs`
filter __time > @2025-01-01
filter __time < @2025-01-31
filter message ~= "failed"
sort {-__time}
フィールド選択と変換
from `web_access`
select {__time, method, path, status, response_time}
filter status >= 500
sort {-__time}
take 50
Sigma ルール変換
Sigma ルールを CSIRT-Pro のクエリ形式に変換する。
リクエストボディ:
Sigma ルール（YAML 形式）を文字列として送る。
レスポンス:
変換されたクエリが返る。
タグフィルタ
X-SOCEngine-Tags ヘッダーで検索結果にタグベースのフィルタを適用できる。