Query

Query handling: factory and builder.

class cumin.query.Query(config)[source]

Bases: cumin.backends.BaseQueryAggregator

Cumin main query class.

It has multi-query capability and allow to use a default backend, if set, without additional syntax. If a default_backend is set in the configuration, it will try to execute the query string first with the default backend and only if the query is not parsable with that backend it will try to execute it with the multi-query grammar.

When a query is executed, a ClusterShell.NodeSet.NodeSet with the FQDN of the matched hosts is returned.

Examples

>>> import cumin
>>> from cumin.query import Query
>>> config = cumin.Config()
>>> hosts = Query(config).execute(query_string)
__init__(config)[source]

Query constructor, initialize the registered backends.

Parameters

according to parent cumin.backends.BaseQueryAggregator.__init__().

_aggregate_hosts(hosts, element_hosts, bool_operator)

static inherited Aggregate hosts according to their boolean operator.

Parameters
  • hosts (ClusterShell.NodeSet.NodeSet) -- the hosts to update with the results in element_hosts according to the bool_operator. This object is updated in place by reference.

  • element_hosts (ClusterShell.NodeSet.NodeSet) -- the additional hosts to aggregate to the results based on the bool_operator.

  • bool_operator (str, None) -- the boolean operator to apply while aggregating the two NodeSet. It must be None when adding the first hosts.

_build(query_string)

static inherited Override parent method to reset the stack and log it.

Parameters

according to parent cumin.backends.BaseQuery._build().

_close_subgroup()

static inherited Handle subgroup closing.

_execute()

static inherited Concrete implementation of parent abstract method.

Parameters

according to parent cumin.backends.BaseQuery._execute().

static _get_stack_element()

static inherited Return an empty stack element.

Returns

the dictionary with an empty stack element.

Return type

dict

_loop_stack(hosts, stack_element)

static inherited Loop the stack generated while parsing the query and aggregate the results.

Parameters
  • hosts (ClusterShell.NodeSet.NodeSet) -- the hosts to be updated with the current stack element results. This object is updated in place by reference.

  • stack_element (dict) -- the stack element to iterate.

_open_subgroup()

static inherited Handle subgroup opening.

_parse_token(token)[source]

Concrete implementation of parent abstract method.

Parameters

according to parent cumin.backends.BaseQueryAggregator._parse_token().

Raises

cumin.backends.InvalidQueryError -- on internal parsing error.

_query_default_backend(query_string)[source]

Execute the query with the default backend, according to the configuration.

Parameters

query_string (str) -- the query string to be parsed and executed with the default backend.

Returns

with the FQDNs of the matching hosts.

Return type

ClusterShell.NodeSet.NodeSet

Raises

cumin.backends.InvalidQueryError -- if unable to get the default backend from the registered backends.

_replace_alias(token_dict)[source]

Replace any alias in the query in a recursive way, alias can reference other aliases.

Parameters

token_dict (dict) -- the dictionary of the parsed token returned by the grammar parsing.

Returns

True if a replacement was made, :py:data`False` otherwise.

Return type

bool

Raises

cumin.backends.InvalidQueryError -- if unable to replace an alias.

execute(query_string)[source]

Override parent class execute method to implement the multi-query capability.

Parameters

according to parent cumin.backends.BaseQueryAggregator.execute().

Returns

with the FQDNs of the matching hosts.

Return type

ClusterShell.NodeSet.NodeSet

Raises

cumin.backends.InvalidQueryError -- if unable to parse the query.