Class: PEClient::Resource::PuppetDB::QueryV4::Factsets

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

Overview

The factsets endpoint provides access to a representation of node factsets where each result includes the structured facts for a node broken down into a vector of top-level key/value pairs. Note that the inventory endpoint will often provide more flexible and efficient access to the same information.

See Also:

Constant Summary collapse

BASE_PATH =

The base path for PuppetDB Query v4 Factsets endpoints.

"#{QueryV4::BASE_PATH}/factsets".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:, **kwargs) ⇒ Hash+

This will return all facts for a particular factset, designated by a node certname. 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>”], except results are returned even if the node is deactivated or expired.

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)
  • 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:



58
59
60
 
# File 'lib/pe_client/resources/puppet_db/query.v4/factsets.rb', line 58

def facts(node:, **kwargs)
  @client.get "#{BASE_PATH}/#{node}/facts", params: QueryV4.query_paging(**kwargs).compact
end

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

This will return all factsets matching the given query.

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 the most recent factset 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>, Hash)

See Also:



42
43
44
45
 
# File 'lib/pe_client/resources/puppet_db/query.v4/factsets.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