The use of the "filter" in data sources

REF: Data Sources - Configuration Language | Terraform by HashiCorp

there are 2 examples given:

data "aws_ami" "example" {
  most_recent = true

  owners = ["self"]
  tags = {
    Name   = "app-server"
    Tested = "true"


# Find the latest available AMI that is tagged with Component = web
data "aws_ami" "web" {
  filter {
    name   = "state"
    values = ["available"]

  filter {
    name   = "tag:Component"
    values = ["web"]

  most_recent = true

What is the difference between these examples?
When do I need/want to use “filter”?

The filter attribute allows scoping the returned data specific enough.

If more or less than a single match is returned by the search, Terraform will fail. Ensure that your search is specific enough to return a single AMI ID only, or use most_recent to choose the most recent one. If you want to match multiple AMIs, use the aws_ami_ids data source instead.

It’s very much possible that you get multiple results if your query is not specific enough, and you may not be able to get the right AMI ID you wanted to query. So you likely want to use the filter attribute to narrow it down, not just by a single Tag key:value pair.

The full list of the available filter options are here:

1 Like

I think your main question here is why the are two different ways to filter by tag, and by some other properties.

These data sources are mostly just reflecting the design of the underlying AWS APIs, which themselves have a mixture of specific search properties and a more generalized idea of “filters”. In some cases, the underlying API itself provides two ways to express the same thing, while in other cases the AWS provider offers an additional property primarily to make the expected argument type match better with the arguments and attributes of other resource types in the AWS provider.

However, one key difference for tags is that using the tags argument only allows an exact match of a single tag value, while filters allow you to match any of one or more options, and also tend to allow wildcards so that you can e.g. match by a value prefix.

On the server side, filters get applied only after the API has fetched all possible data matching the non-filter arguments, and so sometimes using non-filter arguments can be a bit faster if you have a lot of objects that would be returned in the absence of a filter, but I don’t expect that to make a big difference in most cases and so I mention it only for completeness.

1 Like

Thank you for explanation @apparentlymart . Now the usage makes sense.
I’ll not that “filter” is the way to go as more flexible approach.