{"id":15013919,"url":"https://github.com/dalen/puppet-puppetdbquery","last_synced_at":"2025-05-16T12:10:19.015Z","repository":{"id":3644955,"uuid":"4712399","full_name":"dalen/puppet-puppetdbquery","owner":"dalen","description":"Query functions for PuppetDB","archived":true,"fork":false,"pushed_at":"2025-05-05T13:46:38.000Z","size":314,"stargazers_count":198,"open_issues_count":28,"forks_count":70,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-05-08T01:04:17.337Z","etag":null,"topics":["puppet","puppetdb","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dalen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-06-19T10:40:50.000Z","updated_at":"2025-05-05T13:47:36.000Z","dependencies_parsed_at":"2024-09-20T15:32:02.516Z","dependency_job_id":null,"html_url":"https://github.com/dalen/puppet-puppetdbquery","commit_stats":{"total_commits":299,"total_committers":30,"mean_commits":9.966666666666667,"dds":"0.33444816053511706","last_synced_commit":"438c089759680b6bb2ec070699aab2141775d2be"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalen%2Fpuppet-puppetdbquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalen%2Fpuppet-puppetdbquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalen%2Fpuppet-puppetdbquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalen%2Fpuppet-puppetdbquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dalen","download_url":"https://codeload.github.com/dalen/puppet-puppetdbquery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253895024,"owners_count":21980444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["puppet","puppetdb","ruby"],"created_at":"2024-09-24T19:44:56.645Z","updated_at":"2025-05-16T12:10:18.992Z","avatar_url":"https://github.com/dalen.png","language":"Ruby","readme":"# Project archived\n\nThis project has largely been replaced by the PQL in newer PuppetDB versions, see https://www.puppet.com/blog/puppet-query-language-pql\n\n[![Build Status](https://travis-ci.org/dalen/puppet-puppetdbquery.png)](https://travis-ci.org/dalen/puppet-puppetdbquery)\n\n# PuppetDB query tools\n\nThis module implements command line tools and Puppet functions that can be used to query puppetdb.\nThere's also a hiera backend that can be used to return query results from puppetdb.\n\n## Usage warning\n\nYou might not need this puppet module anymore. PuppetDB bundles a simplified query language since version 4.0. So unless you really prefer the syntax in this module you can just use PQL instead. See https://puppet.com/blog/introducing-puppet-query-language-pql for more details.\n\n# Requirements\n\nPuppetDB terminus is required for the Puppet functions, but not for the face.\n\nTo parse date queries the Ruby gem \"chronic\" is required.\n\n## Required PuppetDB version\n\nThis module uses the V4 API, and as such it requires at least PuppetDB 3.0.0.\nIf you are using PuppetDB 2.x please use the 1.x version of this module instead.\n\n# Query syntax\n\nUse `fact=value` to search for nodes where `fact` equals `value`. To search for\nstructured facts use dots between each part of the fact path, for example\n`foo.bar=baz`.\n\nResources can be matched using the syntax `type[title]{param=value}`.\nThe part in brackets is optional. You can also specify `~` before the `title`\nto do a regexp match on the title. Type names and class names are case insensitive.\nA resource can be preceded by @@ to match exported resources, the default is to only\nmatch \"local\" resources.\n\nStrings can contain letters, numbers or the characters :-\\_ without needing to be quoted.\nIf they contain any other characters they need to be quoted with single or double quotes.\nUse backslash (\\) to escape quotes within a quoted string or double backslash for backslashes.\n\nAn unquoted number or the strings true/false will be interpreted as numbers and boolean\nvalues, use quotation marks around them to search for them as strings instead.\n\nA @ sign before a string causes it to be interpreted as a date parsed with\n[chronic](https://github.com/mojombo/chronic). For example `@\"2 hours ago\"`.\n\nA # sign can be used to do a subquery, against the nodes endpoint for example to\nquery the `report_timestamp`, `catalog_timestamp` or `facts_timestamp` fields.\nFor example `#node.report_timestamp \u003c @\"2 hours ago\"`.\n\nA subquery using the # sign can have a block of expressions instead of a single\nexpression. For example `#node { report_timestamp \u003e @\"4 hours ago\" and\nreport_timestamp \u003c @\"2 hours ago\" }`\n\nA bare string without comparison operator will be treated as a regexp match against the certname.\n\n#### Comparison operators\n\n| Op  | Meaning                |\n| --- | ---------------------- |\n| =   | Equality               |\n| !=  | Not equal              |\n| ~   | Regexp match           |\n| !~  | Not equal Regexp match |\n| \u003c   | Less than              |\n| =\u003c  | Less than or equal     |\n| \u003e   | Greater than           |\n| =\u003e  | Greater than or equal  |\n\n#### Logical operators\n\n| Op  |            |\n| --- | ---------- |\n| not | (unary op) |\n| and |            |\n| or  |            |\n\nShown in precedence order from highest to lowest. Use parenthesis to change order in an expression.\n\n### Query Examples\n\nNodes with package mysql-server and amd64 arcitecture\n\n    (package[\"mysql-server\"] and architecture=amd64)\n\nNodes with the class Postgresql::Server and a version set to 9.3\n\n    class[postgresql::server]{version=9.3}\n\nNodes with 4 or 8 processors running Linux\n\n    (processorcount=4 or processorcount=8) and kernel=Linux\n\nNodes that haven't reported in the last 2 hours\n\n    #node.report_timestamp\u003c@\"2 hours ago\"\n\n# Usage\n\nTo get a list of the supported subcommands for the puppetdbquery face, run:\n\n     $ puppet help puppetdbquery\n\nYou can run `puppet help` on the returned subcommands\n\n    $ puppet help puppetdbquery nodes\n    $ puppet help puppetdbquery facts\n\n## CLI\n\nEach of the faces uses the following query syntax to return all objects found on a subset of nodes:\n\n    # get all nodes that contain the apache package and are in france, or all nodes in the us\n    $ puppet puppetdbquery nodes '(Package[httpd] and country=fr) or country=us'\n\nEach of the individual faces returns a different data format:\n\nnodes - a list of nodes identified by a name\n\n     $ puppet puppetdbquery nodes '(Package[\"mysql-server\"] and architecture=amd64)'\n       [\"db_node_1\", \"db_node2\"]\n\nfacts - a hash of facts per node\n\n     $ puppet puppetdbquery facts '(Package[\"mysql-server\"] and architecture=amd64)'\n       db_node_1  {\"facterversion\":\"1.6.9\",\"hostname\":\"controller\",...........}\n       db_node_2  {\"facterversion\":\"1.6.9\",\"hostname\":\"controller\",...........}\n\nevents - a list of events on the matched nodes\n\n     $ puppet puppetdbquery events '(Package[\"mysql-server\"] and architecture=amd64)' --since='1 hour ago' --until=now --status=success\n       host.example.com: 2013-06-10T10:58:37.000Z: File[/foo/bar]/content ({md5}5711edf5f5c50bd7845465471d8d39f0 -\u003e {md5}e485e731570b8370f19a2a40489cc24b): content changed '{md5}5711edf5f5c50bd7845465471d8d39f0' to '{md5}e485e731570b8370f19a2a40489cc24b'\n\n## Ruby\n\nfaces can be called from the ruby in exactly they same way they are called from the command line:\n\n    $ irb\u003e require 'puppet/face'\n      irb\u003e Puppet.initialize_settings\n      irb\u003e Puppet::Face[:puppetdbquery, :current].nodes('(Package[\"mysql-server\"] and architecture=amd64)')\n\n## Puppet functions\n\nThere's corresponding functions to query PuppetDB directly from Puppet manifests.\nAll the functions accept either the simplified query language or raw PuppetDB API queries.\n\n### query_nodes\n\nAccepts two arguments, a query used to discover nodes, and a optional\nfact that should be returned.\n\nReturns an array of certnames or fact values if a fact is specified.\n\n#### Examples\n\n    $hosts = query_nodes('manufacturer~\"Dell.*\" and processorcount=24 and Class[Apache]')\n\n    $hostips = query_nodes('manufacturer~\"Dell.*\" and processorcount=24 and Class[Apache]', 'ipaddress')\n\n### query_resources\n\nAccepts two arguments or three argument, a query used to discover nodes, and a resource query\n, and an optional a boolean to whether or not to group the result per host.\n\nReturn either a hash (by default) that maps the name of the nodes to a list of\nresource entries. This is a list because there's no single\nreliable key for resource operations that's of any use to the end user.\n\n#### Examples\n\nReturns the parameters and such for the ntp class for all CentOS nodes:\n\n    $resources = query_resources('Class[\"apache\"]{ port = 443 }', 'User[\"apache\"]')\n\nReturns the parameters for the apache class for all nodes in a flat array:\n\n    query_resources(false, 'Class[\"apache\"]', false)\n\n### query_facts\n\nSimilar to query_nodes but takes two arguments, the first is a query used to discover nodes, the second is a list of facts to return for those nodes.\n\nReturns a nested hash where the keys are the certnames of the nodes, each containing a hash with facts and fact values.\n\n#### Example\n\n    query_facts('Class[Apache]{port=443}', ['osfamily', 'ipaddress'])\n\nExample return value in JSON format:\n\n    {\n      \"foo.example.com\": {\n        \"ipaddress\": \"192.168.0.2\",\n        \"osfamily\": \"Redhat\"\n      },\n      \"bar.example.com\": {\n        \"ipaddress\": \"192.168.0.3\",\n        \"osfamily\": \"Debian\"\n      }\n    }\n\n### Querying nested facts\n\nFacter 3 introduced many nested facts, so puppetdbquery provides an easy way to query for a value nested within a fact that's a hash.\nTo query for a nested value, simply join the keys you want to extract together on periods, like so:\n\n#### Example\n\n    $host_eth0_networks = query_nodes('manufacturer~\"Dell.*\" and Class[Apache]', 'networking.interfaces.eth0.network')\n\n    $host_kernels_and_ips = query_facts('manufacturer~\"Dell.*\" and Class[Apache]', ['kernel', 'networking.interfaces.eth1.ip'])\n\n## Hiera backend\n\nThe hiera backend can be used to return an array with results from a puppetdb query. It requires another hiera backend to be active at the same time, and that will be used to define the actual puppetdb query to be used. It does not matter which backend that is, there can even be several of them. To enable add the backend `puppetdb`to the backends list in `hiera.yaml`.\n\n### hiera 3\n\n```yaml\n---\n:backends:\n  - yaml\n  - puppetdb\n```\n\n### hiera 5\n\n```yaml\n---\nversion: 5\n\nhierarchy:\n  - name: Puppetdb\n    lookup_key: puppetdb_lookup_key\n```\n\n### Note: hiera 5 is not backward compatible\n\nYou can not use the hiera 3 backed at all in hiera 5. Backwards compatibility is broken.\nYou must switch to hiera 5 config to use this in hiera 5.\n\n### Examples\n\nSo instead of writing something like this in for example your `hiera-data/common.yaml`:\n\n    ntp::servers:\n      - 'ntp1.example.com'\n      - 'ntp2.example.com'\n\nYou can now instead write:\n\n    ntp::servers::_nodequery: 'Class[Ntp::Server]'\n\nIt will then find all nodes with the class ntp::server and return an array containing their certname. If you instead want to return the value of a fact, for example the `ipaddress`, the nodequery can be a tuple, like:\n\n    ntp::servers::_nodequery: ['Class[Ntp::Server]', 'ipaddress']\n\nor a hash:\n\n    ntp::servers::_nodequery:\n      query: 'Class[Ntp::Server]'\n      fact: 'ipaddress'\n\nSometimes puppetdb doesn't return items in the same order every run - hiera 5 only:\n\n    ntp::servers::_nodequery: ['Class[Ntp::Server]', 'ipaddress', true]\n\n    ntp::servers::_nodequery:\n      query: 'Class[Ntp::Server]'\n      fact: 'ipaddress'\n      sort: true\n\nWhen returning facts only nodes that actually have the fact are returned, even if more nodes would in fact match the query itself.\n\n# Related projects\n\n- JavaScript version: https://github.com/dalen/node-puppetdbquery\n- Python version: https://github.com/bootc/pypuppetdbquery\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalen%2Fpuppet-puppetdbquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdalen%2Fpuppet-puppetdbquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalen%2Fpuppet-puppetdbquery/lists"}