テーブルの列を調べる
クエリを書く前に、まずテーブルにどんな列があるかを確認する。対話モードで .inspect テーブル名 と打つと、列の名前・型・説明が表示される。
> .inspect aws_ec2_instance+------------------------+--------------------------+----------------------------------------------+
| column | type | description |
+------------------------+--------------------------+----------------------------------------------+
| instance_id | text | The ID of the instance. |
| instance_state | text | The state of the instance (pending | running |
| | | | shutting-down | terminated | stopping | |
| | | stopped). |
| instance_type | text | The instance type. |
| launch_time | timestamp with time zone | The time the instance was launched. |
| security_groups | jsonb | The security groups for the instance. |
| tags | jsonb | A map of tags for the resource. |
| ... | | |
+------------------------+--------------------------+----------------------------------------------+テーブル名がうろ覚えのときは、.inspect aws で一覧を出すか、入力中に Tab キーで補完候補を出す。Web で調べるなら、Steampipe Hub のテーブル一覧に、テーブルごとの列とクエリ例が載っている。テーブルによっては「Important Notes」に使い方の注意(必須の条件や料金)が書かれているので、初めて使うテーブルは一度目を通しておくとよい。
型は PostgreSQL の型で、よく出てくるのは text・bigint・boolean・timestamp with time zone・jsonb の5つだ。日時は timestamp with time zone なので、now() - interval '90 days' のような比較がそのまま書ける。boto3 のように datetime 型を JSON にできずにつまずくこともない。
select * が遅い理由:列ごとに呼ばれるAPI
Steampipe を使い始めて最初に気づくのが、select * が驚くほど遅いテーブルがあることだ。理由は、テーブルの列が「一覧の API で取れる列」と「1行ずつ追加の API を呼んで埋める列」に分かれているからである。Steampipe では、この追加の呼び出しを hydrate と呼ぶ。
S3 バケットのテーブル aws_s3_bucket がわかりやすい。バケットの一覧は ListBuckets 1回で取れるが、それ以外の列はバケットごとに別の API が必要になる。
| 列 | 値を埋めるために呼ばれる API | 回数 |
|---|---|---|
name, creation_date | ListBuckets | 全体で1回(ページ数ぶん) |
region | GetBucketLocation | バケットごとに1回 |
versioning_enabled | GetBucketVersioning | バケットごとに1回 |
block_public_acls など4列 | GetPublicAccessBlock | バケットごとに1回(4列で共有) |
policy, policy_std | GetBucketPolicy | バケットごとに1回 |
tags | GetBucketTagging | バケットごとに1回 |
| (ほか暗号化・ライフサイクル・ログ・レプリケーション…) | それぞれ別の API | バケットごとに1回ずつ |
select * にすると、これらがすべて呼ばれる。バケットが200個あれば、数千回の API 呼び出しになる。一方、select name, region from aws_s3_bucket なら、ListBuckets と、バケットごとの GetBucketLocation だけで済む。
EC2 の aws_ec2_instance は、ほとんどの列が DescribeInstances で取れるが、user_data・disable_api_termination・instance_status・launch_template_data などはインスタンスごとに追加の API が呼ばれる。欲しい列だけを書くのが、Steampipe で一番効果のある高速化だ。
実際にどれだけ呼ばれたかは、.timing on で確かめられる。クエリのあとに、かかった時間・取得した行数・hydrate の回数が表示される(下は出力の例)。
> .timing on
> select name, region from aws_s3_bucket;
...
Time: 3.1s. Rows returned: 48. Rows fetched: 48. Hydrate calls: 48.
> select name, region from aws_s3_bucket;
...
Time: 41ms. Rows returned: 48. Rows fetched: 48 (cached). Hydrate calls: 0.2回目は (cached) と表示され、API を呼ばずにキャッシュから返っている。キャッシュについては後半で扱う。なお、count(*) は列の値を必要としないため、追加の API は呼ばれない。
AWS側で絞り込まれる条件と、手元で絞り込まれる条件
where の条件も、書き方によって効き方が変わる。テーブルには キー列(Steampipe の用語では qualifier)が決められていて、キー列に対する条件は API のパラメーターとして AWS に渡される。それ以外の列の条件は、全件を取ってきてから PostgreSQL が絞り込む。
-- instance_state はキー列。DescribeInstances の Filters として渡される
select instance_id, instance_type
from aws_ec2_instance
where instance_state = 'running';-- tags はキー列ではない。全インスタンスを取得してから絞り込む
select instance_id, instance_type
from aws_ec2_instance
where tags ->> 'Env' = 'prod';どちらも結果は正しいが、件数が多いアカウントでは速さと API の呼び出し回数に差が出る。boto3 の PART 03 で「サーバー側の Filters」と「手元の JMESPath」を使い分けたのと同じ考え方で、Steampipe ではキー列に条件を書くと自動でサーバー側の絞り込みになる。
どの列がキー列かは、Hub のテーブルのページ(Important Notes に「optional quals」として書かれていることが多い)か、プラグインのソースコードで確認する。主なテーブルのキー列を挙げておく。
| テーブル | 主なキー列 | 使える演算子 |
|---|---|---|
aws_ec2_instance | instance_id(1件取得), instance_state, instance_type, image_id, placement_availability_zone など | = |
aws_ebs_volume | volume_id, state, volume_type, encrypted など | =(encrypted などは <> も) |
aws_rds_db_instance | db_instance_identifier(1件取得), db_cluster_identifier, engine | = |
aws_iam_access_key | user_name | = |
aws_cost_by_service_monthly | service, period_start, period_end | = ほか、期間は >= < なども |
テーブルによっては、キー列の条件が必須のものもある。たとえば任意のメトリクスを取る aws_cloudwatch_metric_data_point は、where で id と expression(または metric_stat)を指定しないとエラーになる(PART 05)。必須条件が足りないときは、どの列を指定すべきかがエラーメッセージに出る。
💡 limit は取得を早めに打ち切る
手元での絞り込みや並べ替えを含まない単純なクエリなら、limit 5 と書くと、プラグインは5行そろった時点で API の呼び出しをやめる。大きなテーブルの中身を眺めるときは、select * ... limit 5 から始めると待たずに済む。
JSONB列の扱い(タグ・配列・入れ子)
API が返す入れ子のデータは、jsonb 型の列に入っている。PostgreSQL の JSON 演算子で取り出す。よく使うものは次の5つで足りる。
| 書き方 | 意味 | 例 |
|---|---|---|
->> 'キー' | 値を文字列(text)で取り出す | tags ->> 'Name' |
-> 'キー' | 値を jsonb のまま取り出す(さらに辿るとき) | metadata_options -> 'HttpTokens' |
? 'キー' | キーが存在するか | tags ? 'Owner' |
@> '{...}' | 指定した内容を含むか | tags @> '{"Env": "prod"}' |
jsonb_array_elements(列) | 配列を1要素1行に展開する | jsonb_array_elements(security_groups) |
タグは PART 01 で紹介したとおり {"Name": "web-01", "Env": "prod"} の形になっているので、tags ->> 'Name' で取り出せる。Owner タグが付いていないインスタンスを探すなら次のようになる。
select instance_id, title, region
from aws_ec2_instance
where not (tags ? 'Owner');配列の列は、jsonb_array_elements で行に展開してから扱う。EC2 に付いているセキュリティグループを1行ずつ出す例だ。
select
i.instance_id,
i.title,
sg ->> 'GroupId' as group_id,
sg ->> 'GroupName' as group_name
from
aws_ec2_instance as i,
jsonb_array_elements(i.security_groups) as sg
order by
i.instance_id;JSON の形がわからないときは、jsonb_pretty(列) で整形して1行だけ見てみるとよい(select jsonb_pretty(security_groups) from aws_ec2_instance limit 1;)。キーの名前は API のレスポンスのまま(大文字始まり)なので、boto3 のレスポンスを見たことがあれば同じ名前で辿れる。
⚠️ JSONB の中身での絞り込みは、すべて手元で行われる
tags ->> 'Env' = 'prod' のような条件はキー列の条件にならないため、全件を取ってから絞り込む。件数の多いテーブルでは、キー列の条件(instance_state = 'running' など)を併せて書いて、取得する量を減らしておく。
テーブルをJOINする
Steampipe を使う一番の理由が、サービスをまたいだ join だ。たとえば、SSM でポートフォワードしたいのに接続できない EC2 を探すなら、EC2 の一覧と SSM のマネージドインスタンスの一覧を突き合わせればよい。
select
i.instance_id,
i.title,
i.region,
s.ping_status
from
aws_ec2_instance as i
left join aws_ssm_managed_instance as s
on s.instance_id = i.instance_id
and s.region = i.region
where
i.instance_state = 'running'
and (s.instance_id is null or s.ping_status <> 'Online');boto3 なら、2つの API の結果を dict にしてキーで突き合わせるコードを書くところだ。結合の条件には、同じリソースを指す列(ここでは instance_id)に加えて、region(複数アカウントなら account_id も)をそろえておくと、別リージョンの同名リソースを誤って結びつける心配がない。
💡 JOIN が遅いときは、先に取ってから結合する
結合の条件がもう一方のテーブルのキー列だと、PostgreSQL が「左の1行ごとに右のテーブルを問い合わせる」実行計画を選び、API の呼び出しが増えることがある。遅いと感じたら、片方を with s as materialized (select ... from aws_ssm_managed_instance) のように先に取り出してから結合すると、まとめて1回の取得で済む。
キャッシュ:結果が古いと感じたら
Steampipe は、取得した結果を 既定で300秒(5分)キャッシュする。同じテーブルを、同じかより少ない列・同じかより厳しい条件で問い合わせると、API を呼ばずにキャッシュから返す。API の呼び出しとスロットリングを減らすための仕組みだが、コンソールで変更した直後に問い合わせると、変更前の結果が返ることがある。
対話モードでは、次のメタコマンドでキャッシュを操作できる。いずれもその対話セッションの中だけで有効だ。
| メタコマンド | 動作 |
|---|---|
.cache clear | これより前のキャッシュを使わないようにする(変更を確かめたいときはこれ) |
.cache off / .cache on | キャッシュを使わない / 使う |
.cache_ttl 60 | このセッションのキャッシュの有効期間を60秒にする |
逆に、棚卸しのように「数分前の状態で十分」な作業では、有効期間を延ばしたほうが速く、API にもやさしい。サーバー側の上限は default.spc、steampipe query が使う既定値は workspaces.spc に書く(どちらも ~/.steampipe/config/ の下)。
options "database" {
cache = true
cache_max_ttl = 900 # サーバー側の上限(秒)
}workspace "default" {
cache_ttl = 900 # steampipe query で使う有効期間(秒)
}クライアント側の cache_ttl をいくら長くしても、サーバー側の cache_max_ttl を超えることはない。なお、キャッシュは内蔵データベースのプラグインのプロセスが持っている。サービスを起動していないと、steampipe query を実行するたびにプラグインが起動し直すため、前のコマンドのキャッシュは使われない。何本ものクエリを続けて流すなら、サービスを起動しておくと2本目以降が速くなる。
エラーとリトライの挙動
API の呼び出しが失敗したときの挙動も知っておきたい。
- スロットリングなど一時的なエラー:プラグインが自動でリトライする。既定では最大9回(初回を含む)で、間隔は指数的に延びる。回数は
aws.spcのmax_error_retry_attemptsで変えられる - 「見つからない」系のエラー(削除された直後のリソースなど):そのリソースは結果から除かれ、クエリは続く
- 権限不足(AccessDenied など):クエリ全体がエラーになり、結果は返らない。どの API で拒否されたかがメッセージに出る
3つ目は、特定の列だけ権限が足りないときにも起こる。たとえば S3 バケットのポリシーを読む権限がないのに select * をすると、GetBucketPolicy で拒否されて全体が失敗する。必要な列だけを選べば、その API は呼ばれないので成功する。ここでも「欲しい列だけを書く」ことが効いてくる。
権限のないリージョンやサービスを無視して結果を出したい場合は、ignore_error_codes で特定のエラーを無視できる。ただし、無視したぶんはエラーにならずに結果から黙って抜け落ちるので、使いどころは PART 06 で確認してほしい。
✅ 次の記事では…
PART 04 では、ここまでの書き方を使って、全リージョンの EC2・EBS・RDS・Lambda・S3 を1つの表にまとめる棚卸しクエリを作り、Excel で開ける CSV に出力する。