Merge pull request #458 from influxdata/CSV
Add CSV example with all required annotationspull/463/head
kelseiv
GitHub
commit
912b589c8f
|
|
@ -13,6 +13,7 @@ Annotated CSV (comma-separated values) format is used to encode HTTP responses a
|
|||
CSV tables must be encoded in UTF-8 and Unicode Normal Form C as defined in [UAX15](http://www.unicode.org/reports/tr15/). Line endings must be CRLF (Carriage Return Line Feed) as defined by the `text/csv` MIME type in [RFC 4180](https://tools.ietf.org/html/rfc4180).
|
||||
|
||||
## Examples
|
||||
|
||||
In this topic, you'll find examples of valid CSV syntax for responses to the following query:
|
||||
|
||||
```js
|
||||
|
|
@ -23,12 +24,15 @@ from(bucket:"mydb/autogen")
|
|||
```
|
||||
|
||||
## CSV response format
|
||||
|
||||
Flux supports encodings listed below.
|
||||
|
||||
### Tables
|
||||
|
||||
A table may have the following rows and columns.
|
||||
|
||||
#### Rows
|
||||
|
||||
- **Annotation rows**: describe column properties.
|
||||
|
||||
- **Header row**: defines column labels (one header row per table).
|
||||
|
|
@ -36,6 +40,7 @@ A table may have the following rows and columns.
|
|||
- **Record row**: describes data in the table (one record per row).
|
||||
|
||||
##### Example
|
||||
|
||||
Encoding of a table with and without a header row.
|
||||
|
||||
{{< code-tabs-wrapper >}}
|
||||
|
|
@ -63,6 +68,7 @@ my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,
|
|||
{{< /code-tabs-wrapper >}}
|
||||
|
||||
#### Columns
|
||||
|
||||
In addition to the data columns, a table may include the following columns:
|
||||
|
||||
- **Annotation column**: Only used in annotation rows. Always the first column. Displays the name of an annotation. Value can be empty or a supported [annotation](#annotations). You'll notice a space for this column for the entire length of the table, so rows appear to start with `,`.
|
||||
|
|
@ -72,6 +78,7 @@ In addition to the data columns, a table may include the following columns:
|
|||
- **Table column**: Contains a unique ID for each table in a result.
|
||||
|
||||
### Multiple tables and results
|
||||
|
||||
If a file or data stream contains multiple tables or results, the following requirements must be met:
|
||||
|
||||
- A table column indicates which table a row belongs to.
|
||||
|
|
@ -82,6 +89,7 @@ If a file or data stream contains multiple tables or results, the following requ
|
|||
- Each new table boundary starts with new annotation and header rows.
|
||||
|
||||
##### Example
|
||||
|
||||
Encoding of two tables in the same result with the same schema (header row) and different schema.
|
||||
|
||||
{{< code-tabs-wrapper >}}
|
||||
|
|
@ -119,6 +127,7 @@ my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,west,
|
|||
{{< /code-tabs-wrapper >}}
|
||||
|
||||
### Dialect options
|
||||
|
||||
Flux supports the following dialect options for `text/csv` format.
|
||||
|
||||
| Option | Description| Default |
|
||||
|
|
@ -130,7 +139,8 @@ Flux supports the following dialect options for `text/csv` format.
|
|||
| **commentPrefix** | String prefix to identify a comment. Always added to annotations. |`#`|
|
||||
|
||||
### Annotations
|
||||
Annotation rows are optional, describe column properties, and start with `#` (or commentPrefix value). The first column in an annotation row always contains the annotation name. Subsequent columns contain annotation values as shown in the table below.
|
||||
|
||||
Annotation rows describe column properties, and start with `#` (or commentPrefix value). The first column in an annotation row always contains the annotation name. Subsequent columns contain annotation values as shown in the table below.
|
||||
|
||||
|Annotation name | Values| Description |
|
||||
| :-------- | :--------- | :-------|
|
||||
|
|
@ -138,67 +148,30 @@ Annotation rows are optional, describe column properties, and start with `#` (or
|
|||
| **group** | boolean flag `true` or `false` | Indicates the column is part of the group key.|
|
||||
| **default** | a [valid data type](#valid-data-types) |Value to use for rows with an empty string value.|
|
||||
|
||||
##### Example
|
||||
Encoding of datatype and group annotations for two tables.
|
||||
|
||||
{{< code-tabs-wrapper >}}
|
||||
{{% code-tabs %}}
|
||||
[Datatype annotation](#)
|
||||
[Group annotation](#)
|
||||
[Datatype and group annotations](#)
|
||||
{{% /code-tabs %}}
|
||||
|
||||
{{% code-tab-content %}}
|
||||
```js
|
||||
#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,string,string,double
|
||||
,result,table,_start,_stop,_time,region,host,_value
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,west,A,62.73
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,west,B,12.83
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,west,C,51.62
|
||||
```
|
||||
{{% /code-tab-content %}}
|
||||
|
||||
{{% code-tab-content %}}
|
||||
```js
|
||||
#group,false,false,true,true,false,true,false,false
|
||||
,result,table,_start,_stop,_time,region,host,_value
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,west,A,62.73
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,west,B,12.83
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,west,C,51.62
|
||||
```
|
||||
{{% /code-tab-content %}}
|
||||
|
||||
|
||||
{{% code-tab-content %}}
|
||||
```js
|
||||
#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,string,string,double
|
||||
,result,table,_start,_stop,_time,region,host,_value
|
||||
#group,false,false,true,true,false,true,false,false
|
||||
,result,table,_start,_stop,_time,region,host,_value
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,west,A,62.73
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,west,B,12.83
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,west,C,51.62
|
||||
```
|
||||
{{% /code-tab-content %}}
|
||||
{{< /code-tabs-wrapper >}}
|
||||
|
||||
|
||||
**Notes:**
|
||||
{{% note %}}
|
||||
To encode a table with its group key, the `datatype`, `group`, and `default` annotations must be included.
|
||||
|
||||
If a table has no rows, the `default` annotation provides the group key values.
|
||||
To encode a table with its group key, the `datatype`, `group`, and `default` annotations must be included. If a table has no rows, the `default` annotation provides the group key values.
|
||||
{{% /note %}}
|
||||
|
||||
##### Example
|
||||
|
||||
Example encoding of datatype, group, and default annotations.
|
||||
|
||||
```js
|
||||
import "csv"
|
||||
a = "#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,string,string,double
|
||||
#group,false,false,false,false,false,false,false,false
|
||||
#default,,,,,,,,
|
||||
,result,table,_start,_stop,_time,region,host,_value
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25
|
||||
,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,west,A,62.73
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,west,B,12.83
|
||||
,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,west,C,51.62
|
||||
"
|
||||
csv.from(csv:a) |> yield()
|
||||
```
|
||||
|
||||
### Valid data types
|
||||
|
||||
| Datatype | Flux type | Description |
|
||||
|
|
@ -213,6 +186,7 @@ If a table has no rows, the `default` annotation provides the group key values.
|
|||
| duration | duration | a length of time represented as an unsigned 64-bit integer number of nanoseconds |
|
||||
|
||||
## Errors
|
||||
|
||||
If an error occurs during execution, a table returns with:
|
||||
|
||||
- An error column that contains an error message.
|
||||
|
|
@ -225,6 +199,7 @@ If an error occurs:
|
|||
- After partial results are sent to the client, the error is encoded as the next table and remaining results are discarded. In this case, the HTTP status code remains 200 OK.
|
||||
|
||||
##### Example
|
||||
|
||||
Encoding for an error with the datatype annotation:
|
||||
```js
|
||||
#datatype,string,long
|
||||
|
|
|
|||
Loading…
Reference in New Issue