consul.api.query module

class consul.api.query.Query(agent)

Bases: object

list(dc=None, token=None)

Lists all the active queries. This is a privileged endpoint, therefore you will only be able to get the prepared queries which the token supplied has read privileges to.

dc is the datacenter that this agent will communicate with. By default the datacenter of the host is used.

token is an optional `ACL token`_ to apply to this request.

Parameters:

token (str | None)

create(service, name=None, dc=None, session=None, token=None, nearestn=None, datacenters=None, onlypassing=None, tags=None, ttl=None, regexp=None)

Creates a new query. This is a privileged endpoint, and requires a management token for a certain query name.*token* will override this client’s default token.

service is mandatory for new query. represent service name to query.

name is an optional name for this query.

dc is the datacenter that this agent will communicate with. By default the datacenter of the host is used.

token is an optional `ACL token`_ to apply to this request.

nearestn if set to a value greater than zero, then the query will be forwarded to up to NearestN other datacenters based on their estimated network round trip time using Network Coordinates from the WAN gossip pool.

datacenters is a fixed list of remote datacenters to forward the query to if there are no healthy nodes in the local datacenter.

onlypassing controls the behavior of the query’s health check filtering.

tags is a list of service tags to filter the query results.

ttl is a duration string that can use “s” as a suffix for seconds. It controls how the TTL is set when query results are served over DNS.

regexp is optional for template this option is only supported in Consul 0.6.4 or later. The only option for type is name_prefix_match so if you want a query template with no regexp enter an empty string.

For more information about query https://developer.hashicorp.com/consul/api-docs/query

Parameters:

• name (str | None)

• token (str | None)

• ttl (int | None)

update(query_id, service=None, name=None, dc=None, session=None, token=None, nearestn=None, datacenters=None, onlypassing=None, tags=None, ttl=None, regexp=None)

This endpoint will update a certain query

query_id is the query id for update

all the other setting remains the same as the query create method

Parameters:

• name (str | None)

• token (str | None)

• ttl (int | None)

get(query_id, token=None, dc=None)

This endpoint will return information about a certain query

query_id the query id to retrieve information about

token is an optional `ACL token`_ to apply to this request.

dc is the datacenter that this agent will communicate with. By default the datacenter of the host is used.

Parameters:

token (str | None)

delete(query_id, token=None, dc=None)

This endpoint will delete certain query

query_id the query id delete

token is an optional `ACL token`_ to apply to this request.

dc is the datacenter that this agent will communicate with. By default the datacenter of the host is used.

Parameters:

token (str | None)

execute(query, token=None, dc=None, near=None, limit=None)

This endpoint will execute certain query

query name or query id to execute

token is an optional `ACL token`_ to apply to this request.

dc is the datacenter that this agent will communicate with. By default the datacenter of the host is used.

near is a node name to sort the resulting list in ascending order based on the estimated round trip time from that node

limit is used to limit the size of the list to the given number of nodes. This is applied after any sorting or shuffling.

Parameters:

• token (str | None)

• limit (int | None)

explain(query, token=None, dc=None)

This endpoint shows a fully-rendered query for a given name

query name to explain. This cannot be query id.

token is an optional `ACL token`_ to apply to this request.

dc is the datacenter that this agent will communicate with. By default the datacenter of the host is used.

Parameters:

token (str | None)