Streaming: improve JSDocs for DataSourceAPI streaming support #18672
Conversation
| @@ -295,7 +313,7 @@ export interface ExploreStartPageProps { | |||
| */ | |||
| export type LegacyResponseData = TimeSeries | TableData | any; | |||
|
|
|||
| export type DataQueryResponseData = DataFrameDTO | LegacyResponseData; | |||
| export type DataQueryResponseData = DataFrame | DataFrameDTO | LegacyResponseData; | |||
There was a problem hiding this comment.
unrelated... but I added it while I'm looking
There was a problem hiding this comment.
Shouldn't it be DataFrameHelper as well?
There was a problem hiding this comment.
no, DataFrameHelper implements DataFrame -- it is just a helper ;)
* grafana/master: Plugins: better warning when plugins fail to load (grafana#18671)
| * 4. {key:K2, data:[C4]} >> PanelData: [A,B3,C4] | ||
| * | ||
| * NOTE: that PanelData will report a `Done` state until all | ||
| * unique keys have returned with either `Error` or `Done` state. |
There was a problem hiding this comment.
Whoa, are you saying that this is basically a stream of streams that you have to manually check by the key? Honestly did not see any code like that so far so not sure what to make from this. It seems like all of this is meant not to be used directly but only through PanelQueryRunner or something but that isn't the case right now so all these assumptions could be broken somewhere.
There was a problem hiding this comment.
assumptions could be broken
well obviously!
stream of streams
remember that the query argument is not a single query. it is a request with a query[] (targets), given that each query can return an array of data, that is how this mess gets made
| * then you can ignore the `observer` entirely. | ||
| * | ||
| * When streaming behavior is required, the Promise can return at any time | ||
| * with empty or partial data in the response and optionally a state. |
There was a problem hiding this comment.
This I think is broken here https://github.com/grafana/grafana/pull/16676/files#r316658833. even though that is older PR I feel like these kind of errors are too easy to make here.
| * Data may not be known yet | ||
| * The streaming events return entire DataFrames. The DataSource | ||
| * sending the events is responcible for truncating any growing lists | ||
| * most likely to the requested `maxDataPoints` |
There was a problem hiding this comment.
No idea here why this is array of dataframes and not just a dataframe. At least on Explore side this seems to be flattened anyway.
There was a problem hiding this comment.
a query often returns many DataFrames. and again remember, the existing query request contains a list of queries, not a single query
There was a problem hiding this comment.
This cannot be flattened in Explore, as a time series is presented as a single DataFrame (with time and value field), and Explore needs to show more than one time series :) A single query can return many series (explore also supports multiple queries which of course can return multiple series (ie DataFrames)
Co-Authored-By: Hugo Häggmark <hugo.haggmark@gmail.com>
Co-Authored-By: Hugo Häggmark <hugo.haggmark@gmail.com>
|
@aocenas I added these docs as it defines the current behavior, I'll take a stab at an updated API that incorporates your feedback |
* grafana/master: Streaming: improve JSDocs for DataSourceAPI streaming support (grafana#18672)
* grafana/master: Streaming: improve JSDocs for DataSourceAPI streaming support (grafana#18672) TimeSrv: Enable value time windowing in TimeSrv (grafana#18636) Explore: Fixes so Show context shows results again (grafana#18675) Graph: Updated y-axis ticks test dashboard (grafana#18677) Add typings to package.json in packages (grafana#18640) Plugins: better warning when plugins fail to load (grafana#18671)
* grafana/master: Heatmap: Add Cividis and Turbo color schemes (grafana#18710) Units: add counts/sec (cps) and counts/min (cpm) in Throughput (grafana#18702) Dev Docker: Use golang:1.12.9-alpine to prevent glibc mismatch. (grafana#18701) Docs: Fix broken link for the Grafana on RHEL or Ubuntu tutorial (grafana#18697) Fixes several usability issues with QueryField component (grafana#18681) convert teams section of user profile to react (grafana#18633) Singlestat/Gauge/BarGauge: Improvements to decimals logic and added test dashboard (grafana#18676) Emails: Change text (grafana#18683) Streaming: improve JSDocs for DataSourceAPI streaming support (grafana#18672) TimeSrv: Enable value time windowing in TimeSrv (grafana#18636) Explore: Fixes so Show context shows results again (grafana#18675) Graph: Updated y-axis ticks test dashboard (grafana#18677) Add typings to package.json in packages (grafana#18640) Plugins: better warning when plugins fail to load (grafana#18671) SingleStat2: save options to defaults not override (grafana#18666) Packages: Fix path import from grafana/data (grafana#18667)
* grafana/master: @grafana/data: improve the CircularVector api (grafana#18716) QueryEditor: check if optional func toggleEditorMode is provided (grafana#18705) Emails: remove the yarn.lock (grafana#18724) OAuth: Support JMES path lookup when retrieving user email (grafana#14683) Emails: resurrect template notification (grafana#18686) Email: add reply-to and direct attachment (grafana#18715) Dashboard: Adds Logs Panel (alpha) as visualization option for Dashboards (grafana#18641) Heatmap: Add Cividis and Turbo color schemes (grafana#18710) Units: add counts/sec (cps) and counts/min (cpm) in Throughput (grafana#18702) Dev Docker: Use golang:1.12.9-alpine to prevent glibc mismatch. (grafana#18701) Docs: Fix broken link for the Grafana on RHEL or Ubuntu tutorial (grafana#18697) Fixes several usability issues with QueryField component (grafana#18681) convert teams section of user profile to react (grafana#18633) Singlestat/Gauge/BarGauge: Improvements to decimals logic and added test dashboard (grafana#18676) Emails: Change text (grafana#18683) Streaming: improve JSDocs for DataSourceAPI streaming support (grafana#18672) TimeSrv: Enable value time windowing in TimeSrv (grafana#18636) Explore: Fixes so Show context shows results again (grafana#18675) Graph: Updated y-axis ticks test dashboard (grafana#18677) Add typings to package.json in packages (grafana#18640)
After discussing streaming support with @aocenas, it is clear we are missing good docs somewhere :)
This is an attempt to add better JSDocs. We likely need a blog post and more, but I hope to do that when we have a more coherent streaming solution. ie, same thing works in grafana and explore