From 01b28b9581c8950a694daeeef638ac1cbcd0b4a2 Mon Sep 17 00:00:00 2001 From: Ryan Uber Date: Fri, 1 Jul 2016 11:50:09 -0700 Subject: [PATCH] website: document near parameter of prepared queries --- .../source/docs/agent/http/query.html.markdown | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/website/source/docs/agent/http/query.html.markdown b/website/source/docs/agent/http/query.html.markdown index bad3ae1288..d2737384d9 100644 --- a/website/source/docs/agent/http/query.html.markdown +++ b/website/source/docs/agent/http/query.html.markdown @@ -70,6 +70,7 @@ query, like this example: "Name": "my-query", "Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e", "Token": "", + "Near": "node1", "Service": { "Service": "redis", "Failover": { @@ -114,6 +115,16 @@ attribute which can be set on functions. This change in effect moves Consul from using `SECURITY DEFINER` by default to `SECURITY INVOKER` by default for new Prepared Queries. + +`Near` allows specifying a particular node to sort near based on distance +sorting using [Network Coordinates](/docs/internals/coordinates.html). 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. Using the magic `_agent` value is supported, and will automatically +return results nearest the agent servicing the request. If unspecified, the +response will be shuffled by default. + The set of fields inside the `Service` structure define the query's behavior. `Service` is the name of the service to query. This is required. @@ -365,8 +376,9 @@ blocking queries, but it does support all consistency modes. Adding the optional "?near=" parameter with a node name will 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. If this is not -present, then the nodes will be shuffled randomly and will be in a different -order each time the query is executed. +present, the default behavior will shuffle the nodes randomly each time the +query is executed. Passing this option will override the built-in +near parameter of a prepared query, if present. An optional "?limit=" parameter can be used to limit the size of the list to the given number of nodes. This is applied after any sorting or shuffling.