terraform/website/source/docs/providers/consul/r/prepared_query.markdown

---
layout: "consul"
page_title: "Consul: consul_prepared_query"
sidebar_current: "docs-consul-resource-prepared-query"
description: |-
  Allows Terraform to manage a Consul prepared query
---

# consul\_prepared\_query

Allows Terraform to manage a Consul prepared query.

Managing prepared queries is done using Consul's REST API. This resource is
useful to provide a consistent and declarative way of managing prepared
queries in your Consul cluster using Terraform.

## Example Usage

```
resource "consul_prepared_query" "service-near-self" {
    datacenter = "nyc1"
    token = "abcd"
    stored_token = "wxyz"
    name = ""
    only_passing = true
    near = "_agent"

    template {
        type = "name_prefix_match"
        regexp = "^(.*)-near-self$"
    }

    service = "$${match(1)}"

    failover {
        nearest_n = 3
        datacenters = ["dc2", "dc3", "dc4"]
    }

    dns {
        ttl = "5m"
    }

}
```

## Argument Reference

The following arguments are supported:

* `datacenter` - (Optional) The datacenter to use. This overrides the
  datacenter in the provider setup and the agent's default datacenter.

* `token` - (Optional) The ACL token to use when saving the prepared query.
  This overrides the token that the agent provides by default.

* `stored_token` - (Optional) The ACL token to store with the prepared
  query. This token will be used by default whenever the query is executed.

* `name` - (Required) The name of the prepared query. Used to identify
  the prepared query during requests. Can be specified as an empty string
  to configure the query as a catch-all.

* `service` - (Required) The name of the service to query.

* `only_passing` - (Optional) When `true`, the prepared query will only
  return nodes with passing health checks in the result.

* `near` - (Optional) Allows specifying the name of a node to sort results
  near using Consul's distance sorting and network coordinates. The magic
  `_agent` value can be used to always sort nearest the node servicing the
  request.

* `failover` - (Optional) Options for controlling behavior when no healthy
  nodes are available in the local DC.

  * `nearest_n` - (Optional) Return results from this many datacenters,
    sorted in ascending order of estimated RTT.

  * `datacenters` - (Optional) Remote datacenters to return results from.

* `dns` - (Optional) Settings for controlling the DNS response details.

  * `ttl` - (Optional) The TTL to send when returning DNS results.

* `template` - (Optional) Query templating options. This is used to make a
  single prepared query respond to many different requests.

  * `type` - (Required) The type of template matching to perform. Currently
    only `name_prefix_match` is supported.

  * `regexp` - (Required) The regular expression to match with. When using
    `name_prefix_match`, this regex is applied against the query name.

## Attributes Reference

The following attributes are exported:

* `id` - The ID of the prepared query, generated by Consul.