| 1 | # Query formatting |
| 2 | |
| 3 | API data queries need to be formatted before returned to the caller. |
| 4 | Using API parameters, the caller may define the format he/she wishes to get back. |
| 5 | |
| 6 | The following formats are supported: |
| 7 | |
| 8 | | format|module|content type|description| |
| 9 | |:----:|:----:|:----------:|:----------| |
| 10 | | `array`|[ssv](/src/web/api/formatters/ssv/README.md)|application/json|a JSON array| |
| 11 | | `csv`|[csv](/src/web/api/formatters/csv/README.md)|text/plain|a text table, comma separated, with a header line (dimension names) and `\r\n` at the end of the lines| |
| 12 | | `csvjsonarray`|[csv](/src/web/api/formatters/csv/README.md)|application/json|a JSON array, with each row as another array (the first row has the dimension names)| |
| 13 | | `datasource`|[json](/src/web/api/formatters/json/README.md)|application/json|a Google Visualization Provider `datasource` javascript callback| |
| 14 | | `datatable`|[json](/src/web/api/formatters/json/README.md)|application/json|a Google `datatable`| |
| 15 | | `html`|[csv](/src/web/api/formatters/csv/README.md)|text/html|an html table| |
| 16 | | `json`|[json](/src/web/api/formatters/json/README.md)|application/json|a JSON object| |
| 17 | | `jsonp`|[json](/src/web/api/formatters/json/README.md)|application/json|a JSONP javascript callback| |
| 18 | | `markdown`|[csv](/src/web/api/formatters/csv/README.md)|text/plain|a markdown table| |
| 19 | | `ssv`|[ssv](/src/web/api/formatters/ssv/README.md)|text/plain|a space separated list of values| |
| 20 | | `ssvcomma`|[ssv](/src/web/api/formatters/ssv/README.md)|text/plain|a comma separated list of values| |
| 21 | | `tsv`|[csv](/src/web/api/formatters/csv/README.md)|text/plain|a TAB delimited `csv` (MS Excel flavor)| |
| 22 | |
| 23 | For examples of each format, check the relative module documentation. |
| 24 | |
| 25 | ## Metadata with the `jsonwrap` option |
| 26 | |
| 27 | All data queries can be encapsulated to JSON object having metadata about the query and the results. |
| 28 | |
| 29 | This is done by adding the `options=jsonwrap` to the API URL (if there are other `options` append |
| 30 | `,jsonwrap` to the existing ones). |
| 31 | |
| 32 | This is such an object: |
| 33 | |
| 34 | ```bash |
| 35 | # curl -Ss 'https://registry.my-netdata.io/api/v1/data?chart=system.cpu&after=-3600&points=6&group=average&format=csv&options=nonzero,jsonwrap' |
| 36 | { |
| 37 | "api": 1, |
| 38 | "id": "system.cpu", |
| 39 | "name": "system.cpu", |
| 40 | "view_update_every": 600, |
| 41 | "update_every": 1, |
| 42 | "first_entry": 1540387074, |
| 43 | "last_entry": 1540647070, |
| 44 | "before": 1540647000, |
| 45 | "after": 1540644000, |
| 46 | "dimension_names": ["steal", "softirq", "user", "system", "iowait"], |
| 47 | "dimension_ids": ["steal", "softirq", "user", "system", "iowait"], |
| 48 | "latest_values": [0, 0.2493766, 1.745636, 0.4987531, 0], |
| 49 | "view_latest_values": [0.0158314, 0.0516506, 0.866549, 0.7196127, 0.0050002], |
| 50 | "dimensions": 5, |
| 51 | "points": 6, |
| 52 | "format": "csv", |
| 53 | "result": "time,steal,softirq,user,system,iowait\n2018-10-27 13:30:00,0.0158314,0.0516506,0.866549,0.7196127,0.0050002\n2018-10-27 13:20:00,0.0149856,0.0529183,0.8673155,0.7121144,0.0049979\n2018-10-27 13:10:00,0.0137501,0.053315,0.8578097,0.7197613,0.0054209\n2018-10-27 13:00:00,0.0154252,0.0554688,0.899432,0.7200638,0.0067252\n2018-10-27 12:50:00,0.0145866,0.0495922,0.8404341,0.7011141,0.0041688\n2018-10-27 12:40:00,0.0162366,0.0595954,0.8827475,0.7020573,0.0041636\n", |
| 54 | "min": 0, |
| 55 | "max": 0 |
| 56 | } |
| 57 | ``` |
| 58 | |
| 59 | ## Downloading data query result files |
| 60 | |
| 61 | Following the [Google Visualization Provider guidelines](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source), |
| 62 | Netdata supports parsing `tqx` options. |
| 63 | |
| 64 | Using these options, any Netdata data query can instruct the web browser to download |
| 65 | the result and save it under a given filename. |
| 66 | |
| 67 | For example, to download a CSV file with CPU utilization of the last hour, |
| 68 | [click here](https://registry.my-netdata.io/api/v1/data?chart=system.cpu&after=-3600&format=csv&options=nonzero&tqx=outFileName:system+cpu+utilization+of+the+last_hour.csv). |
| 69 | |
| 70 | This is done by appending `&tqx=outFileName:FILENAME` to any data query. |
| 71 | The output will be in the format given with `&format=`. |
| 72 | |
| 73 |