テーブルの列を調べる

クエリを書く前に、まずテーブルにどんな列があるかを確認する。対話モードで .inspect テーブル名 と打つと、列の名前・型・説明が表示される。

steampipe query(対話モード)
> .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_dateListBuckets全体で1回(ページ数ぶん)
regionGetBucketLocationバケットごとに1回
versioning_enabledGetBucketVersioningバケットごとに1回
block_public_acls など4列GetPublicAccessBlockバケットごとに1回(4列で共有)
policy, policy_stdGetBucketPolicyバケットごとに1回
tagsGetBucketTaggingバケットごとに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 の回数が表示される(下は出力の例)。

steampipe query(対話モード)
> .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 が絞り込む。

SQL:AWS 側で絞り込まれる
-- instance_state はキー列。DescribeInstances の Filters として渡される
select instance_id, instance_type
from aws_ec2_instance
where instance_state = 'running';
SQL:手元で絞り込まれる
-- 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_instanceinstance_id(1件取得), instance_state, instance_type, image_id, placement_availability_zone など=
aws_ebs_volumevolume_id, state, volume_type, encrypted など=(encrypted などは <> も)
aws_rds_db_instancedb_instance_identifier(1件取得), db_cluster_identifier, engine=
aws_iam_access_keyuser_name=
aws_cost_by_service_monthlyservice, 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 タグが付いていないインスタンスを探すなら次のようになる。

SQL
select instance_id, title, region
from aws_ec2_instance
where not (tags ? 'Owner');

配列の列は、jsonb_array_elements で行に展開してから扱う。EC2 に付いているセキュリティグループを1行ずつ出す例だ。

SQL
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 のマネージドインスタンスの一覧を突き合わせればよい。

SQL:SSM に登録されていない、動いている EC2
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/ の下)。

~/.steampipe/config/default.spc(例)
options "database" {
  cache         = true
  cache_max_ttl = 900   # サーバー側の上限(秒)
}
~/.steampipe/config/workspaces.spc(例)
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 に出力する。

→ PART 04 — 実践:全リージョンのリソース棚卸しクエリへ