influxdata / docs-v2

InfluxData Documentation that covers InfluxDB Cloud, InfluxDB OSS 2.x, InfluxDB OSS 1.x, InfluxDB Enterprise, Telegraf, Chronograf, Kapacitor, and Flux.
https://docs.influxdata.com
MIT License
72 stars 269 forks source link

Add more information about options in the `/api/v2/query` payload #3748

Open sanderson opened 2 years ago

sanderson commented 2 years ago

Working through Flux HTTP examples with @rickspencer3, we found that the description for the dialect payload option on /api/v2/query doesn't really help users all that much. We need to update the descriptions in the openAPI spec to be more clear and help guide users.

One specific change we need to make is to call out (in dialect description) that to return annotated CSV in a format that can be directly written back to InfluxDB, users must include the following in their request body:

{
    "query": "...",
    "dialect": {
        "annotations": [
            "group",
            "datatype",
            "default"
        ]
    }
}

Potentially, add a request payload example that includes group, datatype, and default specifically for users who intend to use InfluxDB to consume the response.

Relevant URLs

-https://docs.influxdata.com/influxdb/v2.1/api/#operation/PostQuery

rickspencer3 commented 2 years ago

I think it would also be useful to show how to use csv.from() on the results.