前回のAWS CLI S3コマンドの時刻表示の違いとJST変換に続き、今回はqueryオプションの使い方について書こうと思います。

queryオプションを使いこなせると、欲しい情報だけをピンポイントで取得できて作業効率が格段に上がります。

■ –queryオプションとは

AWS CLIの–queryオプションは、JMESPathという構文を使ってJSON形式の出力結果をフィルタリング・整形できる機能です。
s3api list-objects-v2などのコマンドで取得した大量のデータから、必要な情報だけを抽出できます。

■ JMESPathとは

JMESPath（ジェームズパス）は、JSON データを検索・操作するためのクエリ言語です。
AWS CLIだけでなく、他のツールやプログラミング言語でも使われています。

【特徴】
・JSON構造を直感的に操作できる
・フィルタリング、射影（必要なフィールドの抽出）、関数など豊富な機能
・複雑なデータ構造から簡単に必要な情報を取り出せる

公式サイト: https://jmespath.org/
※ オンラインで構文を試せるプレイグラウンドもあります

■ 基本的な使い方

▼ 配列の全要素を取得
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[*].Key”

[*] は配列の全要素を指します。

▼ 特定のフィールドだけ取得
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[].[Key,Size]” –output text

[] を使うと配列として展開され、[Key,Size] で複数フィールドを取得できます。

■ フィルタリング（条件指定）

【文字列が含まれているか】
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[?contains(Key, ‘log’)].[Key]” –output text

特定の文字列（この例では’log’）が含まれるKeyだけを抽出します。
ログファイルや特定のファイル名パターンを探す時に便利です。

【文字列で始まる・終わる】
# 特定の文字列で始まる
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[?starts_with(Key, ‘data-‘)].[Key]” –output text

# 特定の拡張子で終わる
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[?ends_with(Key, ‘.csv’)].[Key]” –output text

拡張子でフィルタリングする場合は ends_with が便利です。

【サイズで絞り込み】
# 1MB（1048576バイト）以上のファイル
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[?Size >= \`1048576\`].[Key,Size]” –output text

※ 数値を比較する場合は、バッククォート ` で囲む必要があります（リテラル表現）

【日付で絞り込み】
# 特定日時以降に更新されたファイル
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[?LastModified >= ‘2025-10-17T00:00:00+00:00’].[Key,LastModified]” –output text

■ 複数条件を組み合わせる

【AND条件（&&）】
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[?contains(Key, ‘log’) && Size >= \`1048576\`].[Key,Size]” –output text

「log」という文字列を含み、かつ1MB以上のファイルを抽出します。

【OR条件（||）】
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[?contains(Key, ‘error’) || contains(Key, ‘warning’)].[Key]” –output text

「error」または「warning」という文字列を含むファイルを抽出します。
エラーログを探す時に便利です。

【複雑な条件の組み合わせ】
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[?ends_with(Key, ‘.log’) && Size >= \`1048576\` && contains(Key, ‘2025-10’)].[Key,Size]” –output text

拡張子が.logで、1MB以上、かつKeyに’2025-10’を含むファイルを抽出します。

■ 整形・加工

【カスタムフォーマットで出力】
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “Contents[].{ファイル名:Key, サイズ:Size, 更新日時:LastModified}” –output table

{} を使うことで、カスタムキー名を付けて出力できます（マルチセレクトハッシュ）。
–output table と組み合わせると見やすい表形式になります。

【ソートして出力】
aws s3api list-objects-v2 –bucket bucket –prefix path/ –query “reverse(sort_by(Contents, &Size))[:10].[Key,Size]” –output text

sort_by でサイズ順にソート、reverse で降順、[:10] で上位10件を取得します（スライス）。※全件の場合は[]で取得できます
大きいファイルを探す時に便利です。

※ & はExpression（式）を表し、sort_byに渡すフィールドを指定します

■ 実用例

【例1: 特定日付のCSVファイルだけ抽出】
aws s3api list-objects-v2 –bucket bucket –prefix data/ –query “Contents[?contains(Key, ‘2025-10-17’) && ends_with(Key, ‘.csv’)].[Key]” –output text

【例3: エラーまたは警告を含むファイルをサイズ順で取得】
aws s3api list-objects-v2 –bucket bucket –prefix logs/ –query “reverse(sort_by(Contents[?contains(Key, ‘error’) || contains(Key, ‘warning’)], &Size))[].[Key,Size]” –output table

■ よく使うパターン集

# 拡張子でフィルタ
–query “Contents[?ends_with(Key, ‘.json’)].[Key]”

# ファイル名に日付を含む
–query “Contents[?contains(Key, ‘2025-10’)].[Key]”

# サイズが0バイトのファイルを除外
–query “Contents[?Size > \`0\`].[Key,Size]”

# 最新の10件を取得
–query “reverse(sort_by(Contents, &LastModified))[:10].[Key,LastModified]”

■ まとめ

・–queryオプションはJMESPathという構文を使用
・JMESPathはJSON操作のためのクエリ言語で、公式サイト（https://jmespath.org/）で詳細を確認できる
・contains, starts_with, ends_with で文字列フィルタリング
・&&（AND）、||（OR）で複数条件を組み合わせ
・数値比較する場合はバッククォート ` で囲む
・sort_by, reverse を使ってソート可能
・{}（マルチセレクトハッシュ）でカスタムフォーマット
・–output table と組み合わせると見やすい

–queryオプションを使いこなせると、シェルスクリプトでの複雑な処理が不要になり、ワンライナーで完結できることが増えます。
今回はここまで。