1--- 2title: "Upgrading from version 3" 3layout: default 4canonical: "/puppetdb/latest/api/query/v4/upgrading-from-v3.html" 5--- 6 7# Upgrading from version 3 8 9This page describes changes that users will need to be aware of 10to make their code compliant with the changes in PuppetDB 3.0. Most of these 11changes are observable in released versions of the v4 query API, which has been 12marked 'experimental' since 2.0.0 but is the only API available in 3.0. 13 14Note that this document focuses on API changes only, and only includes changes 15leading up to the release of 3.0. For a more complete description 16of the changes listed and changes in versions subsequent to 3.0, see the 17[release notes](../../../release_notes.markdown). 18 19Each change below is marked with the corresponding release version. 20 21## Backward-incompatible changes 22 23### Changes affecting all endpoints 24 25* (3.0) The query API has been moved from `/` to `/pdb/query`, so 26 http://localhost:8080/v4/facts has become 27 http://localhost:8080/pdb/query/v4/facts. 28 29* (3.0) The `/commands` endpoint has been moved to its own API at `/pdb/cmd`, so 30 http://localhost:8080/v3/commands has become 31 http://localhost:8080/pdb/cmd/v1. 32 33* (3.0) The `version` and `server-time` endpoints have been moved out of the 34 query API and into to a separate `metadata` API. They are now accessed at 35 `/pdb/meta/v1/version` and `/pdb/meta/v1/server-time`. 36 37* (3.0) All previously dash-separated field names (such as "receive-time"), subquery 38 operators (such as "select-facts"), and query parameters (such as "order-by") are now 39 underscore-separated. This change does not apply to dash-separated endpoint 40 names such as `aggregate-event-counts`. 41 42* (3.0) All endpoints with child rest queries (for example `/pdb/query/v4/environments/<env_name>/facts`) 43 now return a 404 if the parent data does not exist. In the past, an empty array was returned in this case, but this gave the impression that there was a parent 44 but the particular child data was empty. To improve clarity, missing parent data now returns a 404 "Not Found" status code and a proper JSON error. 45 46### /pdb/query/v4/catalogs 47 48* (3.0) The v4 catalogs endpoint has caused the response of the 49 `edges` and `resources` fields to be expanded. For more information, 50 see [catalogs documentation](catalogs.markdown). 51 52* (3.0) We have renamed the "name" key of the catalogs endpoint to "certname", for 53 consistency with other endpoints. 54 55* (3.0) The top-level v4 catalogs endpoint will now only return data about nodes 56 that are active. This provides the same consistency as other non-historical 57 data returns. Endpoints which specify the node explicitly will return results 58 even for deactivated or expired nodes. 59 60* (2.0.0) The v4 catalogs endpoint does not contain a `metadata` field 61 or an `api_version` field. The contents of the v3 `data` field 62 compose the v4 response body, along with the new fields 63 `producer_timestamp`, `hash`, and `environment`. For more 64 information, see the 65 [catalogs documentation](catalogs.markdown). 66 67### /pdb/query/v4/facts 68 69* (2.2.0) The v4 facts endpoint returns proper JSON rather than stringified JSON 70 under the `value` field in the case of a structured fact. 71 72* (2.2.0) Queries against fact values must use the appropriate type. Possible types are integer, float, Boolean, string, JSON, and null. Where the v3 API would return the same results for `[">","value","10"]` and `[">","value",10]`, only the second form will work on v4. The same applies for equality queries on Boolean values. 73 74### /pdb/query/v4/factsets 75 76* (2.2) The v4 factsets endpoint was added to facilitate the grouping 77 of facts per node. For more information, see the 78 [factsets documentation](factsets.markdown). 79 80* (3.0) We added a `hash` field to the endpoint fields to support a unique identifer for factsets. 81 82* (3.0) The `facts` field is now expanded as per our new expansion 83 convention, so the data format has changed. For more information, see 84 the [factsets documentation](factsets.markdown). 85 86* (3.0) The `/pdb/query/v4/factsets/<node>/facts` endpoints will now 87 return results even for deactivated or expired nodes. 88 89### /pdb/query/v4/aggregate-event-counts 90 91* (3.0) the `aggregate-event-counts` endpoint is no longer supported on HSQLDB. 92 93* (3.0) the `aggregate-event-counts` endpoint now accepts multiple `summarize_by` 94 parameters and returns an array of maps instead of a map. An additional 95 `summarize_by` field has also been added to describe the parameter used. For 96 more information, see the 97 [aggregate-event-counts documentation](aggregate-event-counts.markdown). 98 99### /metrics/v1 (formerly /v3/metrics) 100 101* (3.0) The former metrics endpoint has been split off into a separate service, and 102 reversioned at v1. If you are currently accessing mbeans at 103 http://localhost:8080/v3/metrics/mbeans, you will now access them at 104 http://localhost:8080/metrics/v1/mbeans and so on, according to the 105 [metrics api documentation](../../metrics/v1/mbeans.markdown). 106 107* (3.0) PuppetDB's mbeans (listed at /metrics/v1/mbeans) are no longer prefixed with 108 "com." 109 110### /pdb/cmd/v1 (formerly /v3/commands) 111 112 * (3.0) For users posting commands directly to the 113 /pdb/cmd/v1 endpoint, the only valid command submission 114 versions will be 115 [replace catalogs v6](../../../api/wire_format/catalog_format_v6.markdown), 116 [store report v5](../../../api/wire_format/report_format_v5.markdown), 117 and [replace facts v4](../../../api/wire_format/facts_format_v4.markdown). 118 119### /pdb/meta/v1/version (formerly /v3/version) 120* (3.0) The version endpoint has been split from the query service and mounted 121 at `pdb/meta/v1/version`. 122 123### /pdb/meta/v1/server-time (formerly /v3/server-time) 124* (3.0) The server-time endpoint has been split from the query service and mounted 125 at `pdb/meta/v1/server-time`. 126 127## New API features 128 129### New endpoints 130 131* (2.2.0) `/pdb/query/v4/factsets` This endpoint returns a key-value 132 hash for each certname. For more information, see the 133 [factsets documentation](factsets.markdown#response-format). 134 135* (2.2.0) `/pdb/query/v4/fact-paths` This endpoint is similar to the 136 existing fact-names endpoint in that one expected use is GUI 137 autocompletion. For more information, see the 138 [documentation](fact-paths.markdown). 139 140* (2.2.0) `/pdb/query/v4/fact-contents` This endpoint allows 141 fine-grained querying of structured facts. For more information, see 142 the [documentation](fact-contents.markdown). 143 144* (3.0) `/pdb/query/v4/edges` This endpoint allows querying edges 145 inside a catalog. For more information, see the 146 [edges documentation](edges.markdown) 147 148* (3.0) `/pdb/query/v4/reports/<hash>/events` This convenience 149 endpoint allows you to show events for a particular report by its 150 hash. See the [/pdb/query/v4/reports documentation](reports.markdown) 151 152* (3.0) `/pdb/query/v4/reports/<hash>/metrics` This endpoint allows 153 you to show metrics for a particular report by its hash. See the 154 [reports documentation](reports.markdown) 155 156* (3.0) `/pdb/query/v4/reports/<hash>/logs` This endpoint allows you 157 to show logs for a particular report by its hash. See the 158 [reports documentation](reports.markdown) 159 160* (3.0) `/pdb/query/v4/catalogs/<node>/[resources|edges]` Both of 161 these endpoints provide convenience for drilling into resources and 162 edges data specific to a particular catalog. See 163 [catalogs documentation](catalogs.markdown) 164 165### Features affecting all endpoints 166 167* (3.0) Extract is available as a top-level query operator, useful for selecting only 168 certain fields from a response. See the [documentation on the extract operator](../../../api/query/v4/ast.markdown#extract) for more information. 169 170* (2.2.0) The `in` and `extract` operators have been changed to accept multiple fields, 171 allowing more concise subquerying as explained [here](https://github.com/puppetlabs/puppetdb/pull/1053). 172 173### /pdb/query/v4/events 174 175* (3.0) The v4 events endpoint does not require a query parameter, so 176 `/pdb/query/v4/events` is now a valid query. See the 177 [events endpoint documentation](../../../api/query/v4/events.markdown#pdbqueryv4events) 178 for more information. 179 180### /pdb/query/v4/reports 181 182* (3.0) The response of the reports endpoint includes the new fields `noop`, 183 `environment`, `status`, `resource_events`, `logs`, and `metrics`. For more information, see the 184 [documentation on the reports endpoint](../../../api/query/v4/reports.markdown). For comparison, see 185 [an example of the new format](../../../api/query/v4/reports.markdown#examples), and 186 [an example of the old format](https://github.com/puppetlabs/puppetdb/blob/doc-2.3/documentation/api/query/v3/reports.markdown#response-format) (PuppetDB 2.3 docs). 187 188* (3.0) The reports endpoint takes a `latest_report?` query to return only reports 189 associated with the most recent puppet run for their nodes. Similar to the 190 corresponding events query, there is no corresponding field in the response. 191 For more information, see the 192 [documentation on the report query fields](../../../api/query/v4/reports.markdown#query-fields). 193 194### /pdb/query/v4/catalogs 195 196* (3.0) The v4 catalogs endpoint is queryable like the other 197 endpoints, whereas before it could only return a catalog for a 198 single host. The old query format (`/pdb/query/v4/catalogs/myhost`) 199 still works as before, but `/pdb/query/v4/catalogs` returns results 200 too. For more information, see the 201 [catalog query examples](catalogs.markdown#examples). 202 203### Operators 204 205* (2.2.0) The new `select_fact_contents` subquery operator allows for filtering the 206 results of other endpoints based on detailed queries about structured fact 207 values. This is exhibited on the bottom of the 208 [subquery examples documentation](../../../api/query/v4/ast.markdown#explicit-subquery-examples). 209 210* (2.2.0) We have added the regexp array match operator `~>` for querying fact paths on 211 the `fact-contents` or `fact-paths endpoints`. This is documented with the other 212 [operators](../../../api/query/v4/ast.markdown#regexp-array-match). 213 An example of usage is given at the bottom of the 214 [subquery examples page](../../../api/query/v4/ast.markdown#explicit-subquery-examples). 215 216* (3.0) We have added the `group_by` and `function` operators, as well as 217 support for the `count` function. For more information, see the 218 [operators documentation](../../../api/query/v4/ast.markdown#function). 219