Introduction to Prepared Queries

Prepared Queries in Consul 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:

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/<QueryID>/execute

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:

{
  "Name": "web-app-v64",
  "Service": {
    "Service": "web-app",
    "Tags": ["v6.4"],
    "OnlyPassing": true
  }
}

Register it:

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:

GET /v1/query/<QueryID>/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

Static Failover Policy

{
  "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

{
  "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

{
  "Name": "web-app-v64",
  "Service": {
    "Service": "web-app",
    "Tags": ["v6.4"],
    "OnlyPassing": true,
    "Failover": {
      "NearestN": 2,
      "Datacenters": ["dc2", "dc3"]
    }
  }
}

Comparing Service Discovery Methods

Consul supports three main ways to locate services:

References

• Consul Prepared Queries
• Consul HTTP API
• Service Discovery Concepts