1---
2layout: "docs"
3page_title: "Commands: Query"
4sidebar_current: "docs-commands-query"
5description: |-
6  The `serf query` command dispatches a custom user query into a Serf cluster, efficiently broadcasting the query to all nodes, and gathering responses.
7---
8
9# Serf Query
10
11Command: `serf query`
12
13The `serf query` command dispatches a custom user query into a Serf cluster,
14efficiently broadcasting the query to all nodes, and gathering responses.
15
16Nodes in the cluster can listen for queries and respond to them.
17Example use cases of queries are to request load average, ask for the
18version of an app that is deployed, or to trigger deploys across web nodes
19by sending a "deploy" query, possibly with a commit payload.
20
21The command will wait until the query finishes (by reaching a timeout) and
22will report all acknowledgements and responses that are received.
23
24The open ended nature of `serf query` allows you to send and respond to
25queries in _any way_ you want.
26
27The main distinction between a Serf query and an event is that events
28are fire-and-forget. The Serf client will send the event immediately and
29will broadcast to the entire cluster. Events have no filtering mechanism
30and cannot reply or acknowledge receipt. Serf also tries harder to deliver
31events, by performing anti-entropy over TCP as well as message replay.
32
33Queries are intended to be a real-time request and response mechanism.
34Since they are intended to be time sensitive, Serf will not do message
35replay or anti-entropy, as a response to a very old query is not useful.
36Queries have more advanced filtering mechanisms and can be used to build
37more complex control flow. For example, a code deploy could check that at
38least 90% of nodes successfully deployed before continuing.
39
40## Usage
41
42Usage: `serf query [options] name [payload]`
43
44The command-line flags are all optional. The list of available flags are:
45
46* `-format` - Controls the output format. Supports `text` and `json`.
47  The default format is `text`.
48
49* `-no-ack` - If provided, the query will not request that nodes acknowledge
50  receipt of the query. By default, any nodes that pass the `-node` and `-tag` filters
51  will acknowledge receipt of a query and potentially respond if they have a configured
52  event handler.
53
54* `-relay-factor` - Available in Serf 0.8.1 and later, if provided, nodes responding to
55  the query will relay their response through the specified number of other nodes for
56  redundancy. Must be between 0 and 255.
57
58* `-node node` - If provided, output is filtered to only nodes with the given
59  node name. `-node` can be specified multiple times to allow multiple nodes.
60
61* `-tag key=value` - If provided, output is filtered to only nodes with the specified
62  tag if its value matches the regular expression. tag can be specified
63  multiple times to filter on multiple keys.
64
65* `-timeout=15s` - When provided, the given timeout overrides the default query timeout.
66  By default, a query has a timeout that is designed to give the cluster enough time
67  to gossip the message out and to respond. This is a computed multiple of the
68  GossipInterval, a QueryTimeoutMultipler and a logarithmic scale based on cluster size.
69  This time may be low for long running queries, so this flag can be used to specify
70  an alternative timeout.
71
72* `-rpc-addr` - Address to the RPC server of the agent you want to contact
73  to send this command. If this isn't specified, the command will contact
74  "127.0.0.1:7373" which is the default RPC address of a Serf agent. This option
75  can also be controlled using the `SERF_RPC_ADDR` environment variable.
76
77* `-rpc-auth` - Optional RPC auth token. If the agent is configured to use
78  an auth token, then this must be provided or the agent will refuse the
79  command.  This option can also be controlled using the `SERF_RPC_AUTH`
80  environment variable.
81