docs: update chart sorting control labels/descriptions (apache#1436)

Co-authored-by: John Bodley <[email protected]>
zhaoyongjie · Nov 24, 2021 · 63aa9b8 · 63aa9b8
1 parent 5acb5d7
commit 63aa9b8
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 13 deletions.
diff --git a/...et_ui/superset-ui/packages/superset-ui-chart-controls/src/shared-controls/dndControls.tsx b/...et_ui/superset-ui/packages/superset-ui-chart-controls/src/shared-controls/dndControls.tsx
@@ -25,7 +25,10 @@ export const dndGroupByControl: SharedControlConfig<'DndColumnSelect'> = {
   type: 'DndColumnSelect',
   label: t('Group by'),
   default: [],
-  description: t('One or many columns to group by'),
+  description: t(
+    'One or many columns to group by. High cardinality groupings should include a sort by metric ' +
+      'and series limit to limit the number of fetched and rendered series.',
+  ),
   mapStateToProps(state, { includeTime }) {
     const newState: ExtraControlProps = {};
     if (state.datasource) {
@@ -113,7 +116,10 @@ export const dnd_sort_by: SharedControlConfig<'DndMetricSelect'> = {
   type: 'DndMetricSelect',
   label: t('Sort by'),
   default: null,
-  description: t('Metric used to define the top series'),
+  description: t(
+    'Metric used to define the top series. Should be used in conjunction with the series or row ' +
+      'limit.',
+  ),
   mapStateToProps: ({ datasource }) => ({
     columns: datasource?.columns || [],
     savedMetrics: datasource?.metrics || [],

diff --git a/...superset_ui/superset-ui/packages/superset-ui-chart-controls/src/shared-controls/index.tsx b/...superset_ui/superset-ui/packages/superset-ui-chart-controls/src/shared-controls/index.tsx
@@ -102,7 +102,10 @@ const groupByControl: SharedControlConfig<'SelectControl', ColumnMeta> = {
   clearable: true,
   default: [],
   includeTime: false,
-  description: t('One or many columns to group by'),
+  description: t(
+    'One or many columns to group by. High cardinality groupings should include a sort by metric ' +
+      'and series limit to limit the number of fetched and rendered series.',
+  ),
   optionRenderer: c => <ColumnOption showType column={c} />,
   valueRenderer: c => <ColumnOption column={c} />,
   valueKey: 'column_name',
@@ -324,6 +327,10 @@ const row_limit: SharedControlConfig<'SelectControl'> = {
   validators: [legacyValidateInteger],
   default: 10000,
   choices: formatSelectOptions(ROW_LIMIT_OPTIONS),
+  description: t(
+    'Limits the number of rows that get displayed. Should be used in conjunction with a sort ' +
+      'by metric.',
+  ),
 };
 
 const limit: SharedControlConfig<'SelectControl'> = {
@@ -334,10 +341,11 @@ const limit: SharedControlConfig<'SelectControl'> = {
   choices: formatSelectOptions(SERIES_LIMITS),
   clearable: true,
   description: t(
-    'Limits the number of time series that get displayed. A sub query ' +
-      '(or an extra phase where sub queries are not supported) is applied to limit ' +
-      'the number of time series that get fetched and displayed. This feature is useful ' +
-      'when grouping by high cardinality dimension(s).',
+    'Limits the number of series that get displayed. Should be used in conjunction with a sort ' +
+      'by metric. A joined subquery (or an extra phase where subqueries are not supported) is ' +
+      'applied to limit the number of series that get fetched and rendered. This feature is ' +
+      'useful when grouping by high cardinality column(s) though does increase the query ' +
+      'complexity and cost.',
   ),
 };
 
@@ -348,18 +356,22 @@ const series_limit: SharedControlConfig<'SelectControl'> = {
   validators: [legacyValidateInteger],
   choices: formatSelectOptions(SERIES_LIMITS),
   description: t(
-    'Limits the number of series that get displayed. A sub query ' +
-      '(or an extra phase where sub queries are not supported) is applied to limit ' +
-      'the number of series that get fetched and displayed. This feature is useful ' +
-      'when grouping by high cardinality dimension(s).',
+    'Limits the number of series that get displayed. Should be used in conjunction with a sort ' +
+      'by metric. A joined subquery (or an extra phase where subqueries are not supported) is ' +
+      'applied to limit the number of series that get fetched and rendered. This feature is ' +
+      'useful when grouping by high cardinality column(s) though does increase the query ' +
+      'complexity and cost.',
   ),
 };
 
 const sort_by: SharedControlConfig<'MetricsControl'> = {
   type: 'MetricsControl',
-  label: t('Sort By'),
+  label: t('Sort by'),
   default: null,
-  description: t('Metric used to define the top series'),
+  description: t(
+    'Metric used to define the top series. Should be used in conjunction with the series or row ' +
+      'limit',
+  ),
   mapStateToProps: ({ datasource }) => ({
     columns: datasource?.columns || [],
     savedMetrics: datasource?.metrics || [],