> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction to Prepared Queries
> Prepared Queries in Consul enable advanced service discovery by filtering instances based on various criteria for reusable query execution.
Prepared Queries in [Consul](https://www.consul.io/) enable advanced service discovery by filtering instances based on health status, version tags, datacenter location, and more. Unlike basic DNS lookups, prepared queries let you define reusable query objects at the datacenter level and execute them via HTTP or DNS.
## Defining and Executing a Prepared Query
Prepared Queries are stored in Consul’s catalog by calling the `/v1/query` API endpoint:
```bash theme={null}
curl --request PUT \
--data @my-query.json \
http://localhost:8500/v1/query
```
Once registered, a query named `my-query` is available as:
* **DNS**: `my-query.query.consul`
* **HTTP API**: `GET /v1/query//execute`
DNS queries to `*.query.consul` support standard A/AAAA record lookups and SRV records for service resolution.
## Filtering Services: A Dealership Analogy
Imagine you visit a car dealership with thousands of vehicles. You only want:
1. A car (not a truck)
2. Painted red
3. The latest model
By applying these filters, you narrow down the lot to your perfect match.
Similarly, a Consul client can request service instances and then filter by:
* **Health**: only passing health checks
* **Service**: e.g., `web-app`
* **Tags**: e.g., `v6.4`
### Example: `web-app-v64` Prepared Query
Save the following JSON to `web-app-v64-query.json`:
```json theme={null}
{
"Name": "web-app-v64",
"Service": {
"Service": "web-app",
"Tags": ["v6.4"],
"OnlyPassing": true
}
}
```
Register it:
```bash theme={null}
curl --request PUT \
--data @web-app-v64-query.json \
http://localhost:8500/v1/query
```
Now you can resolve `web-app-v64.query.consul` or call:
```bash theme={null}
GET /v1/query//execute
```
## Multi-Datacenter Failover Policies
In federated environments, you may want your queries to automatically fail over to other datacenters if no local instances are healthy.
### Failover Policy Types
| Policy Type | Behavior | Key Configuration |
| ----------- | ----------------------------------------------------------------- | ------------------------- |
| Static | Try a fixed list of datacenters in order | `Datacenters` |
| Dynamic | Automatically select the nearest N datacenters by round-trip time | `NearestN` |
| Hybrid | First nearest N, then fallback to a static list | `NearestN`, `Datacenters` |
#### Static Failover Policy
```json theme={null}
{
"Name": "web-app-v64",
"Service": {
"Service": "web-app",
"Tags": ["v6.4"],
"OnlyPassing": true,
"Failover": {
"Datacenters": ["dc2", "dc3"]
}
}
}
```
> Consul tries the local datacenter first, then `dc2`, then `dc3`.
#### Dynamic Failover Policy
```json theme={null}
{
"Name": "web-app-v64",
"Service": {
"Service": "web-app",
"Tags": ["v6.4"],
"OnlyPassing": true,
"Failover": {
"NearestN": 2
}
}
}
```
> Consul measures round-trip time and queries the two nearest datacenters if the local ones have no healthy instances.
#### Hybrid Failover Policy
```json theme={null}
{
"Name": "web-app-v64",
"Service": {
"Service": "web-app",
"Tags": ["v6.4"],
"OnlyPassing": true,
"Failover": {
"NearestN": 2,
"Datacenters": ["dc2", "dc3"]
}
}
}
```
In a hybrid policy, each datacenter is queried at most once per execution.
## Comparing Service Discovery Methods
Consul supports three main ways to locate services:
| Method | Advantages | Limitations |
| ------------------------------ | ----------------------------------------------- | ----------------------------------------- |
| DNS | Built-in, simple round-robin | No health or metadata filtering |
| Prepared Queries | Filter by tags, health, metadata | Local datacenter only |
| Prepared Queries with Failover | All prepared query benefits + cross-DC failover | Requires federated topology configuration |
## References
* [Consul Prepared Queries](https://www.consul.io/docs/discovery/prepared-queries)
* [Consul HTTP API](https://www.consul.io/api-docs)
* [Service Discovery Concepts](https://www.consul.io/docs/intro/concepts)