feat: add support for Unit conversion on Custom Time Series Queries (#…

…319)

* update requirements

* add support for targetUnit and targetUnitSystem

* update query field

* small styling of common editors

* update documentation

* add some extra fields

* patch deprecated method

* Revert "patch deprecated method"

This reverts commit e3d0bd8.

* update documentation

* bump version and add changelog

* update help text

* Update yarn.lock

---------

Co-authored-by: Ivan Polomani <[email protected]>
Co-authored-by: cognite-bulldozer[bot] <51074376+cognite-bulldozer[bot]@users.noreply.github.com>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cognite/cognite-grafana-datasource",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Cognite Data Fusion datasource",
   "repository": "https://github.com/cognitedata/cognite-grafana-datasource",
   "author": "Cognite AS",
@@ -104,7 +104,7 @@
     "@grafana/schema": "^10.1.2",
     "@grafana/ui": "^10.1.2",
     "deepdash": "^4.5.4",
-    "eslint-plugin-jsdoc": "^40.1.1",
+    "eslint-plugin-jsdoc": "48.0.4",
     "graphql": "^16.6.0",
     "graphql-language-service": "^5.1.2",
     "graphql-tag": "^2.12.6",
@@ -116,4 +116,4 @@
     "react": "17.0.2",
     "react-dom": "17.0.2"
   }
-}
+}

src/cdf/types.ts

@@ -7,6 +7,7 @@ export interface Datapoint {
   isStep: boolean;
   isString: boolean;
   unit?: string;
+  unitExternalId?: string;
   datapoints: TimeSeriesDatapoint[] | TimeSeriesAggregateDatapoint[];
 }
 
@@ -68,6 +69,8 @@ export interface TimeseriesFilterRequestParams extends FilterRequestParams {
   unit?: string;
   isString?: boolean;
   isStep?: boolean;
+  unitExternalId?: string;
+  unitQuantity?: string;
   assetIds?: CogniteInternalId[];
   assetExternalIds?: CogniteExternallId[];
   rootAssetIds?: IdEither[];
@@ -98,21 +101,23 @@ export interface ExtractionPipelinesResponse {
   name: string;
   description: string;
   dataSetId?: number;
-  'data set'?: string;
+  "data set"?: string;
 }
 
-export interface ExtractionPipelinesWithRun extends ExtractionPipelinesResponse {
+export interface ExtractionPipelinesWithRun
+  extends ExtractionPipelinesResponse {
   runId: number;
   message: string;
   status: string;
 }
 export type EventsFilterTimeParams =
-  | Pick<EventsFilterRequestParams, 'activeAtTime'>
-  | Pick<EventsFilterRequestParams, 'startTime' | 'endTime'>;
-
+  | Pick<EventsFilterRequestParams, "activeAtTime">
+  | Pick<EventsFilterRequestParams, "startTime" | "endTime">;
 
 export interface EventSortRequestParam {
-  property: string[], order?: 'asc' | 'desc', nulls?: 'first' | 'last' | 'auto'
+  property: string[];
+  order?: "asc" | "desc";
+  nulls?: "first" | "last" | "auto";
 }
 
 export interface FilterRequest<Filter, SortType = {}> extends Limit, Cursor {
@@ -141,6 +146,7 @@ export interface TimeSeriesResponseItem extends Resource {
   isString?: boolean;
   metadata?: Record<string, string>;
   unit?: string;
+  unitExternalId?: string;
   assetId?: string;
   isStep: boolean;
   source?: string;
@@ -178,11 +184,11 @@ export type Items<T = any> = {
 
 export type IdEither =
   | {
-      id: number;
-    }
+    id: number;
+  }
   | {
-      externalId: string;
-    };
+    externalId: string;
+  };
 
 export interface Range<T> {
   min?: T;
@@ -206,7 +212,7 @@ interface CogniteRelationshipAsset {
     path?: [
       {
         id: string | number;
-      }
+      },
     ];
   };
   parentId?: number;

src/components/commonEditors.tsx

@@ -25,8 +25,8 @@ const GranularityEditor = (props: SelectedProps) => {
       <div className="gf-form">
         <FormField
           label="Granularity"
-          labelWidth={6}
-          inputWidth={10}
+          labelWidth={7}
+          inputWidth={6}
           onChange={({ target }) => onQueryChange({ granularity: target.value })}
           value={query.granularity}
           placeholder="default"
@@ -59,8 +59,8 @@ export const LabelEditor = (props: SelectedProps) => {
     <div className="gf-form gf-form--grow">
       <FormField
         label="Label"
-        labelWidth={6}
-        inputWidth={10}
+        labelWidth={5}
+        inputWidth={20}
         onChange={({ target }) => onQueryChange({ label: target.value })}
         value={query.label}
         placeholder="default"

src/components/queryEditor.tsx

@@ -9,6 +9,9 @@ import {
   Switch,
   AsyncSelect,
   Button,
+  InlineField,
+  InlineFieldRow,
+  Input
 } from '@grafana/ui';
 import { SelectableValue } from '@grafana/data';
 import { SystemJS } from '@grafana/runtime';
@@ -245,20 +248,24 @@ function CustomTab(props: SelectedProps & Pick<EditorProps, 'onRunQuery'>) {
 
   return (
     <>
-      <div className="gf-form">
-        <FormField
+      <InlineFieldRow>
+        <InlineField
           label="Query"
-          labelWidth={6}
-          inputWidth={30}
-          className="custom-query"
-          placeholder="ts{externalIdPrefix='PT_123'}"
-          onChange={({ target }) => setValue(target.value)}
-          onBlur={() => onQueryChange({ expr: value })}
-          value={value}
           tooltip="Click [?] button for help."
-        />
-        <Button variant="secondary" icon="question-circle" onClick={() => setShowHelp(!showHelp)} />
-      </div>
+          grow
+        >
+          <Input
+            type="text"
+            value={value}
+            placeholder="ts{externalIdPrefix='PT_123'}"
+            onChange={(d) => setValue(d.currentTarget.value)}
+            onBlur={() => onQueryChange({ expr: value })}
+          />
+        </InlineField>
+        <InlineField>
+          <Button variant="secondary" icon="question-circle" onClick={() => setShowHelp(!showHelp)} />
+        </InlineField>
+      </InlineFieldRow>
       <CommonEditors {...{ onQueryChange, query }} />
       {showHelp && <CustomQueryHelp onDismiss={() => setShowHelp(false)} />}
     </>

src/components/queryHelp.tsx

@@ -44,6 +44,17 @@ export const CustomQueryHelp = ({ onDismiss }: Pick<HelpParams, 'onDismiss'>) =>
     Example: <Code>{`sum(ts{metadata{type="TEMP"}}) - ts{id=12345678}`}</Code>
     <br />
     <br />
+    If a time series has a defined <Code>unitExternalId</Code>, you can convert its values to a different unit within the same quantity.
+    <br />
+    Example: <Code>{`ts{externalId='temperature_f_houston', targetUnit='temperature:deg_c'} + ts{id='123', targetUnitSystem='SI'}`}</Code>
+    <br />
+    - For each time series/aggregate, you may specify either <Code>targetUnit</Code> or <Code>targetUnitSystem</Code>, but not both. The chosen target unit must be compatible with the original unit.
+    <br />
+    - When querying data points using synthetic time series, the values will no longer retain their unit information. For instance, despite it not being physically accurate, it is possible to add values from a <b>temperature</b> time series to those from a <b>distance</b> time series.
+    <br />
+    - Finally, it is important to note that if you try to access the <Code>unit</Code> or <Code>unitExternalId</Code> properties of each time series on the <b>label</b> field, Grafana will return the original unit of the time series, not the unit associated with the data points.
+    <br />
+    <br />
     Templating is available by using the <Code>$variable_name</Code> syntax.
     <br />
     Example:{' '}