influxdata / influxdata/kapacitor

Improve InfluxQL node documentation

Open
#1,205 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
2.4k
Forks
479
Avg merge
4d 16h
Merged PRs (30d)
4

Description

There are several places in the documentation where a chaining method is documented as operating on a point, but has a field as an argument, with no explanation why.

For example:
![image](https://cloud.githubusercontent.com/assets/1826947/23046505/ef491dbe-f477-11e6-8d21-9205741de456.png)

If this counts the number of points, what is it doing with the field parameter?

From a quick skim through the docs. These methods all have this documentation issue:

* count
* elapsed
* first
* last

----

![image](https://cloud.githubusercontent.com/assets/1826947/23046705/2eae1b66-f479-11e6-84a2-d7c59f78f37b.png)

This should read `|Percentile(...`. It's a chaining method, not a property.

----
![image](https://cloud.githubusercontent.com/assets/1826947/23046772/9e28556a-f479-11e6-897a-bec0b9158f48.png)

Should probably read something closer to: "Produce batch of points with distinct values for the specified field"

----
![image](https://cloud.githubusercontent.com/assets/1826947/23046790/bbd46bb2-f479-11e6-9360-0d73e0ea4e9a.png)

In addition to the earlier issue of why does it need `field`, what is `unit` used for?
We should clarify that it defines the resulting unit of the output value. Or that more accurately, the output value is a multiple of the given value (seeing as something like `2s` is a valid value, but is a little confusing to think of as a "unit").

----
![image](https://cloud.githubusercontent.com/assets/1826947/23046873/22b0fcec-f47a-11e6-8681-496bebb8cc61.png)

Should probably read closer to "Compute the difference between the field's value in adjacent points".

----

The "selector" methods return a InfluxQLNode. This is a somewhat confusing as InfluxQLNode has a `.As()` property, which doesn't make much sense here. `.As()` sets the name of a computed field. What is it going to do on a selected point?

----

Several of the methods operate on consecutive points, such as `difference()` & `derivative()`. What happens when they receive a point for which the given field is missing/null? Do they just skip the point and compute the difference/derivative between the last point where the given field was non-null?

What about `mean()`? Does it treat the a point with the null field as 0, or does it skip it? Meaning does `1, 2, null, 4` result in 1.75, or 2.333?

----

In general I think the documentation just needs to be a little less terse. Pretty much all of the above issues are just because of terseness. Documentation other than the mentioned issues could also benefit from a little more verbosity.

Contributor guide

Open the contributing guide

Research direction

The issue names the InfluxQL node documentation and the methods count, elapsed, first, last, percentile, distinct, derivative, difference, and mean, but no file or test. Start by locating those method descriptions and verify their documented arguments and null-value behavior; done means the chaining syntax, field and unit semantics, and output behavior are explained consistently.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.