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