Skip to content

Commit

Permalink
rewrite examples to use the test data source (#51)
Browse files Browse the repository at this point in the history
  • Loading branch information
@retzkek
retzkek authored Mar 16, 2021
1 parent 5821362 commit 42e8d7e
Show file tree
Hide file tree
Showing 2 changed files with 148 additions and 132 deletions.
140 changes: 74 additions & 66 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@ annotations, and dashboard variables.
object at that path is an array it will be iterated over, with each object added
as a row in the data frame, otherwise the result object will be the only row.
- Can be separated by commas to use multiple data paths
- Timeseries data requires a field named `Time` containing the timestamp in a
format that can be parsed by `moment()` (e.g. ISO8601).
- Timeseries data must include a timestamp field under the data path, default
`Time`, in [ISO8601](https://momentjs.com/docs/#/parsing/string/) or a
configurable [custom
format](https://momentjs.com/docs/#/parsing/string-format/).
- Nested types will be flattened into dot-delimited fields.
- Grafana variables should be substituted directly in the query (instead of
using GraphQL variables). The dashboard time ranges are available in the
Expand All @@ -33,100 +35,108 @@ annotations, and dashboard variables.

# Examples

Below are some example queries demonstrating how to use the plugin. See the
[project wiki](https://github.com/fifemon/graphql-datasource/wiki) for further
examples and tutorials.
Below are some example queries demonstrating how to use the plugin, using the
[FIFEMon GraphQL test source
server](https://github.com/fifemon/graphql-test-source/), which also includes a
[dashboard](https://raw.githubusercontent.com/fifemon/graphql-test-source/master/doc/graphql-test-dashboard.json)
demonstrating these queries.

## Basic timeseries

```graphql
query {
submissions(user: "$user", from: "$__from", to: "$__to") {
Time: submitTime
idle
running
completed
data: simple_series(from: "${__from:date:iso}", to: "${__to:date:iso}", interval_ms: $__interval_ms) {
Time: timestamp
value
}
}
```

- Data path: `submissions`

Note the use of the global `$__from` and `$__to` variables to insert the
dashboard time range into the query, alongside a dashboard variable `$user`.
dashboard time range into the query and the use of `$__interval_ms` to specify
the appropriate time interval for the graph.

## Custom time format

```graphql
query {
simple_series(
from: "${__from:date:iso}"
to: "${__to:date:iso}"
interval_ms: $__interval_ms
format: "MM.dd.uuuu HHmmss"
) {
timestamp
value
}
}
```

- Data path: `simple_series`
- Time path: `timestamp`
- Time format: `MM.DD.YYYY HHmmss`

## Alias and group by

```graphql
query {
data: queryAll(from: "$__from", to: "$__to", sourceId: "default") {
batteryVoltage {
Time: dateMillis
packet {
batteryVoltage
identifier {
representation
}
identityInfo {
displayName
}
}
complex_series(from: "${__from:date:iso}", to: "${__to:date:iso}", interval_ms: $__interval_ms) {
time {
timestamp
}
value
group {
id
name
}
}
}
```

- Data path: `data.batteryVoltage`
- Group by: `packet.identifier.representation`
- Alias by: `$field_packet.identityInfo.displayName`
- Data path: `complex_series`
- Time path: `time.timestamp`
- Group by: `group.id`
- Alias by: `$field_group.name`

In the above example, "Group by" and "Alias by" are defined. "Group by" allows
you to split up an array of data into multiple data points. "Alias by" is used
as the name of the data point. You can make alias use text from the query or
even the field name by using `$field_<your.field.name>` for the value of the
field,
was used, it would be replaced by "batteryVoltage" because that's the name of
the field. If `$field_identityInfo.displayName` was used, it would be replaced
with the value of displayName. Using `$fieldName` can be useful if you're
querying multiple numeric fields that you want displayed in your graph.
field, or `$fieldName` for the name of the field. If `$fieldName` was used, it
would be replaced by "value" because that's the name of the field. If
`$field_group.name` was used, it would be replaced with the value
of `name`. Using `$fieldName` can be useful if you're querying multiple
numeric fields that you want displayed in your graph.

## Annotations

```graphql
query {
server1: queryEvents(from: "$__from", to: "$__to", server: "server1") {
birthdayEvent {
Time: dateMillis
person {
fullName
}
}
}
server2: queryEvents(from: "$__from", to: "$__to", server: "server2") {
birthdayEvent {
Time: dateMillis
person {
fullName
}
}
events(from: "${__from:date:iso}", to: "${__to:date:iso}", end: true) {
timestamp
end_timestamp
name
description
tags
}
}
```

- Data path: `server1.birthdayEvent, server2.birthdayEvent`
- Title: `Birthday yay!`
- Text: `$field_person.fullName`
- Data path: `events`
- Time path: `timestamp`
- End time path: `end_timestamp`
- Title: `$field_name`
- Text: `$field_description`
- Tags: `tag1, tag2`

The above annotation example is similar to regular queries. You must have a
`Time` field and are able to define a data path. Similar to the last example,
you can also substitute values into the title, text, and tags by using
`$field_<field name>`. By using `$field_person.fullName` as the text, the text
in this annotation will be the person's full name. Tags are separated by commas.
The above example has two tags: "tag1" and "tag2". If a `TimeEnd` field is
present, the annotation will be shown over a period of time. You can also
separate the data path with commas to provide multiple data paths as shown with
both server1 and server2.
The above annotation example is similar to regular queries. You are able to
define a data path, time path, and time format. Similar to the last example, you
can also substitute values into the title, text, and tags by using
`$field_<field name>`. Tags are separated by commas. The above example has two
tags: "tag1" and "tag2".

If the optional end time field is defined and present, the annotation will be
shown over a period of time.

## Dashboard Variable Queries

Expand All @@ -138,13 +148,11 @@ the variable value list.

```graphql
query {
search(searchTerm: "$query") {
stations {
__value: primaryEvaId
__text: name
}
groups {
__value: id
__text: name
}
}
```

- Data path: `search.stations`
- Data path: `groups`
140 changes: 74 additions & 66 deletions dist/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@ annotations, and dashboard variables.
object at that path is an array it will be iterated over, with each object added
as a row in the data frame, otherwise the result object will be the only row.
- Can be separated by commas to use multiple data paths
- Timeseries data requires a field named `Time` containing the timestamp in a
format that can be parsed by `moment()` (e.g. ISO8601).
- Timeseries data must include a timestamp field under the data path, default
`Time`, in [ISO8601](https://momentjs.com/docs/#/parsing/string/) or a
configurable [custom
format](https://momentjs.com/docs/#/parsing/string-format/).
- Nested types will be flattened into dot-delimited fields.
- Grafana variables should be substituted directly in the query (instead of
using GraphQL variables). The dashboard time ranges are available in the
Expand All @@ -33,100 +35,108 @@ annotations, and dashboard variables.

# Examples

Below are some example queries demonstrating how to use the plugin. See the
[project wiki](https://github.com/fifemon/graphql-datasource/wiki) for further
examples and tutorials.
Below are some example queries demonstrating how to use the plugin, using the
[FIFEMon GraphQL test source
server](https://github.com/fifemon/graphql-test-source/), which also includes a
[dashboard](https://raw.githubusercontent.com/fifemon/graphql-test-source/master/doc/graphql-test-dashboard.json)
demonstrating these queries.

## Basic timeseries

```graphql
query {
submissions(user: "$user", from: "$__from", to: "$__to") {
Time: submitTime
idle
running
completed
data: simple_series(from: "${__from:date:iso}", to: "${__to:date:iso}", interval_ms: $__interval_ms) {
Time: timestamp
value
}
}
```

- Data path: `submissions`

Note the use of the global `$__from` and `$__to` variables to insert the
dashboard time range into the query, alongside a dashboard variable `$user`.
dashboard time range into the query and the use of `$__interval_ms` to specify
the appropriate time interval for the graph.

## Custom time format

```graphql
query {
simple_series(
from: "${__from:date:iso}"
to: "${__to:date:iso}"
interval_ms: $__interval_ms
format: "MM.dd.uuuu HHmmss"
) {
timestamp
value
}
}
```

- Data path: `simple_series`
- Time path: `timestamp`
- Time format: `MM.DD.YYYY HHmmss`

## Alias and group by

```graphql
query {
data: queryAll(from: "$__from", to: "$__to", sourceId: "default") {
batteryVoltage {
Time: dateMillis
packet {
batteryVoltage
identifier {
representation
}
identityInfo {
displayName
}
}
complex_series(from: "${__from:date:iso}", to: "${__to:date:iso}", interval_ms: $__interval_ms) {
time {
timestamp
}
value
group {
id
name
}
}
}
```

- Data path: `data.batteryVoltage`
- Group by: `packet.identifier.representation`
- Alias by: `$field_packet.identityInfo.displayName`
- Data path: `complex_series`
- Time path: `time.timestamp`
- Group by: `group.id`
- Alias by: `$field_group.name`

In the above example, "Group by" and "Alias by" are defined. "Group by" allows
you to split up an array of data into multiple data points. "Alias by" is used
as the name of the data point. You can make alias use text from the query or
even the field name by using `$field_<your.field.name>` for the value of the
field,
was used, it would be replaced by "batteryVoltage" because that's the name of
the field. If `$field_identityInfo.displayName` was used, it would be replaced
with the value of displayName. Using `$fieldName` can be useful if you're
querying multiple numeric fields that you want displayed in your graph.
field, or `$fieldName` for the name of the field. If `$fieldName` was used, it
would be replaced by "value" because that's the name of the field. If
`$field_group.name` was used, it would be replaced with the value
of `name`. Using `$fieldName` can be useful if you're querying multiple
numeric fields that you want displayed in your graph.

## Annotations

```graphql
query {
server1: queryEvents(from: "$__from", to: "$__to", server: "server1") {
birthdayEvent {
Time: dateMillis
person {
fullName
}
}
}
server2: queryEvents(from: "$__from", to: "$__to", server: "server2") {
birthdayEvent {
Time: dateMillis
person {
fullName
}
}
events(from: "${__from:date:iso}", to: "${__to:date:iso}", end: true) {
timestamp
end_timestamp
name
description
tags
}
}
```

- Data path: `server1.birthdayEvent, server2.birthdayEvent`
- Title: `Birthday yay!`
- Text: `$field_person.fullName`
- Data path: `events`
- Time path: `timestamp`
- End time path: `end_timestamp`
- Title: `$field_name`
- Text: `$field_description`
- Tags: `tag1, tag2`

The above annotation example is similar to regular queries. You must have a
`Time` field and are able to define a data path. Similar to the last example,
you can also substitute values into the title, text, and tags by using
`$field_<field name>`. By using `$field_person.fullName` as the text, the text
in this annotation will be the person's full name. Tags are separated by commas.
The above example has two tags: "tag1" and "tag2". If a `TimeEnd` field is
present, the annotation will be shown over a period of time. You can also
separate the data path with commas to provide multiple data paths as shown with
both server1 and server2.
The above annotation example is similar to regular queries. You are able to
define a data path, time path, and time format. Similar to the last example, you
can also substitute values into the title, text, and tags by using
`$field_<field name>`. Tags are separated by commas. The above example has two
tags: "tag1" and "tag2".

If the optional end time field is defined and present, the annotation will be
shown over a period of time.

## Dashboard Variable Queries

Expand All @@ -138,13 +148,11 @@ the variable value list.

```graphql
query {
search(searchTerm: "$query") {
stations {
__value: primaryEvaId
__text: name
}
groups {
__value: id
__text: name
}
}
```

- Data path: `search.stations`
- Data path: `groups`

0 comments on commit 42e8d7e

Please sign in to comment.