--- layout: api page_title: Prepared Queries - HTTP API description: The /query endpoints manage and execute prepared queries in Consul. --- # Prepared Query HTTP Endpoint The `/query` endpoints create, update, destroy, and execute prepared queries. Prepared queries allow you to register a complex service query and then execute it later via its ID or name to get a set of healthy nodes that provide a given service. This is particularly useful in combination with Consul's [DNS Interface](/docs/discovery/dns#prepared-query-lookups) as it allows for much richer queries than would be possible given the limited entry points exposed by DNS. Check the [Geo Failover tutorial](https://learn.hashicorp.com/tutorials/consul/automate-geo-failover) for details and examples for using prepared queries to implement geo failover for services. Check the [prepared query rules](/docs/security/acl/acl-rules#prepared-query-rules) section of the agent ACL documentation for more details about how prepared queries work with Consul's ACL system. ### Prepared Query Templates Consul 0.6.4 and later support prepared query templates. These are created similar to static queries, except with some additional fields and features. Here is an example prepared query template: ```json { "Template": { "Type": "name_prefix_match", "Regexp": "^geo-db-(.*?)-([^\\-]+?)$", "RemoveEmptyTags": false } } ``` The `Template` structure configures a prepared query as a template instead of a static query. It has two fields: - `Type` is the query type, which must be `name_prefix_match`. This means that the template will apply to any query lookup with a name whose prefix matches the `Name` field of the template. In this example, any query for `geo-db` will match this query. Query templates are resolved using a longest prefix match, so it's possible to have high-level templates that are overridden for specific services. Static queries are always resolved first, so they can also override templates. - `Regexp` is an optional regular expression which is used to extract fields from the entire name, once this template is selected. In this example, the regular expression takes the first item after the "-" as the database name and everything else after as a tag. See the [RE2](https://github.com/google/re2/wiki/Syntax) reference for syntax of this regular expression. - `RemoveEmptyTags` is optional, and if set to true, will cause the `Tags` list inside the `Service` structure to be stripped of any empty strings. This defaults to false, meaning that empty strings will remain in the list. This is useful when interpolating into tags in a way where the tag is optional, and where searching for an empty tag would yield no results from the query. All other fields of the query have the same meanings as for a static query, except that several interpolation variables are available to dynamically populate the query before it is executed. All of the string fields inside the `Service` structure are interpolated, with the following variables available: - `${name.full}` has the entire name that was queried. For example, a DNS lookup for `geo-db-customer-primary.query.consul` in the example above would set this variable to `geo-db-customer-primary`. - `${name.prefix}` has the prefix that matched. This would always be `geo-db` for the example above. - `${name.suffix}` has the suffix after the prefix. For example, a DNS lookup for `geo-db-customer-primary.query.consul` in the example above would set this variable to `-customer-primary`. - `${match(N)}` returns the regular expression match at the given index N. The 0 index will have the entire match, and >0 will have the results of each match group. For example, a DNS lookup for `geo-db-customer-primary.query.consul` in the example above with a `Regexp` field set to `^geo-db-(.*?)-([^\-]+?)$` would return `geo-db-customer-primary` for `${match(0)}`, `customer` for `${match(1)}`, and `primary` for `${match(2)}`. If the regular expression doesn't match, or an invalid index is given, then `${match(N)}` will return an empty string. - `${agent.segment}` - the network segment of the agent that initiated the query. This varaible can be used with the `NodeMeta` field to limit the results of a query to service instances within its own network segment: ```json { "Name": "", "Template": { "Type": "name_prefix_match" }, "Service": { "Service": "${name.full}", "NodeMeta": { "consul-network-segment": "${agent.segment}" } } } ``` This will map all names of the form `.query.consul` over DNS to a query that will select an instance of the service in the agent's own network segment. Using templates, it is possible to apply prepared query behaviors to many services with a single template. Here's an example template that matches any query and applies a failover policy to it: ```json { "Name": "", "Template": { "Type": "name_prefix_match" }, "Service": { "Service": "${name.full}", "Failover": { "NearestN": 3 } } } ``` This will match any lookup for `*.query.consul` and will attempt to find the service locally, and otherwise attempt to find that service in the next three closest datacenters. If ACLs are enabled, a catch-all template like this with an empty `Name` requires an ACL token that can write to any query prefix. Also, only a single catch-all template can be registered at any time. ## Create Prepared Query This endpoint creates a new prepared query and returns its ID if it is created successfully. | Method | Path | Produces | | ------ | -------- | ------------------ | | `POST` | `/query` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs/features/blocking), [consistency modes](/api-docs/features/consistency), [agent caching](/api-docs/features/caching), and [required ACLs](/api-docs#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | | `NO` | `none` | `none` | `query:write` | ### Query Parameters - `dc` `(string: "")` - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. ### JSON Request Body Schema - `Name` `(string: "")` - Specifies an optional friendly name that can be used to execute a query instead of using its ID. - `Session` `(string: "")` - Specifies the ID of an existing session. This provides a way to automatically remove a prepared query when the given session is invalidated. If not given the prepared query must be manually removed when no longer needed. - `Token` `(string: "")` - Specifies the ACL token to use each time the query is executed. This allows queries to be executed by clients with lesser or even no ACL Token, so this should be used with care. The token itself can only be seen by clients with a management token. If the `Token` field is left blank or omitted, the client's ACL Token will be used to determine if they have access to the service being queried. If the client does not supply an ACL Token, the anonymous token will be used. - `Service` `(Service: )` - Specifies the structure to define the query's behavior. - `Service` `(string: )` - Specifies the name of the service to query. - `Namespace` `(string: "")` - Specifies the Consul namespace to query. If not provided the query will use Consul default namespace for resolution. - `Failover` contains two fields, both of which are optional, and determine what happens if no healthy nodes are available in the local datacenter when the query is executed. It allows the use of nodes in other datacenters with very little configuration. - `NearestN` `(int: 0)` - Specifies that the query will be forwarded to up to `NearestN` other datacenters based on their estimated network round trip time using [Network Coordinates](/docs/architecture/coordinates) from the WAN gossip pool. The median round trip time from the server handling the query to the servers in the remote datacenter is used to determine the priority. - `Datacenters` `(array: nil)` - Specifies a fixed list of WAN federated datacenters to forward the query to when there are no healthy nodes in the local datacenter. Datacenters are queried in the order given in the list. If this option is combined with `NearestN`, then the `NearestN` queries will be performed first, followed by the list given by `Datacenters`. A given datacenter will only be queried one time during a failover, even if it is selected by both `NearestN` and is listed in `Datacenters`. Use `Targets` to failover to cluster peers. - `Targets` `(array: nil)` - Specifies a sequential list of remote datacenters and cluster peers to failover to if there are no healthy service instances in the local datacenter. This option cannot be used with `NearestN` or `Datacenters`. - `PeerName` `(string: "")` - Specifies a [cluster peer](/docs/connect/cluster-peering) to use for failover. - `Datacenter` `(string: "")` - Specifies a WAN federated datacenter to forward the query to. - `IgnoreCheckIDs` `(array: nil)` - Specifies a list of check IDs that should be ignored when filtering unhealthy instances. This is mostly useful in an emergency or as a temporary measure when a health check is found to be unreliable. Being able to ignore it in centrally-defined queries can be simpler than deregistering the check as an interim solution until the check can be fixed. - `OnlyPassing` `(bool: false)` - Specifies the behavior of the query's health check filtering. If this is set to false, the results will include nodes with checks in the passing as well as the warning states. If this is set to true, only nodes with checks in the passing state will be returned. - `Near` `(string: "")` - Specifies a node to sort near based on distance sorting using [Network Coordinates](/docs/architecture/coordinates). The nearest instance to the specified node will be returned first, and subsequent nodes in the response will be sorted in ascending order of estimated round-trip times. If the node given does not exist, the nodes in the response will be shuffled. If unspecified, the response will be shuffled by default. - `_agent` - Returns results nearest the agent servicing the request. - `_ip` - Returns results nearest to the node associated with the source IP where the query was executed from. For HTTP the source IP is the remote peer's IP address or the value of the X-Forwarded-For header with the header taking precedence. For DNS the source IP is the remote peer's IP address or the value of the EDNS client IP with the EDNS client IP taking precedence. * `Tags` `(array: nil)` - Specifies a list of service tags to filter the query results. For a service to pass the tag filter it must have _all_ of the required tags, and _none_ of the excluded tags (prefixed with `!`). * `NodeMeta` `(map: nil)` - Specifies a list of user-defined key/value pairs that will be used for filtering the query results to nodes with the given metadata values present. * `ServiceMeta` `(map: nil)` - Specifies a list of user-defined key/value pairs that will be used for filtering the query results to services with the given metadata values present. * `Connect` `(bool: false)` - If true, only [Connect-capable](/docs/connect) services for the specified service name will be returned. This includes both natively integrated services and proxies. For proxies, the proxy name may not match `Service`, because the proxy destination will. Any constrains beyond the service name such as `Near`, `Tags`, and `NodeMeta` are applied to Connect-capable service. * `DNS` `(DNS: nil)` - Specifies DNS configuration - `TTL` `(string: "")` - Specifies the TTL duration when query results are served over DNS. If this is specified, it will take precedence over any Consul agent-specific configuration. ### Sample Payload ```json { "Name": "my-query", "Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e", "Token": "", "Service": { "Service": "redis", "Failover": { "NearestN": 3, "Datacenters": ["dc1", "dc2"] }, "Near": "node1", "OnlyPassing": false, "Tags": ["primary", "!experimental"], "NodeMeta": { "instance_type": "m3.large" }, "ServiceMeta": { "environment": "production" } }, "DNS": { "TTL": "10s" } } ``` ### Sample Request ```shell-session $ curl \ --request POST \ --data @payload.json \ http://127.0.0.1:8500/v1/query ``` ### Sample Response ```json { "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05" } ``` ## List Prepared Queries This endpoint returns a list of all prepared queries. @include 'http_api_results_filtered_by_acls.mdx' | Method | Path | Produces | | ------ | -------- | ------------------ | | `GET` | `/query` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs/features/blocking), [consistency modes](/api-docs/features/consistency), [agent caching](/api-docs/features/caching), and [required ACLs](/api-docs#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `all` | `none` | `query:read` | ### Query Parameters - `dc` `(string: "")` - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. ### Sample Request ```shell-session $ curl \ http://127.0.0.1:8500/v1/query ``` ### Sample Response ```json [ { "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05", "Name": "my-query", "Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e", "Token": "", "Service": { "Service": "redis", "Failover": { "NearestN": 3, "Datacenters": ["dc1", "dc2"] }, "OnlyPassing": false, "Tags": ["primary", "!experimental"], "NodeMeta": { "instance_type": "m3.large" }, "ServiceMeta": { "environment": "production" } }, "DNS": { "TTL": "10s" }, "RaftIndex": { "CreateIndex": 23, "ModifyIndex": 42 } } ] ``` ### Update Prepared Query This endpoint updates an existing prepared query. If no query exists by the given ID, an error is returned. | Method | Path | Produces | | ------ | -------------- | ------------------ | | `PUT` | `/query/:uuid` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs/features/blocking), [consistency modes](/api-docs/features/consistency), [agent caching](/api-docs/features/caching), and [required ACLs](/api-docs#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | | `NO` | `none` | `none` | `query:write` | ### Path Parameters - `uuid` `(string: )` - Specifies the UUID of the query to update. ### Query Parameters - `dc` `(string: "")` - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. The body is the same as is used to create a prepared query. Please see above for more information. ### Sample Request ```shell-session $ curl \ --request PUT \ --data @payload.json \ http://127.0.0.1:8500/v1/query/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 ``` ## Read Prepared Query This endpoint reads an existing prepared query. If no query exists by the given ID, an error is returned. | Method | Path | Produces | | ------ | -------------- | ------------------ | | `GET` | `/query/:uuid` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs/features/blocking), [consistency modes](/api-docs/features/consistency), [agent caching](/api-docs/features/caching), and [required ACLs](/api-docs#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `all` | `none` | `query:read` | ### Path Parameters - `uuid` `(string: )` - Specifies the UUID of the query to read. ### Query Parameters - `dc` `(string: "")` - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. ### Sample Request ```shell-session $ curl \ http://127.0.0.1:8500/v1/query/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 ``` ### Sample Response The returned response is the same as the list of prepared queries above, only with a single item present. ## Delete Prepared Query This endpoint deletes an existing prepared query. If no query exists by the given ID, an error is returned. | Method | Path | Produces | | -------- | -------------- | ------------------ | | `DELETE` | `/query/:uuid` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs/features/blocking), [consistency modes](/api-docs/features/consistency), [agent caching](/api-docs/features/caching), and [required ACLs](/api-docs#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | | `NO` | `none` | `none` | `query:write` | ### Path Parameters - `uuid` `(string: )` - Specifies the UUID of the query to delete. ### Query Parameters - `dc` `(string: "")` - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. ### Sample Request ```shell-session $ curl \ --request DELETE \ http://127.0.0.1:8500/v1/query/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 ``` ## Execute Prepared Query This endpoint executes an existing prepared query. If no query exists by the given ID, an error is returned. The HTTP response includes the `X-Consul-Results-Filtered-By-ACLs: true` header if the [`Nodes`](#nodes) response array excludes results due to ACL policy configuration. Refer to the [HTTP API documentation](/api-docs#results-filtered-by-acls) for more information. | Method | Path | Produces | | ------ | ---------------------- | ------------------ | | `GET` | `/query/:uuid/execute` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs/features/blocking), [consistency modes](/api-docs/features/consistency), [agent caching](/api-docs/features/caching), and [required ACLs](/api-docs#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------------- | | `NO` | `all` | `simple` | `depends`1 | 1 If an ACL Token was bound to the query when it was defined then it will be used when executing the request. Otherwise, the client's supplied ACL Token will be used. ### Path Parameters - `uuid` `(string: )` - Specifies the UUID of the query to execute. This parameter can also be the name of an existing prepared query, or a name that matches a prefix name for a prepared query template. ### Query Parameters - `dc` `(string: "")` - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. - `near` `(string: "")` - Specifies to sort the resulting list in ascending order based on the estimated round trip time from that node. Passing `?near=_agent` will use the agent's node for the sort. Passing `?near=_ip` will use the source IP of the request or the value of the X-Forwarded-For header to lookup the node to use for the sort. If this is not present, the default behavior will shuffle the nodes randomly each time the query is executed. - `limit` `(int: 0)` - Limit the size of the list to the given number of nodes. This is applied after any sorting or shuffling. - `connect` `(bool: false)` - If true, limit results to nodes that are Connect-capable only. This parameter can also be specified directly on the template itself to force all executions of a query to be Connect-only. See the template documentation for more information. ### Sample Request ```shell-session $ curl \ http://127.0.0.1:8500/v1/query/8f246b77-f3e1-ff88-5b48-8ec93abf3e05/execute?near=_agent ``` ### Sample Response ```json { "Service": "redis", "Nodes": [ { "Node": { "ID": "40e4a748-2192-161a-0510-9bf59fe950b5", "Node": "foobar", "Address": "10.1.10.12", "Datacenter": "dc1", "TaggedAddresses": { "lan": "10.1.10.12", "wan": "10.1.10.12" }, "NodeMeta": { "instance_type": "m3.large" } }, "Service": { "ID": "redis", "Service": "redis", "Tags": null, "Meta": { "redis_version": "4.0" }, "Port": 8000 }, "Checks": [ { "Node": "foobar", "CheckID": "service:redis", "Name": "Service 'redis' check", "Status": "passing", "Notes": "", "Output": "", "ServiceID": "redis", "ServiceName": "redis" }, { "Node": "foobar", "CheckID": "serfHealth", "Name": "Serf Health Status", "Status": "passing", "Notes": "", "Output": "", "ServiceID": "", "ServiceName": "" } ], "DNS": { "TTL": "10s" }, "Datacenter": "dc3", "Failovers": 2 } ] } ``` - `Nodes` contains the list of healthy nodes providing the given service, as specified by the constraints of the prepared query. - `Service` has the service name that the query was selecting. This is useful for context in case an empty list of nodes is returned. - `DNS` has information used when serving the results over DNS. This is just a copy of the structure given when the prepared query was created. - `Datacenter` has the datacenter that ultimately provided the list of nodes and `Failovers` has the number of remote datacenters that were queried while executing the query. This provides some insight into where the data came from. This will be zero during non-failover operations where there were healthy nodes found in the local datacenter. ## Explain Prepared Query This endpoint generates a fully-rendered query for a given name, post interpolation. | Method | Path | Produces | | ------ | ---------------------- | ------------------ | | `GET` | `/query/:uuid/explain` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs/features/blocking), [consistency modes](/api-docs/features/consistency), [agent caching](/api-docs/features/caching), and [required ACLs](/api-docs#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `all` | `none` | `query:read` | ### Path Parameters - `uuid` `(string: )` - Specifies the UUID of the query to explain. This parameter can also be the name of an existing prepared query, or a name that matches a prefix name for a prepared query template. ### Query Parameters - `dc` `(string: "")` - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. ### Sample Request ```shell-session $ curl \ http://127.0.0.1:8500/v1/query/8f246b77-f3e1-ff88-5b48-8ec93abf3e05/explain ``` ### Sample Response ```json { "Query": { "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05", "Name": "my-query", "Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e", "Token": "", "Name": "geo-db", "Template": { "Type": "name_prefix_match", "Regexp": "^geo-db-(.*?)-([^\\-]+?)$" }, "Service": { "Service": "mysql-customer", "Failover": { "NearestN": 3, "Datacenters": ["dc1", "dc2"] }, "OnlyPassing": true, "Tags": ["primary"], "Meta": { "mysql_version": "5.7.20" }, "NodeMeta": { "instance_type": "m3.large" } } } } ```