From 34e9df5eebe01bc57fd1dfafb318d149688ca395 Mon Sep 17 00:00:00 2001
From: Elwyn Benson <ebenson@gitlab.com>
Date: Mon, 22 Apr 2024 20:31:38 +0000
Subject: [PATCH] Add documentation for analytics natural language querying

---
 doc/user/ai_features.md                       |  2 +
 doc/user/analytics/analytics_dashboards.md    | 41 +++++++++++++++++++
 .../ai_cube_query_generator.vue               | 20 ++++++++-
 .../ai_cube_query_generator_spec.js           | 10 +++++
 4 files changed, 71 insertions(+), 2 deletions(-)

diff --git a/doc/user/ai_features.md b/doc/user/ai_features.md
index 2606416dc46d7..d1ded1d64b47d 100644
--- a/doc/user/ai_features.md
+++ b/doc/user/ai_features.md
@@ -33,6 +33,7 @@ GitLab is [transparent](https://handbook.gitlab.com/handbook/values/#transparenc
 | Helps you understand code by explaining it in English language. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=1izKaLmmaCA) | [Code explanation](#explain-code-in-the-web-ui-with-code-explanation) | **Tier:** Ultimate <br>**Offering:** GitLab.com <br>**Status:** Experiment |
 | Assists you in determining the root cause for a pipeline failure and failed CI/CD build. | [Root cause analysis](#root-cause-analysis) | **Tier:** Ultimate <br>**Offering:** GitLab.com <br>**Status:** Experiment |
 | Assists you with predicting productivity metrics and identifying anomalies across your software development lifecycle. | [Value stream forecasting](#forecast-deployment-frequency-with-value-stream-forecasting) | **Tier:** Ultimate <br>**Offering:** GitLab.com, Self-managed, GitLab Dedicated <br>**Status:** Experiment |
+| Processes and responds to your questions about your application's usage data. | [Product Analytics](analytics/analytics_dashboards.md#generate-a-custom-visualization-with-gitlab-duo)             | **Tier:** Ultimate <br>**Offering:** GitLab.com <br>**Status:** Experiment |
 
 ## Controlling GitLab Duo features
 
@@ -329,6 +330,7 @@ language model referenced above.
 | [GitLab Duo Chat](gitlab_duo_chat.md) | Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model)    Vertex AI Codey [`textembedding-gecko`](https://cloud.google.com/vertex-ai/generative-ai/docs/embeddings/get-text-embeddings) |
 | [Root cause analysis](#root-cause-analysis) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text) |
 | [Value stream forecasting](#forecast-deployment-frequency-with-value-stream-forecasting) | Statistical forecasting |
+| [Product analytics](analytics/analytics_dashboards.md#generate-a-custom-visualization-with-gitlab-duo) | Vertex AI Codey [`codechat-bison`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-chat) |
 
 ## Data usage
 
diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md
index 4173c73b26272..049abe9cc08b2 100644
--- a/doc/user/analytics/analytics_dashboards.md
+++ b/doc/user/analytics/analytics_dashboards.md
@@ -88,6 +88,7 @@ This feature is only compatible with the [product analytics](../product_analytic
 You can use the dashboard designer to:
 
 - [Create custom visualizations](#create-a-custom-visualization).
+- [Generate custom visualizations with GitLab Duo](#generate-a-custom-visualization-with-gitlab-duo).
 - Explore available data.
 
 ## View project dashboards
@@ -291,6 +292,38 @@ To create a custom visualization:
 
 After you saved a visualization, you can add it to a new or existing custom dashboard in the same project.
 
+### Generate a custom visualization with GitLab Duo
+
+DETAILS:
+**Tier:** Ultimate
+**Offering:** GitLab.com
+**Status:** Experiment
+
+> - Introduced in GitLab 16.11 as an [Experiment](../../policy/experiment-beta-support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `generate_cube_query`. Disabled by default.
+
+Prerequisites:
+
+- The parent group of the project must have [experiment and beta features enabled](../group/manage.md#enable-experiment-and-beta-features).
+
+To generate a custom visualization with GitLab Duo using a natural language query:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Analyze > Analytics dashboards**.
+1. Select **Visualization designer**.
+1. In the **Visualization title** field, enter the name of your visualization.
+1. From the **Visualization type** dropdown list, select a visualization type.
+1. In the **Generate with GitLab Duo** section, enter your prompt. For example:
+
+   - _Daily sessions_
+   - _Number of unique users, grouped weekly_
+   - _Which are the most popular pages?_
+   - _How many unique users does each browser have?_
+
+1. Select **Generate with GitLab Duo**.
+1. Select **Save**.
+
+After you saved a visualization, you can add it to a new or existing custom dashboard in the same project.
+
 ## Troubleshooting
 
 ### `Something went wrong while loading the dashboard.`
@@ -311,3 +344,11 @@ If a dashboard panel displays an error message:
 - Check your [Cube query](../product_analytics/index.md#product-analytics-dashboards) and [visualization](../analytics/analytics_dashboards.md#define-a-chart-visualization)
   configurations, and make sure they are set up correctly.
 - For [product analytics](../product_analytics/index.md), also check that your visualization's Cube query is valid.
+
+### Generate visualization with GitLab Duo returns unexpected results
+
+If GitLab Duo doesn't return the expected or a useful result, try editing your query to:
+
+- Specify a date range. For example: _number of unique users in 2023 to 2024, grouped monthly_.
+- Use the same names for metrics and dimensions as shown in the visualization designer.
+For example: _returning users_ instead of _existing customers_.
diff --git a/ee/app/assets/javascripts/analytics/analytics_dashboards/components/visualization_designer/ai_cube_query_generator.vue b/ee/app/assets/javascripts/analytics/analytics_dashboards/components/visualization_designer/ai_cube_query_generator.vue
index e7584851e860b..6026c86c34195 100644
--- a/ee/app/assets/javascripts/analytics/analytics_dashboards/components/visualization_designer/ai_cube_query_generator.vue
+++ b/ee/app/assets/javascripts/analytics/analytics_dashboards/components/visualization_designer/ai_cube_query_generator.vue
@@ -1,11 +1,19 @@
 <script>
-import { GlButton, GlExperimentBadge, GlFormGroup, GlFormTextarea, GlIcon } from '@gitlab/ui';
+import {
+  GlButton,
+  GlExperimentBadge,
+  GlFormGroup,
+  GlFormTextarea,
+  GlIcon,
+  GlLink,
+} from '@gitlab/ui';
 import { v4 as uuidv4 } from 'uuid';
 
 import { confirmAction } from '~/lib/utils/confirm_via_gl_modal/confirm_action';
 import { fetchPolicies } from '~/lib/graphql';
 import { convertToGraphQLId } from '~/graphql_shared/utils';
 import { TYPENAME_PROJECT, TYPENAME_USER } from '~/graphql_shared/constants';
+import { helpPagePath } from '~/helpers/help_page_helper';
 import { __, s__ } from '~/locale';
 import * as Sentry from '~/sentry/sentry_browser_wrapper';
 import { InternalEvents } from '~/tracking';
@@ -20,8 +28,9 @@ export default {
     GlButton,
     GlExperimentBadge,
     GlFormGroup,
-    GlIcon,
     GlFormTextarea,
+    GlIcon,
+    GlLink,
   },
   mixins: [InternalEvents.mixin()],
   inject: {
@@ -149,6 +158,9 @@ export default {
       },
     },
   },
+  helpPageUrl: helpPagePath('user/analytics/analytics_dashboards', {
+    anchor: 'generate-a-custom-visualization-with-gitlab-duo',
+  }),
 };
 </script>
 
@@ -166,6 +178,10 @@ export default {
             'Analytics|GitLab Duo may be used to help generate your visualization. You can prompt Duo with your desired data, as well as any dimensions or additional groupings of that data. You may also edit the result as needed.',
           )
         }}
+        <gl-link data-testid="generate-cube-query-learn-more-link" :href="$options.helpPageUrl">{{
+          __('Learn more')
+        }}</gl-link
+        >.
       </p>
       <gl-form-textarea
         v-model="prompt"
diff --git a/ee/spec/frontend/analytics/analytics_dashboards/components/visualization_designer/ai_cube_query_generator_spec.js b/ee/spec/frontend/analytics/analytics_dashboards/components/visualization_designer/ai_cube_query_generator_spec.js
index e5a8a4c19da87..4a0f4591d043a 100644
--- a/ee/spec/frontend/analytics/analytics_dashboards/components/visualization_designer/ai_cube_query_generator_spec.js
+++ b/ee/spec/frontend/analytics/analytics_dashboards/components/visualization_designer/ai_cube_query_generator_spec.js
@@ -38,6 +38,7 @@ describe('AiCubeQueryGenerator', () => {
   const findGenerateCubeQuerySubmitButton = () =>
     wrapper.findByTestId('generate-cube-query-submit-button');
   const findExperimentBadge = () => wrapper.findComponent(GlExperimentBadge);
+  const findLearnMoreLink = () => wrapper.findByTestId('generate-cube-query-learn-more-link');
 
   const createWrapper = (props = {}) => {
     wrapper = shallowMountExtended(AiCubeQueryGenerator, {
@@ -76,6 +77,15 @@ describe('AiCubeQueryGenerator', () => {
     expect(findExperimentBadge().exists()).toBe(true);
   });
 
+  it('renders a "learn more" link', () => {
+    createWrapper();
+
+    expect(findLearnMoreLink().text()).toBe('Learn more');
+    expect(findLearnMoreLink().attributes('href')).toBe(
+      '/help/user/analytics/analytics_dashboards#generate-a-custom-visualization-with-gitlab-duo',
+    );
+  });
+
   describe('when no prompt has been entered', () => {
     beforeEach(() => {
       createWrapper();
-- 
GitLab