4806-document-different-ways-to-execute-queries-against-iox (#4836)

* fix(cloud-iox): Superset instruction (#4806)

* chore(docs): add example keywords for code-callout so I can find it later.

* chore(refactor): refactor the SQL schema intro into a partial shortcode for reuse.

* fix(cloud-iox): #4806 Setup and query Grafana Flight SQL

- Help configuring a Homebrew installed Grafana
- Add some query help
- Add note about schema elements.
- Warn about functions not working.
- Screenshot of query builder.

* fix(cloud-iox): superset frontmatter description (#4806)

* fix(cloud-iox): Grafana frontmatter

* fix(cloud-iox): Remove incorrect note about aggregate function support. Clarify required time column and the use of aggregations.

* Apply suggestions from code review

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

---------

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

CONTRIBUTING.md

@@ -1123,7 +1123,8 @@ Click {{< caps >}}Add Data{{< /caps >}}
 
 #### Code callouts
 Use the `{{< code-callout >}}` shortcode to highlight and emphasize a specific
-piece of code in a code block. Provide the string to highlight in the code block.
+piece of code (for example, a variable, placeholder, or value) in a code block.
+Provide the string to highlight in the code block.
 Include a syntax for the codeblock to properly style the called out code.
 
 ~~~md

content/influxdb/cloud-iox/query-data/execute-queries/flight-sql/superset.md

@@ -3,7 +3,7 @@ title: Use Superset to query data
 seotitle: Use Apache Superset to query data stored in InfluxDB Cloud (IOx)
 description: >
   Install and run [Apache Superset](https://superset.apache.org/)
-  to query data stored in an InfluxDB bucket.
+  to query data stored in a bucket powered by InfluxDB IOx.
 weight: 101
 menu:
   influxdb_cloud_iox:
@@ -109,7 +109,7 @@ pip3 install flightsql-dbapi
     [DB API 2](https://peps.python.org/pep-0249/) interface and
     [SQLAlchemy](https://www.sqlalchemy.org/) dialect for
     [Flight SQL](https://arrow.apache.org/docs/format/FlightSql.html).
-    You need it later for configuring Superset.
+    Later, you'll add it to Superset's Docker configuration.
 
     {{% warn %}}
 The `flightsql-dbapi` library is experimental and under active development.

content/influxdb/cloud-iox/query-data/sql/explore-schema.md

@@ -23,9 +23,7 @@ list_code_example: |
   ```
 ---
 
-When working with InfluxDB's implementation of SQL, a **bucket** is equivalent
+{{% sql/sql-schema-intro %}}
-to a databases, a **measurement** is structured as a table, and **time**,
-**fields**, and **tags** are structured as columns.
 
 ## List measurements in a bucket
 

content/influxdb/cloud-iox/visualize-data/grafana.md

@@ -1,21 +1,22 @@
 ---
-title: Use Grafana to visualize data
+title: Use Grafana to query and visualize data
-seotitle: Use Grafana to visualize data stored in InfluxDB
+seotitle: Use Grafana to query and visualize data stored in InfluxDB Cloud (IOx)
-list_title: Grafana
+list_title: Use Grafana
 description: >
-  Use [Grafana](https://grafana.com/) to query and visualize data stored in an
+  Install and run [Grafana](https://grafana.com/) to query and visualize data stored in an
-  InfluxDB bucket backed by InfluxDB IOx.
+  InfluxDB bucket powered by InfluxDB IOx.
 weight: 101
 menu:
   influxdb_cloud_iox:
-    name: Grafana
+    name: Use Grafana
     parent: Visualize data
 influxdb/cloud-iox/tags: [visualization]
 alt_engine: /influxdb/cloud/tools/grafana/
 ---
 
 Use [Grafana](https://grafana.com/) to query and visualize data stored in an
-InfluxDB bucket backed by InfluxDB IOx.
+InfluxDB bucket powered by InfluxDB IOx.
+Install the [grafana-flight-sql-plugin](https://github.com/influxdata/grafana-flightsql-datasource) to query InfluxDB with the Flight SQL protocol.
 
 > [Grafana] enables you to query, visualize, alert on, and explore your metrics,
 > logs, and traces wherever they are stored.
@@ -24,40 +25,62 @@ InfluxDB bucket backed by InfluxDB IOx.
 >
 > {{% caption %}}[Grafana documentation](https://grafana.com/docs/grafana/latest/introduction/){{% /caption %}}
 
-For the most performant queries, use SQL and the
+<!-- TOC -->
-[Flight SQL protocol](https://arrow.apache.org/blog/2022/02/16/introducing-arrow-flight-sql/)
+
-to query InfluxDB.
+- [Install Grafana](#install-grafana)
+- [Download the Grafana Flight SQL Plugin](#download-the-grafana-flight-sql-plugin)
+- [Extract the Flight SQL plugin](#extract-the-flight-sql-plugin)
+- [Install the Grafana Flight SQL plugin](#install-the-grafana-flight-sql-plugin)
+    - [Install with Docker Run](#install-with-docker-run)
+    - [Install with Docker-Compose](#install-with-docker-compose)
+- [Configure the Flight SQL datasource](#configure-the-flight-sql-datasource)
+- [Query InfluxDB with Grafana](#query-influxdb-with-grafana)
+- [Build visualizations with Grafana](#build-visualizations-with-grafana)
+
+<!-- /TOC -->
+
+## Install Grafana
+
+Follow [Grafana installations instructions](https://grafana.com/docs/grafana/latest/setup-grafana/installation/)
+for your operating system to Install Grafana.
 
 
-## Download the Flight SQL Plugin
+## Download the Grafana Flight SQL plugin
+
+Download the latest release from [influxdata/grafana-flightsql-datasource releases](https://github.com/influxdata/grafana-flightsql-datasource/releases).
 
 {{% warn %}}
-The Grafana Flight SQL plugin is experimental and is subject to change.
+Because Grafana Flight SQL Plugin is a custom plugin, you can't use it with Grafana Cloud.
+For more information, see [Find and Use Plugins in the Grafana Cloud documentation](https://grafana.com/docs/grafana-cloud/fundamentals/find-and-use-plugins/)
+
+The Grafana Flight SQL plugin is experimental and subject to change.
 {{% /warn %}}
 
 ```sh
-curl -L https://github.com/influxdata/grafana-flightsql-datasource/releases/download/v0.1.5/influxdata-flightsql-datasource-0.1.5.zip \
+curl https://github.com/influxdata/grafana-flightsql-datasource/releases/download/v0.1.8/influxdata-flightsql-datasource-0.1.8.zip
-  -o influxdata-flightsql-datasource-0.1.5.zip
 ```
 
+<span id="custom-grafana-plugins-directory"></span>
+
+## Extract the Flight SQL plugin
+
+Extract the Flight SQL plugin archive to your Grafana **custom plugins directory**.
+The custom plugins directory can be any filesystem location that Grafana can access.
+
+{{% code-callout "/custom/plugins/directory" %}}
+```sh
+unzip influxdata-flightsql-datasource-0.1.5.zip -d /custom/plugins/directory/
+```
+{{% /code-callout %}}
+
 ## Install the Grafana Flight SQL plugin
 
 Install the custom-built Flight SQL plugin in a local or Docker-based instance
 of Grafana OSS or Grafana Enterprise.
 
 {{% warn %}}
-#### Grafana Cloud does not support custom plugins
+Because Grafana Flight SQL Plugin is a custom plugin, you can't use it with Grafana Cloud.
-
+For more information, see [Find and Use Plugins in the Grafana Cloud documentation](https://grafana.com/docs/grafana-cloud/fundamentals/find-and-use-plugins/)
-Only plugins that are uploaded publicly to the Grafana Plugins repo that
-include the ability to use “click to install” from the site can be added to
-your Grafana Cloud instance. Private, custom-built, or third-party plugins
-that require manual uploading or manually modifying Grafana backend files
-cannot be installed on or used with Grafana Cloud.
-
-{{% caption %}}
-[Grafana Cloud documentation](https://grafana.com/docs/grafana-cloud/fundamentals/find-and-use-plugins/)
-{{% /caption %}}
-
 {{% /warn %}}
 
 {{< tabs-wrapper >}}
@@ -69,89 +92,84 @@ cannot be installed on or used with Grafana Cloud.
 {{% tab-content %}}
 <!---------------------------- BEGIN LOCAL CONTENT ---------------------------->
 
-<div id="custom-grafana-plugins-directory"></div>
+  Follow these steps to edit the Grafana configuration file or set environment variables to install the plugin. 
+  
+  {{% note %}}
 
-1.  **Unzip the Flight SQL plugin archive to your Grafana custom plugin directory**.
+  If you used **Homebrew** to install Grafana, follow the steps to edit the
-    The custom plugin directory can exist anywhere in your filesystem as long as
+  `/homebrew/install/path/etc/grafana/grafana.ini` configuration file.
-    the Grafana process can access it.
+  
+  Replace `/homebrew/install/path` with the output of the [`brew --prefix` command](https://docs.brew.sh/Manpage#--prefix---unbrewed---installed-formula-) for your system.
 
-    ```sh
+  For information about where to find your Grafana configuration file or what
-    unzip influxdata-flightsql-datasource-0.1.5.zip -d /path/to/grafana-plugins/
+  environment variables are available, see the
-    ```
+  [Configure Grafana documentation](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/).
-
+  
-2.  **Edit your Grafana configuration**.
+  {{% /note %}}
     
-    Configure Grafana using configuration file or environment variable.
+  1.  Set your Grafana custom plugin directory. Do one of the following:
-    For information about where to find your Grafana configuration file or what
-    environment variables are available, see the
-    [Configure Grafana documentation](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/).
-    
-    1.  **Point Grafana to your custom plugin directory**.
-        Do one of the following:
 
-        - Edit the `paths.plugins` directive in your Grafana configuration file
+      - In your Grafana configuration file, set the `paths.plugins` directive 
-          to point to the path of your [custom plugins directory](#custom-grafana-plugins-directory):
+        to the path of your [custom plugins directory](#custom-grafana-plugins-directory):
-        
+      
-          ```ini
+        ```ini
-          [paths]
+        [paths]
-          plugins = /path/to/grafana-plugins/
+        plugins = /custom/plugins/directory/
-          ```
+        ```
 
-        - Set the `GF_PATHS_PLUGINS` environment variable to point to the path
+      - Set the `GF_PATHS_PLUGINS` environment variable to the path
-          of your [custom plugins directory](#custom-grafana-plugins-directory):
+        of your [custom plugins directory](#custom-grafana-plugins-directory):
-        
+      
-          ```sh
+        ```sh
-          GF_PATHS_PLUGINS=/path/to/grafana-plugins/
+        GF_PATHS_PLUGINS=/custom/plugins/directory/
-          ```
+        ```
 
-    2.  **Allow Grafana to load unsigned plugins**.
+  2.  Allow Grafana to load the unsigned plugin. The Flight SQL plugin is unsigned and Grafana requires you to explicitly load unsigned plugins.
-        The Flight SQL plugin is unsigned and cannot be loaded by default.
+      Do one of the following:
-        Do one of the following:
 
-        - Edit the `plugins.allow_loading_unsigned_plugins` directive in your
+      - Set the `plugins.allow_loading_unsigned_plugins` directive in your
-          Grafana configuration file to allow the `influxdata-flightsql-datasource`:
+        Grafana configuration file to allow the `influxdata-flightsql-datasource`:
 
-          ```ini
+        ```ini
-          [plugins]
+        [plugins]
-          allow_loading_unsigned_plugins = influxdata-flightsql-datasource
+        allow_loading_unsigned_plugins = influxdata-flightsql-datasource
-          ```
+        ```
 
-        - Set the `GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS` environment variable
+      - Set the `GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS` environment variable
-          to `influxdata-flightsql-datasource`:
+        to `influxdata-flightsql-datasource`:
 
-          ```sh
+        ```sh
-          GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=influxdata-flightsql-datasource
+        GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=influxdata-flightsql-datasource
-          ```
+        ```
 
-4.  **Restart Grafana to apply the configuration changes**.
+4.  Restart Grafana to apply the configuration changes.
 
 <!----------------------------- END LOCAL CONTENT ----------------------------->
 {{% /tab-content %}}
 {{% tab-content %}}
 <!---------------------------- BEGIN DOCKER CONTENT --------------------------->
-**Unzip the Flight SQL plugin archive to your Grafana custom plugin directory**.
+To add the Flight SQL plugin to your pre-existing Grafana Docker deployment,
- The custom plugin directory can exist anywhere in your filesystem as long as
+use `docker run` or `docker-compose` to do the following:
- the Grafana process can access it.
 
-    ```sh
+-  Mount the plugin directory (`/custom/plugins/directory/influxdata-flightsql-datasource`) as a volume to your Grafana container.
-    unzip influxdata-flightsql-datasource-0.1.2.zip
+-  Set the `GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS` environment variable to the plugin name. The Flight SQL plugin is unsigned and Grafana requires you to explicitly load unsigned plugins. 
-    ```
 
-To add the Flight SQL plugin to your pre-existing Grafana Docker deployment
+### Install with Docker Run
-mount the plugin directory, `influxdata-flightsql-datasource`, as a volume to your Grafana container:
 
-Docker Run
+{{% code-callout "/custom/plugins/directory" %}}
-```bash 
+```sh 
 docker run \
-  --volume $PWD/influxdata-flightsql-datasource:/var/lib/grafana/plugins/influxdata-flightsql-datasource \
+  --volume $PWD/influxdata-flightsql-datasource:/custom/plugins/directory/influxdata-flightsql-datasource \
   --publish 3000:3000 \
   --name grafana \
   --env GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=influxdata-flightsql-datasource \
   grafana/grafana:latest
 ```
+{{% /code-callout %}}
 
-##### Docker-Compose
+### Install with Docker-Compose
 
+{{% code-callout "/custom/plugins/directory" %}}
 ```yaml
 version: '3'
 services:
@@ -162,16 +180,13 @@ services:
     environment:
       - GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=influxdata-flightsql-datasource
     volumes: 
-      - ./influxdata-flightsql-datasource:/var/lib/grafana/plugins/influxdata-flightsql-datasource
+      - ./influxdata-flightsql-datasource:/custom/plugins/directory/influxdata-flightsql-datasource
     restart: always
 ```
+{{% /code-callout %}}
 
-{{% note %}}
+- Replace `/custom/plugins/directory` with the path
-It's important to set the `GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS`
+  of your [custom plugins directory](#custom-grafana-plugins-directory).
-environment variable. The Flight SQL plugin is unsigned and Grafana requires you
-to explicitly load unsigned plugins. 
-{{% /note %}}
-
 <!----------------------------- END DOCKER CONTENT ---------------------------->
 {{% /tab-content %}}
 {{< /tabs-wrapper >}}
@@ -202,18 +217,44 @@ to explicitly load unsigned plugins.
       {{% oss-only %}}If TLS is configured and enabled on your InfluxDB instance, enable this toggle.{{% /oss-only %}}
 
 6.  Add connection **MetaData**.
-    Provide optional key, value pairs to send to your Flight SQL client.
+    Provide optional key-value pairs to send to your Flight SQL client.
 
     InfluxDB {{< current-version >}} requires your **bucket name** or **bucket-id**:
     
     - **Key**: `bucket-name` or `bucket-id`
     - **Value**: Bucket name or bucket ID
 
-7.  Select **Save & Test**.
+7.  Click **Save & test**.
 
     {{< img-hd src="/img/influxdb/cloud-iox-grafana-flightsql-datasource.png" alt="Grafana Flight SQL datasource" />}}
 
-8. Click **Explore** to begin exploring your schema and querying InfluxDB with SQL.
+    If successful, click **Explore** to begin querying InfluxDB with Flight SQL and Grafana.
+
+## Query InfluxDB with Grafana
+
+After you [configure and save a Flight SQL datasource](#configure-the-flight-sql-datasource),
+use Grafana to build, run, and inspect queries against InfluxDB buckets.
+
+{{% note %}}
+{{% sql/sql-schema-intro %}}
+To learn more, see [Query Data](/influxdb/cloud-iox/query-data/sql/).
+{{% /note %}}
+
+1. Click **Explore**.
+2. In the dropdown, select the saved data source that you want to query.
+3. Use the SQL query form to build your query:
+    - **FROM**: Select the measurement that you want to query.
+    - **SELECT**: Select one or more fields and tags to return as columns in query results.
+                  In Grafana, you must specify a **time** column in the `SELECT` list.
+    - **WHERE**: To filter the query results, enter a conditional expression.
+    - **GROUP BY**: To `GROUP BY` one or more fields or tags, enter them as a comma-delimited list.
+                    If you include an aggregate function in the **SELECT** list,
+                    then you must include one or more of the queried columns in a `GROUP BY` or `PARTITION BY` clause.
+                    SQL will return the aggregation for each group or partition.
+4. Click **Run query** to execute the query.
+{{< img-hd src="/img/influxdb/cloud-iox-grafana-flightsql-explore-query-1.png" alt="Grafana Flight SQL datasource query" />}}
+
+To learn about query management and inspection in Grafana, see the [Grafana Explore documentation](https://grafana.com/docs/grafana/latest/explore/).
 
 ## Build visualizations with Grafana
 

layouts/shortcodes/sql/sql-schema-intro.md

@@ -0,0 +1,3 @@
+When working with the InfluxDB SQL implementation, a **bucket** is equivalent
+to a databases, a **measurement** is structured as a table, and **time**,
+**fields**, and **tags** are structured as columns.