Class: PEClient::Resource::PuppetDB::QueryV4::Nodes

Inherits:
Base
  • Object
show all
Defined in:
lib/pe_client/resources/puppet_db/query.v4/nodes.rb

Overview

Nodes can be queried by making requests through these endpoints.

See Also:

Constant Summary collapse

BASE_PATH =

The base path for PuppetDB Query v4 Nodes endpoints.

"#{QueryV4::BASE_PATH}/nodes".freeze

Instance Method Summary collapse

Methods inherited from Base

#initialize

Constructor Details

This class inherits a constructor from PEClient::Resource::Base

Instance Method Details

#facts(node:, name: nil, value: nil, query: nil, **kwargs) ⇒ Hash+

This will return the facts for the given node. Facts from deactivated and expired nodes aren’t included in the response. This is a shortcut to the PEClient::Resource::PuppetDB::QueryV4#facts endpoint. It behaves the same as a call to PEClient::Resource::PuppetDB::QueryV4#facts with a query string of [“=”, “certname”, “<NODE>”]. Facts from deactivated and expired nodes aren’t included in the response.

Most of PuppetDB’s query endpoints support a general set of HTTP URL parameters that can be used for paging results. PuppetDB also supports paging via query operators, as described in the AST documentation.

Parameters:

  • node (String)
  • name (String) (defaults to: nil) —

    This will return facts with the given name for the given node.

  • value (String) (defaults to: nil) —

    This will return facts with the given name and value for the given node.

  • query (Array) (defaults to: nil) —

    An Array of query predicates, in prefix notation ([“<OPERATOR>”, “<FIELD>”, “<VALUE>”]).

  • kwargs (Hash) —

    Keyword arguments for paging

Options Hash (**kwargs):

  • :order_by (String) —

    This parameter can be used to ask PuppetDB to return results sorted by one or more fields, in ascending or descending order. The value must be an Array of Hashes. Each map represents a field to sort by, and the order in which the maps are specified in the array determines the sort order. Each map must contain the key field, whose value must be the name of a field that can be returned by the specified query. Each map may also optionally contain the key order, whose value may either be “asc” or “desc”, depending on whether you wish the field to be sorted in ascending or descending order. The default value for this key, if not specified, is “asc”. Note that the legal values for field vary depending on which endpoint you are querying. For lists of legal fields, please refer to the documentation for the specific query endpoints.

  • :limit (Integer) —

    This parameter can be used to restrict the result set to a maximum number of results.

  • :include_total (Boolean) —

    This parameter lets you request a count of how many records would have been returned, had the query not been limited using the limit parameter. This is useful if you want your application to show how far the user has navigated (“page 3 of 15”). The value should be a Boolean, and defaults to false. If true, the HTTP response will contain a header X-Records, whose value is an integer indicating the total number of results available. Note: Setting this flag to true can decrease performance.

  • :offset (Integer) —

    This parameter can be used to tell PuppetDB to return results beginning at the specified offset. For example, if you’d like to page through query results with a page size of 10, your first query would specify ‘limit: 10` and `offset: 0`, your second query would specify `limit: 10` and `offset: 10`, and so on. Note that the order in which results are returned by PuppetDB is not guaranteed to be consistent unless you specify a value for :order_by, so this parameter should generally be used in conjunction with :order_by.

Returns:

  • (Hash)
  • (Array<Hash>)

See Also:



63
64
65
66
67
68
 
# File 'lib/pe_client/resources/puppet_db/query.v4/nodes.rb', line 63

def facts(node:, name: nil, value: nil, query: nil, **kwargs)
  uri = "#{BASE_PATH}/#{node}/facts"
  uri += "/#{name}" if name
  uri += "/#{value}" if name && value
  @client.get uri, params: {query: query&.to_json}.merge!(QueryV4.query_paging(**kwargs)).compact
end

#get(node: nil, query: nil, **kwargs) ⇒ Hash+

This will return all nodes matching the given query. Deactivated and expired nodes aren’t included in the response.

Most of PuppetDB’s query endpoints support a general set of HTTP URL parameters that can be used for paging results. PuppetDB also supports paging via query operators, as described in the AST documentation.

Parameters:

  • node (String) (defaults to: nil) —

    This will return status information for the given node, active or not. It behaves exactly like a call with ‘node: nil` but with a query string of [“=”, “certname”, “<NODE>”].

  • query (Array) (defaults to: nil) —

    An Array of query predicates, in prefix notation ([“<OPERATOR>”, “<FIELD>”, “<VALUE>”]).

  • kwargs (Hash) —

    Keyword arguments for paging

Options Hash (**kwargs):

  • :order_by (String) —

    This parameter can be used to ask PuppetDB to return results sorted by one or more fields, in ascending or descending order. The value must be an Array of Hashes. Each map represents a field to sort by, and the order in which the maps are specified in the array determines the sort order. Each map must contain the key field, whose value must be the name of a field that can be returned by the specified query. Each map may also optionally contain the key order, whose value may either be “asc” or “desc”, depending on whether you wish the field to be sorted in ascending or descending order. The default value for this key, if not specified, is “asc”. Note that the legal values for field vary depending on which endpoint you are querying. For lists of legal fields, please refer to the documentation for the specific query endpoints.

  • :limit (Integer) —

    This parameter can be used to restrict the result set to a maximum number of results.

  • :include_total (Boolean) —

    This parameter lets you request a count of how many records would have been returned, had the query not been limited using the limit parameter. This is useful if you want your application to show how far the user has navigated (“page 3 of 15”). The value should be a Boolean, and defaults to false. If true, the HTTP response will contain a header X-Records, whose value is an integer indicating the total number of results available. Note: Setting this flag to true can decrease performance.

  • :offset (Integer) —

    This parameter can be used to tell PuppetDB to return results beginning at the specified offset. For example, if you’d like to page through query results with a page size of 10, your first query would specify ‘limit: 10` and `offset: 0`, your second query would specify `limit: 10` and `offset: 10`, and so on. Note that the order in which results are returned by PuppetDB is not guaranteed to be consistent unless you specify a value for :order_by, so this parameter should generally be used in conjunction with :order_by.

Returns:

  • (Hash)
  • (Array<Hash>, Hash)

See Also:



42
43
44
45
 
# File 'lib/pe_client/resources/puppet_db/query.v4/nodes.rb', line 42

def get(node: nil, query: nil, **kwargs)
  @client.get node ? "#{BASE_PATH}/#{node}" : BASE_PATH,
    params: {query: query&.to_json}.merge!(QueryV4.query_paging(**kwargs)).compact
end

#resources(node:, type: nil, title: nil, query: nil, **kwargs) ⇒ Hash+

This will return the resources for the given node. Resources from deactivated and expired nodes aren’t included in the response. This is a shortcut to the PEClient::Resource::PuppetDB::QueryV4#resources endpoint. It behaves the same as a call to PEClient::Resource::PuppetDB::QueryV4#resources with a query string of [“=”, “certname”, “<NODE>”].

Most of PuppetDB’s query endpoints support a general set of HTTP URL parameters that can be used for paging results. PuppetDB also supports paging via query operators, as described in the AST documentation.

Parameters:

  • node (String)
  • type (String) (defaults to: nil) —

    This will return the resources of the indicated type for the given node.

  • title (String) (defaults to: nil) —

    This will return the resource of the indicated type and title for the given node.

  • query (Array) (defaults to: nil) —

    An Array of query predicates, in prefix notation ([“<OPERATOR>”, “<FIELD>”, “<VALUE>”]).

  • kwargs (Hash) —

    Keyword arguments for paging

Options Hash (**kwargs):

  • :order_by (String) —

    This parameter can be used to ask PuppetDB to return results sorted by one or more fields, in ascending or descending order. The value must be an Array of Hashes. Each map represents a field to sort by, and the order in which the maps are specified in the array determines the sort order. Each map must contain the key field, whose value must be the name of a field that can be returned by the specified query. Each map may also optionally contain the key order, whose value may either be “asc” or “desc”, depending on whether you wish the field to be sorted in ascending or descending order. The default value for this key, if not specified, is “asc”. Note that the legal values for field vary depending on which endpoint you are querying. For lists of legal fields, please refer to the documentation for the specific query endpoints.

  • :limit (Integer) —

    This parameter can be used to restrict the result set to a maximum number of results.

  • :include_total (Boolean) —

    This parameter lets you request a count of how many records would have been returned, had the query not been limited using the limit parameter. This is useful if you want your application to show how far the user has navigated (“page 3 of 15”). The value should be a Boolean, and defaults to false. If true, the HTTP response will contain a header X-Records, whose value is an integer indicating the total number of results available. Note: Setting this flag to true can decrease performance.

  • :offset (Integer) —

    This parameter can be used to tell PuppetDB to return results beginning at the specified offset. For example, if you’d like to page through query results with a page size of 10, your first query would specify ‘limit: 10` and `offset: 0`, your second query would specify `limit: 10` and `offset: 10`, and so on. Note that the order in which results are returned by PuppetDB is not guaranteed to be consistent unless you specify a value for :order_by, so this parameter should generally be used in conjunction with :order_by.

Returns:

  • (Hash)
  • (Array<Hash>)

See Also:



86
87
88
89
90
91
 
# File 'lib/pe_client/resources/puppet_db/query.v4/nodes.rb', line 86

def resources(node:, type: nil, title: nil, query: nil, **kwargs)
  uri = "#{BASE_PATH}/#{node}/resources"
  uri += "/#{type}" if type
  uri += "/#{title}" if type && title
  @client.get uri, params: {query: query&.to_json}.merge!(QueryV4.query_paging(**kwargs)).compact
end