Skip to main content
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.
The image is a slide titled "Introduction to Prepared Query," explaining the benefits and creation of complex service queries, with a pixelated design on the right side.

​
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
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.
The image is an illustration titled "Introduction to Prepared Query," showing a person saying "I need to connect to a service" with a service catalog containing various web apps and services.
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.
The image illustrates a failover policy example involving cloud services like Azure and AWS, with various software icons and a character representing a user. It includes a diagram showing connections between different components and services.

​
Failover Policy Types

Policy TypeBehaviorKey Configuration
StaticTry a fixed list of datacenters in orderDatacenters
DynamicAutomatically select the nearest N datacenters by round-trip timeNearestN
HybridFirst nearest N, then fallback to a static listNearestN, Datacenters
The image describes different types of failover policies: Static, Dynamic, and Hybrid, each with specific configurations for handling service failovers. It also notes that failover policies prioritize returning a local service before using a federated data center.

​
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"]
    }
  }
}
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:
MethodAdvantagesLimitations
DNSBuilt-in, simple round-robinNo health or metadata filtering
Prepared QueriesFilter by tags, health, metadataLocal datacenter only
Prepared Queries with FailoverAll prepared query benefits + cross-DC failoverRequires federated topology configuration
The image compares options for querying services, highlighting DNS as simple but not flexible, Prepared Query as dynamic but local, and Failover Policy as ideal for multi-cloud apps. It features colorful arrows and a pixelated design at the bottom.

​
References

Watch Video