# Filtering output in the AWS CLI
<a name="cli-usage-filter"></a>

AWS Command Line Interface (AWS CLI) には、サーバー側とクライアント側の両方のフィルタリングがあり、AWS CLI 出力をフィルタリングするために個別または一緒に使用することができます。サーバー側のフィルタリングが最初に処理され、クライアント側のフィルタリングのために出力が返されます。
+ サーバー側のフィルタリングは API によってサポートされており、通常は `--filter` パラメータを使用して実装します。このサービスは一致する結果のみを返し、大きなデータセットの HTTP レスポンス時間を短縮できます。
+ クライアント側のフィルタリングは、AWS CLI パラメータを使用して `--query` クライアントによってサポートされます。このパラメータには、サーバー側のフィルタリングにはない可能性がある機能があります。

**Topics**
+ [

## サーバー側のフィルタリング
](#cli-usage-filter-server-side)
+ [

## クライアント側のフィルタリング
](#cli-usage-filter-client-side)
+ [

## サーバー側とクライアント側のフィルタリングを組み合わせる
](#cli-usage-filter-combining)
+ [

## その他のリソース
](#cli-usage-filter-resources)

## サーバー側のフィルタリング
<a name="cli-usage-filter-server-side"></a>

AWS CLI でのサーバー側のフィルタリングは、AWS サービス API によって提供されます。AWS サービスは、フィルターに一致する HTTP レスポンス内のレコードのみを返します。これにより、大規模なデータセットの HTTP レスポンス時間が短縮されます。サーバー側のフィルタリングはサービス API によって定義されるため、パラメータ名と関数はサービスによって異なります。フィルタリングに使用される一般的なパラメータ名は次のとおりです。
+ `--filter` ( [ses](https://docs.aws.amazon.com/cli/latest/reference/ses/create-receipt-filter.html)、 [ce](https://docs.aws.amazon.com/cli/latest/reference/ce/get-cost-and-usage.html)など)。
+ `--filters` ( [ec2](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-volumes.html)、 [autoscaling](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/describe-tags.html)、 [rds](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html) など)。
+ 単語「`filter`」で始まる名前 ([https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html) コマンドの `--filter-expression` など)。

特定のコマンドにサーバー側のフィルタリングとフィルタリングルールがあるかどうかについては、「[AWS CLI バージョン 2 リファレンスガイド](https://docs.aws.amazon.com/cli/latest/reference/index.html)」を参照してください。

## クライアント側のフィルタリング
<a name="cli-usage-filter-client-side"></a>

AWS CLI は、`--query` パラメータによって、組み込みの JSON ベースのクライアント側のフィルタリング機能を提供します。`--query` パラメータは、出力の内容とスタイルをカスタマイズするために使用できる強力なツールです。`--query` パラメータは、サーバーから返される HTTP レスポンスを受け取り、結果を表示する前にフィルタリングします。フィルタリングする前に HTTP レスポンス全体がクライアントに送信されるため、大規模なデータセットでは、クライアント側のフィルタリングはサーバー側のフィルタリングよりも遅くなる可能性があります。

クエリでは、[JMESPath 構文](https://jmespath.org/)を使用して、出力をフィルタリングするための式を作成します。JMESPath 構文については、*JMESPath ウェブサイト*の「[Tutorial](https://jmespath.org/tutorial.html)」をご参照ください。

**重要**  
指定する出力タイプによって、`--query` オプションの動作が変更されます。  
`--output text` を指定する場合、出力は `--query` フィルターが適用される*前に*ページ分割され、AWS CLI は出力の*各ページ*でクエリを 1 回実行します。このため、クエリには各ページで最初に一致する要素が含まれており、予期しない余分な出力が発生する可能性があります。出力をさらにフィルタリングするには、`head` や `tail` などの他のコマンドラインツールを使用できます。
`--output json`、 `--output yaml`、`--output yaml-stream` を指定する場合、単一のネイティブな構造として完全に処理されてから `--query` フィルターが適用されます。AWS CLI は構造全体に対してクエリを 1 回だけ実行し、フィルタリングされた結果を生成してから出力されます。

**Topics**
+ [

### 開始する前に
](#cli-usage-filter-client-side-output)
+ [

### 識別子
](#cli-usage-filter-client-side-identifiers)
+ [

### リストから選択する
](#cli-usage-filter-client-side-select-list)
+ [

### ネストされたデータをフィルタリングする
](#cli-usage-filter-client-side-nested)
+ [

### 結果をフラット化する
](#cli-usage-filter-client-side-specific-flattening)
+ [

### 特定の値をフィルタリングする
](#cli-usage-filter-client-side-specific-values)
+ [

### パイピング式
](#cli-usage-filter-client-side-pipe)
+ [

### 複数の識別子の値をフィルタリングする
](#cli-usage-filter-client-side-miltiselect-list)
+ [

### 識別子の値にラベルを追加する
](#cli-usage-filter-client-side-multiselect-hash)
+ [

### 関数
](#cli-usage-filter-client-side-functions)
+ [

### 高度な `--query` の例
](#cli-usage-filter-client-side-advanced)

### 開始する前に
<a name="cli-usage-filter-client-side-output"></a>

**注記**  
これらのフィルタ式の例は、基本的な Linux 系シェル用に記述されています。これらの例を使用する場合は、ターミナルシェルに正しい引用規則を使用してください。ターミナルが入力を解釈する方法によって、AWS CLI に送信される内容が大きく変わることがあります。ターミナルが一重引用符 `'`、二重引用符 `"`、またはバックティック ``` をどのように解釈するかによって、内容の読み取り方が変わることがあります。  
詳細については、「[Using quotation marks and literals with strings in the AWS CLI](cli-usage-parameters-quoting-strings.md)」を参照してください。

次の JSON 出力は、`--query` パラメータが生成できるものの例を示しています。出力は、個別の Amazon EC2 インスタンスにアタッチされた 3 つの Amazon EBS ボリュームについて説明しています。

#### 出力例
<a name="cli-usage-filter-client-side-output-example"></a>

```
$ aws ec2 describe-volumes
{
  "Volumes": [
    {
      "AvailabilityZone": "us-west-2a",
      "Attachments": [
        {
          "AttachTime": "2013-09-17T00:55:03.000Z",
          "InstanceId": "i-a071c394",
          "VolumeId": "vol-e11a5288",
          "State": "attached",
          "DeleteOnTermination": true,
          "Device": "/dev/sda1"
        }
      ],
      "VolumeType": "standard",
      "VolumeId": "vol-e11a5288",
      "State": "in-use",
      "SnapshotId": "snap-f23ec1c8",
      "CreateTime": "2013-09-17T00:55:03.000Z",
      "Size": 30
    },
    {
      "AvailabilityZone": "us-west-2a",
      "Attachments": [
        {
          "AttachTime": "2013-09-18T20:26:16.000Z",
          "InstanceId": "i-4b41a37c",
          "VolumeId": "vol-2e410a47",
          "State": "attached",
          "DeleteOnTermination": true,
          "Device": "/dev/sda1"
        }
      ],
      "VolumeType": "standard",
      "VolumeId": "vol-2e410a47",
      "State": "in-use",
      "SnapshotId": "snap-708e8348",
      "CreateTime": "2013-09-18T20:26:15.000Z",
      "Size": 8
    },
    {
      "AvailabilityZone": "us-west-2a",
      "Attachments": [
        {
          "AttachTime": "2020-11-20T19:54:06.000Z",
          "InstanceId": "i-1jd73kv8",
          "VolumeId": "vol-a1b3c7nd",
          "State": "attached",
          "DeleteOnTermination": true,
          "Device": "/dev/sda1"
        }
      ],
      "VolumeType": "standard",
      "VolumeId": "vol-a1b3c7nd",
      "State": "in-use",
      "SnapshotId": "snap-234087fb",
      "CreateTime": "2020-11-20T19:54:05.000Z",
      "Size": 15
    }
  ]
}
```

### 識別子
<a name="cli-usage-filter-client-side-identifiers"></a>

識別子は、出力値のラベルです。フィルターを作成するときは、識別子を使用してクエリ結果を絞り込みます。次の出力例では、`Volumes`、`AvailabilityZone`、`AttachTime` などのすべての識別子が強調表示されます。

```
$ aws ec2 describe-volumes
{
  "Volumes": [
    {
      "AvailabilityZone": "us-west-2a",
      "Attachments": [
        {
          "AttachTime": "2013-09-17T00:55:03.000Z",
          "InstanceId": "i-a071c394",
          "VolumeId": "vol-e11a5288",
          "State": "attached",
          "DeleteOnTermination": true,
          "Device": "/dev/sda1"
        }
      ],
      "VolumeType": "standard",
      "VolumeId": "vol-e11a5288",
      "State": "in-use",
      "SnapshotId": "snap-f23ec1c8",
      "CreateTime": "2013-09-17T00:55:03.000Z",
      "Size": 30
    },
    {
      "AvailabilityZone": "us-west-2a",
      "Attachments": [
        {
          "AttachTime": "2013-09-18T20:26:16.000Z",
          "InstanceId": "i-4b41a37c",
          "VolumeId": "vol-2e410a47",
          "State": "attached",
          "DeleteOnTermination": true,
          "Device": "/dev/sda1"
        }
      ],
      "VolumeType": "standard",
      "VolumeId": "vol-2e410a47",
      "State": "in-use",
      "SnapshotId": "snap-708e8348",
      "CreateTime": "2013-09-18T20:26:15.000Z",
      "Size": 8
    },
    {
      "AvailabilityZone": "us-west-2a",
      "Attachments": [
        {
          "AttachTime": "2020-11-20T19:54:06.000Z",
          "InstanceId": "i-1jd73kv8",
          "VolumeId": "vol-a1b3c7nd",
          "State": "attached",
          "DeleteOnTermination": true,
          "Device": "/dev/sda1"
        }
      ],
      "VolumeType": "standard",
      "VolumeId": "vol-a1b3c7nd",
      "State": "in-use",
      "SnapshotId": "snap-234087fb",
      "CreateTime": "2020-11-20T19:54:05.000Z",
      "Size": 15
    }
  ]
}
```

詳細については、*JMESPath ウェブサイト*の「[Identifiers](https://jmespath.org/specification.html#identifiers )」をご参照ください。

### リストから選択する
<a name="cli-usage-filter-client-side-select-list"></a>

リストまたは配列は、`[` における `Volumes` や `Attachments` などの角括弧「[開始する前に](#cli-usage-filter-client-side-output)」の後に続く識別子です。

**構文**

```
<listName>[ ]
```

配列からのすべての出力をフィルタリングするには、ワイルドカード表記を使用できます。[ワイルドカード](http://jmespath.org/specification.html#wildcard-expressions)式は、`*` 表記法を使用して要素を返すために使用される式です。

次の例では、すべての `Volumes` コンテンツに対するクエリを実行します。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*]'
[
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2013-09-17T00:55:03.000Z",
        "InstanceId": "i-a071c394",
        "VolumeId": "vol-e11a5288",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-e11a5288",
    "State": "in-use",
    "SnapshotId": "snap-f23ec1c8",
    "CreateTime": "2013-09-17T00:55:03.000Z",
    "Size": 30
  },
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2020-11-20T19:54:06.000Z",
        "InstanceId": "i-1jd73kv8",
        "VolumeId": "vol-a1b3c7nd",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-a1b3c7nd",
    "State": "in-use",
    "SnapshotId": "snap-234087fb",
    "CreateTime": "2020-11-20T19:54:05.000Z",
    "Size": 15
  }
]
```

配列内の特定のボリュームをインデックス別に表示するには、配列インデックスを呼び出します。例えば、`Volumes` 配列の最初の項目のインデックスは 0 で、`Volumes[0]` クエリが生成されます。配列インデックスの詳細については、*JMESPath ウェブサイト*の「[index expressions](http://jmespath.org/specification.html#index-expressions)」をご参照ください。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[0]'
{
  "AvailabilityZone": "us-west-2a",
  "Attachments": [
    {
      "AttachTime": "2013-09-17T00:55:03.000Z",
      "InstanceId": "i-a071c394",
      "VolumeId": "vol-e11a5288",
      "State": "attached",
      "DeleteOnTermination": true,
      "Device": "/dev/sda1"
    }
  ],
  "VolumeType": "standard",
  "VolumeId": "vol-e11a5288",
  "State": "in-use",
  "SnapshotId": "snap-f23ec1c8",
  "CreateTime": "2013-09-17T00:55:03.000Z",
  "Size": 30
}
```

ボリュームの特定範囲をインデックス別に表示するには、次の構文とともに `slice` を使用します。ここで、**start** は開始配列インデックス、**stop** はフィルターが処理を停止するインデックス、**step** はスキップ間隔です。

**構文**

```
<arrayName>[<start>:<stop>:<step>]
```

スライス式からこれらのいずれかを省略すると、次のデフォルト値が使用されます。
+ Start - リストの最初のインデックス、0。
+ Stop - リストの最後のインデックス。
+ Step - ステップスキップなし。値は 1 です。

最初の 2 つのボリュームだけを返すには、次の例に示すように、start 値 0、stop 値 2、step 値 1 を使用します。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[0:2:1]'
[
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2013-09-17T00:55:03.000Z",
        "InstanceId": "i-a071c394",
        "VolumeId": "vol-e11a5288",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-e11a5288",
    "State": "in-use",
    "SnapshotId": "snap-f23ec1c8",
    "CreateTime": "2013-09-17T00:55:03.000Z",
    "Size": 30
  },
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2013-09-18T20:26:16.000Z",
        "InstanceId": "i-4b41a37c",
        "VolumeId": "vol-2e410a47",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-2e410a47",
    "State": "in-use",
    "SnapshotId": "snap-708e8348",
    "CreateTime": "2013-09-18T20:26:15.000Z",
    "Size": 8
  }
]
```

この例にはデフォルト値が含まれているため、スライスを `Volumes[0:2:1]` から `Volumes[:2]` に短縮できます。

次の例では、デフォルト値を省略し、配列全体におけるあらゆる 2 つのボリュームを返します。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[::2]'
[
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2013-09-17T00:55:03.000Z",
        "InstanceId": "i-a071c394",
        "VolumeId": "vol-e11a5288",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-e11a5288",
    "State": "in-use",
    "SnapshotId": "snap-f23ec1c8",
    "CreateTime": "2013-09-17T00:55:03.000Z",
    "Size": 30
  },
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2020-11-20T19:54:06.000Z",
        "InstanceId": "i-1jd73kv8",
        "VolumeId": "vol-a1b3c7nd",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-a1b3c7nd",
    "State": "in-use",
    "SnapshotId": "snap-234087fb",
    "CreateTime": "2020-11-20T19:54:05.000Z",
    "Size": 15
  }
]
```

次の例に示すように、step には、配列の逆の順序でフィルタリングするために負の数を使用することもできます。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[::-2]'
[
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2020-11-20T19:54:06.000Z",
        "InstanceId": "i-1jd73kv8",
        "VolumeId": "vol-a1b3c7nd",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-a1b3c7nd",
    "State": "in-use",
    "SnapshotId": "snap-234087fb",
    "CreateTime": "2020-11-20T19:54:05.000Z",
    "Size": 15
  },
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2013-09-17T00:55:03.000Z",
        "InstanceId": "i-a071c394",
        "VolumeId": "vol-e11a5288",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-e11a5288",
    "State": "in-use",
    "SnapshotId": "snap-f23ec1c8",
    "CreateTime": "2013-09-17T00:55:03.000Z",
    "Size": 30
  }
]
```

詳細については、*JMESPath ウェブサイト*の「[Slices](https://jmespath.org/specification.html#slices)」をご参照ください。

### ネストされたデータをフィルタリングする
<a name="cli-usage-filter-client-side-nested"></a>

ネストされた値の `Volumes[*]` のフィルタリング結果を絞り込むには、ピリオドとフィルター条件を追加して部分式を使用します。

**構文**

```
<expression>.<expression>
```

次の例は、すべてのボリュームのすべての `Attachments` 情報を示しています。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Attachments'
[
  [
    {
      "AttachTime": "2013-09-17T00:55:03.000Z",
      "InstanceId": "i-a071c394",
      "VolumeId": "vol-e11a5288",
      "State": "attached",
      "DeleteOnTermination": true,
      "Device": "/dev/sda1"
    }
  ],
  [
    {
      "AttachTime": "2013-09-18T20:26:16.000Z",
      "InstanceId": "i-4b41a37c",
      "VolumeId": "vol-2e410a47",
      "State": "attached",
      "DeleteOnTermination": true,
      "Device": "/dev/sda1"
    }
  ],
  [
    {
      "AttachTime": "2020-11-20T19:54:06.000Z",
      "InstanceId": "i-1jd73kv8",
      "VolumeId": "vol-a1b3c7nd",
      "State": "attached",
      "DeleteOnTermination": true,
      "Device": "/dev/sda1"
    }
  ]
]
```

ネストされた値までさらに絞り込むには、ネストされた各識別子の式を追加します。次の例では、すべての `State` の `Volumes` をリストします。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Attachments[*].State'
[
  [
    "attached"
  ],
  [
    "attached"
  ],
  [
    "attached"
  ]
]
```

### 結果をフラット化する
<a name="cli-usage-filter-client-side-specific-flattening"></a>

詳細については、*JMESPath ウェブサイト*の「[SubExpressions](https://jmespath.org/specification.html#subexpressions)」をご参照ください。

`Volumes[*].Attachments[*].State` クエリの結果として生成されたワイルドカード表記を削除することで、`Volumes[*].Attachments[].State` の結果をフラット化することができます。フラット化は、多くの場合、結果の可読性を向上させるのに役立ちます。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Attachments[].State'
[
  "attached",
  "attached",
  "attached"
]
```

詳細については、*JMESPath ウェブサイト*の「[Flatten](https://jmespath.org/specification.html#flatten)」をご参照ください。

### 特定の値をフィルタリングする
<a name="cli-usage-filter-client-side-specific-values"></a>

リスト内の特定の値をフィルタリングするには、次の構文に示すように、フィルター式を使用します。

**構文**

```
? <expression> <comparator> <expression>]
```

式の比較演算子には、`==`、`!=`、`<`、`<=`、`>`、`>=` などがあります。次の例では、`VolumeIds` `Volumes` のすべての `Attached` の `State` をフィルタリングします。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Attachments[?State==`attached`].VolumeId'
[
  [
    "vol-e11a5288"
  ],
  [
    "vol-2e410a47"
  ],
  [
    "vol-a1b3c7nd"
  ]
]
```

その後、これをフラット化することができ、次の例になります。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Attachments[?State==`attached`].VolumeId[]'
[
  "vol-e11a5288",
  "vol-2e410a47",
  "vol-a1b3c7nd"
]
```

次の例では、サイズが 20 未満のすべての `VolumeIds` の `Volumes` をフィルタリングします。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[?Size < `20`].VolumeId'
[
  "vol-2e410a47",
  "vol-a1b3c7nd"
]
```

詳細については、*JMESPath ウェブサイト*の「[Filter Expressions](https://jmespath.org/specification.html#filterexpressions)」をご参照ください。

### パイピング式
<a name="cli-usage-filter-client-side-pipe"></a>

フィルターの結果を新しいリストにパイプ処理し、次の構文を使用して別の式で結果をフィルタリングできます。

**構文**

```
<expression> | <expression>] 
```

次の例では、`Volumes[*].Attachments[].InstanceId` 式のフィルタリング結果を取得し、配列の最初の結果を出力します。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Attachments[].InstanceId | [0]'
"i-a071c394"
```

この例では、最初に次の式から配列を作成することによってこれを行います。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Attachments[].InstanceId'
"i-a071c394",
  "i-4b41a37c",
  "i-1jd73kv8"
```

その後、その配列の最初の要素を返します。

```
"i-a071c394"
```

詳細については、*JMESPath ウェブサイト*の「[Pipe Expressions](https://jmespath.org/specification.html#pipe-expressions)」をご参照ください。

### 複数の識別子の値をフィルタリングする
<a name="cli-usage-filter-client-side-miltiselect-list"></a>

複数の識別子をフィルタリングするには、次の構文を使用して、複数選択リストを使用します。

**構文**

```
<listName>[].[<expression>, <expression>]
```

次の例では、`VolumeId` および `VolumeType` が `Volumes` リストでフィルタリングされ、次の式になります。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[].[VolumeId, VolumeType]'
[
  [
    "vol-e11a5288",
    "standard"
  ],
  [
    "vol-2e410a47",
    "standard"
  ],
  [
    "vol-a1b3c7nd",
    "standard"
  ]
]
```

ネストされたデータをリストに追加するには、別の複数選択リストを追加します。次の例では、ネストされた `InstanceId` リストの `State` および `Attachments` もフィルタリングすることによって、前の例を拡張します。これにより、式は次のようになります。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State]]'
[
  [
    "vol-e11a5288",
    "standard",
    [
      [
        "i-a071c394",
        "attached"
      ]
    ]
  ],
  [
    "vol-2e410a47",
    "standard",
    [
      [
        "i-4b41a37c",
        "attached"
      ]
    ]
  ],
  [
    "vol-a1b3c7nd",
    "standard",
    [
      [
        "i-1jd73kv8",
        "attached"
      ]
    ]
  ]
]
```

可読性を向上させるには、次の例に示すように、式をフラット化します。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State][]][]'
[
  "vol-e11a5288",
  "standard",
  [
    "i-a071c394",
    "attached"
  ],
  "vol-2e410a47",
  "standard",
  [
    "i-4b41a37c",
    "attached"
  ],
  "vol-a1b3c7nd",
  "standard",
  [
    "i-1jd73kv8",
    "attached"
  ]
]
```

詳細については、*JMESPath ウェブサイト*の「[Multiselect list](https://jmespath.org/specification.html#multiselectlist)」をご参照ください。

### 識別子の値にラベルを追加する
<a name="cli-usage-filter-client-side-multiselect-hash"></a>

この出力を読みやすくするには、次の構文で複数選択ハッシュを使用します。

**構文**

```
<listName>[].{<label>: <expression>, <label>: <expression>}
```

識別子のラベルは、識別子の名前と同じである必要はありません。次の例では、`VolumeType` 値のラベル `VolumeType` を使用します。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[].{VolumeType: VolumeType}'
[
  {
    "VolumeType": "standard",
  },
  {
    "VolumeType": "standard",
  },
  {
    "VolumeType": "standard",
  }
]
```

簡単にするために、以下の例では、各ラベルの識別子名を保持し、すべてのボリュームの `VolumeId`、`VolumeType`、`InstanceId`、および `State` を表示します。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[].{VolumeId: VolumeId, VolumeType: VolumeType, InstanceId: Attachments[0].InstanceId, State: Attachments[0].State}'
[
  {
    "VolumeId": "vol-e11a5288",
    "VolumeType": "standard",
    "InstanceId": "i-a071c394",
    "State": "attached"
  },
  {
    "VolumeId": "vol-2e410a47",
    "VolumeType": "standard",
    "InstanceId": "i-4b41a37c",
    "State": "attached"
  },
  {
    "VolumeId": "vol-a1b3c7nd",
    "VolumeType": "standard",
    "InstanceId": "i-1jd73kv8",
    "State": "attached"
  }
]
```

詳細については、*JMESPath ウェブサイト*の「[Multiselect hash](https://jmespath.org/specification.html#multiselecthash)」を参照してください。

### 関数
<a name="cli-usage-filter-client-side-functions"></a>

JMESPath 構文には、クエリに使用できる多くの関数が含まれています。JMESPath 関数の詳細については、*JMESPath ウェブサイト*の「[Built-in Functions](https://jmespath.org/specification.html#built-in-functions)」をご参照ください。

クエリに関数を組み込む方法を示すために、次の例では `sort_by` 関数を使用します。`sort_by` 関数は、次の構文を使用して、ソートキーとして式を使用して配列をソートします。

**構文**

```
sort_by(<listName>, <sort expression>)[].<expression>
```

次の例では、前述の[複数選択ハッシュの例](#cli-usage-filter-client-side-multiselect-hash)を使用して、出力を `VolumeId` でソートします。

```
$ aws ec2 describe-volumes \
    --query 'sort_by(Volumes, &VolumeId)[].{VolumeId: VolumeId, VolumeType: VolumeType, InstanceId: Attachments[0].InstanceId, State: Attachments[0].State}'
[
  {
    "VolumeId": "vol-2e410a47",
    "VolumeType": "standard",
    "InstanceId": "i-4b41a37c",
    "State": "attached"
  },
  {
    "VolumeId": "vol-a1b3c7nd",
    "VolumeType": "standard",
    "InstanceId": "i-1jd73kv8",
    "State": "attached"
  },
  {
    "VolumeId": "vol-e11a5288",
    "VolumeType": "standard",
    "InstanceId": "i-a071c394",
    "State": "attached"
  }
]
```

詳細については、*JMESPath ウェブサイト*の「[sort\$1by](https://jmespath.org/specification.html#sort-by)」をご参照ください。

### 高度な `--query` の例
<a name="cli-usage-filter-client-side-advanced"></a>

**特定のアイテムから情報を抽出するには**

次の例では、`--query` パラメータを使用してリスト上の特定の項目を検索し、その項目から情報を抽出します。この例では、指定されたサービスエンドポイントに関連付けられているすべての `AvailabilityZones` をリストします。指定された `ServiceDetails` が含まれる `ServiceName` リストから項目を抽出し、選択されたその項目から `AvailabilityZones` フィールドを出力します。

```
$ aws --region us-east-1 ec2 describe-vpc-endpoint-services \
    --query 'ServiceDetails[?ServiceName==`com.amazonaws.us-east-1.ecs`].AvailabilityZones'
[
    [
        "us-east-1a",
        "us-east-1b",
        "us-east-1c",
        "us-east-1d",
        "us-east-1e",
        "us-east-1f"
    ]
]
```

**指定した作成日より後のスナップショットを表示するには**

次の例は、指定された日付以降に作成されたすべてのスナップショットを一覧表示する方法を示しています (例: 出力の利用可能な一部のフィールド)。

```
$ aws ec2 describe-snapshots --owner self \
    --output json \
    --query 'Snapshots[?StartTime>=`2018-02-07`].{Id:SnapshotId,VId:VolumeId,Size:VolumeSize}'
[
    {
        "id": "snap-0effb42b7a1b2c3d4",
        "vid": "vol-0be9bb0bf12345678",
        "Size": 8
    }
]
```

**最新の AMI を表示するには**

次の例では、作成した最新の 5 つの Amazon マシンイメージ (AMI) を最新のものから古いものの順に並べ替えています。

```
$ aws ec2 describe-images \
    --owners self \
    --query 'reverse(sort_by(Images,&CreationDate))[:5].{id:ImageId,date:CreationDate}'
[
    {
        "id": "ami-0a1b2c3d4e5f60001",
        "date": "2018-11-28T17:16:38.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60002",
        "date": "2018-09-15T13:51:22.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60003",
        "date": "2018-08-19T10:22:45.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60004",
        "date": "2018-05-03T12:04:02.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60005",
        "date": "2017-12-13T17:16:38.000Z"
    }
]
```

**異常な Auto Scaling インスタンスを表示する方法**

次の例は、指定した Auto Scaling グループで異常のあるインスタンスのみの `InstanceId` を示しています。

```
$ aws autoscaling describe-auto-scaling-groups \
    --auto-scaling-group-name My-AutoScaling-Group-Name \
    --output text \
    --query 'AutoScalingGroups[*].Instances[?HealthStatus==`Unhealthy`].InstanceId'
```

**指定したタグを持つボリュームを含めるには**

次の例では、`test` タグを持つすべてのインスタンスを説明します。ボリュームにアタッチされた、`test` ではない別のタグがある限り、ボリュームは結果に含まれて返されます。

以下の式は、`test` タグを含むすべてのタグを配列に含めて返します。`test` タグでないタグには `null` 値が含まれています。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Tags[?Value == `test`]'
```

**指定したタグを持つボリュームを除外するには**

次の例では、`test` タグを持たないすべてのインスタンスを説明します。ボリュームは複数のタグを持つことができるため、シンプルな `?Value != `test`` 式を使用しても、ボリュームを除外することはできません。ボリュームにアタッチされた、`test` ではない別のタグがある限り、ボリュームは結果に含まれて返されます。

`test` タグを持つすべてのボリュームを除外するには、以下の式から開始して、`test` タグを含むすべてのタグを配列に含めて返します。`test` タグでないタグには `null` 値が含まれています。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Tags[?Value == `test`]'
```

その後、`test` 関数を使用してすべての肯定的な `not_null` の結果をフィルタリングで抽出します。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[?!not_null(Tags[?Value == `test`].Value)]'
```

結果をパイプ処理して、結果をフラット化すると、次のクエリになります。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[?!not_null(Tags[?Value == `test`].Value)] | []'
```

## サーバー側とクライアント側のフィルタリングを組み合わせる
<a name="cli-usage-filter-combining"></a>

サーバー側とクライアント側のフィルタリングを一緒に使用できます。サーバー側のフィルタリングが最初に完了し、得られたデータがクライアントに送信され、`--query` パラメータがそのデータをフィルタリングします。大規模なデータセットを使用している場合、サーバー側のフィルタリングを最初に使用すると、クライアント側のフィルタリングによって提供される強力なカスタマイズを維持しながら、各 AWS CLI 呼び出しについてクライアントに送信されるデータの量を減らすことができます。

次の例では、サーバー側とクライアント側の両方のフィルタリングを使用して Amazon EC2 ボリュームを一覧表示します。このサービスでは、`us-west-2a` アベイラビリティーゾーンでアタッチされたすべてのボリュームのリストがフィルタリングされます。`--query` パラメータでは、`Size` 値が 50 を超えるボリュームにのみ出力を制限し、ユーザー定義の名前を持つ指定されたフィールドのみ表示されます。

```
$ aws ec2 describe-volumes \
    --filters "Name=availability-zone,Values=us-west-2a" "Name=status,Values=attached" \
    --query 'Volumes[?Size > `50`].{Id:VolumeId,Size:Size,Type:VolumeType}'
[
    {
        "Id": "vol-0be9bb0bf12345678",
        "Size": 80,
        "VolumeType": "gp2"
    }
]
```

次の例では、いくつかの基準を満たすイメージのリストを取得します。`--query` パラメータを使用して、`CreationDate` で出力を絞り込み、最新のイメージのみ選択します。最後に、1 つのイメージの `ImageId` が表示されます。

```
$ aws ec2 describe-images \
    --owners amazon \
    --filters "Name=name,Values=amzn*gp2" "Name=virtualization-type,Values=hvm" "Name=root-device-type,Values=ebs" \
    --query "sort_by(Images, &CreationDate)[-1].ImageId" \
    --output text
ami-00ced3122871a4921
```

以下の例では、`length` を使用してリスト内の数をカウントすることで、1,000 IOPS を超える利用可能なボリュームの数を表示します。

```
$ aws ec2 describe-volumes \
    --filters "Name=status,Values=available" \
    --query 'length(Volumes[?Iops > `1000`])'
3
```

次の例では、指定した AWS リージョンにおいて、CloudFormation スタックを起動設定で使用している Auto Scaling グループの名前を取得します。

```
$ aws autoscaling describe-auto-scaling-groups --region us-west-2 \
  --filters Name=tag-key,Values=aws:cloudformation:stack-name \
  --query 'AutoScalingGroups[?LaunchConfigurationName!=`null`].AutoScalingGroupName'
[
    "group-1",
    "group-2",
    "group-3"
]
```

## その他のリソース
<a name="cli-usage-filter-resources"></a>

**AWS CLI 自動プロンプト**  
フィルター式の使用を開始するときは、AWS CLI バージョン 2 の自動プロンプト機能を使用できます。**F5** キーを押すと、自動プロンプト機能でプレビューが表示されます。詳細については、「[AWS CLI でのコマンドプロンプトの有効化と使用](cli-usage-parameters-prompting.md)」を参照してください。

**JMESPath ターミナル**  
JMESPath ターミナルは、クライアント側のフィルタリングに使用される JMESPath 式を実験するインタラクティブなターミナルコマンドです。`jpterm` コマンドを使用すると、ターミナルに入力すると即時にクエリ結果が表示されます。AWS CLI 出力をターミナルに直接パイプすることができ、これにより、高度なクエリ実験が可能となります。  
次の例では、JMESPath ターミナルに `aws ec2 describe-volumes` 出力を直接パイプします。  

```
$ aws ec2 describe-volumes | jpterm
```
JMESPath ターミナルとインストール手順の詳細については、*GitHub* の「[JMESPath Terminal](https://github.com/jmespath/jmespath.terminal)」をご参照ください。

**jq ユーティリティ**  
`jq` ユーティリティは、クライアント側の出力を必要な出力形式に変換する方法を提供します。`jq` およびインストール手順の詳細については、*GitHub* の「[jq](https://stedolan.github.io/jq/)」をご参照ください。