Docs: Updated Athena data source docs

docs/sources/alerting.md

@@ -0,0 +1,85 @@
+---
+aliases:
+  - /docs/plugins/grafana-athena-datasource/alerting/
+description: Set up Grafana Alerting with the Amazon Athena data source.
+keywords:
+  - grafana
+  - amazon athena
+  - athena
+  - aws
+  - alerting
+  - alerts
+labels:
+  products:
+    - cloud
+    - enterprise
+    - oss
+menuTitle: Alerting
+title: Amazon Athena alerting
+weight: 460
+last_reviewed: 2026-02-20
+---
+
+# Amazon Athena alerting
+
+Use [Grafana Alerting](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/alerting/) with the Amazon Athena data source to receive notifications when your data meets specific conditions. For example, you can create alerts that trigger when error counts exceed a threshold or when costs rise above a budget.
+
+## Before you begin
+
+Before you set up alerting, ensure you have the following prerequisites.
+
+- [Configure the Amazon Athena data source](https://grafana.com/docs/plugins/grafana-athena-datasource/latest/configure/).
+- Understand how to use the [Amazon Athena query editor](https://grafana.com/docs/plugins/grafana-athena-datasource/latest/query-editor/).
+- Understand [Grafana Alerting concepts](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/alerting/fundamentals/).
+
+## Create an alert rule
+
+To create an alert rule using the Amazon Athena data source:
+
+1. Click **Alerting** in the left-side menu.
+1. Click **Alert rules**.
+1. Click **New alert rule**.
+1. Enter a name for the alert rule.
+1. Select the Amazon Athena data source.
+1. Write a SQL query that returns the numeric value you want to evaluate.
+1. Configure the alert condition by selecting a reducer (such as **Last** or **Mean**) and a threshold.
+1. Set the evaluation interval and pending period.
+1. Configure notification settings and click **Save rule and exit**.
+
+## Query requirements for alerting
+
+Alert rule queries must return numeric data that Grafana can evaluate against a threshold. Follow these guidelines when writing queries for alert rules.
+
+- **Return a numeric value:** The query must return at least one numeric column that Grafana can evaluate.
+- **Use time-series format:** Select the **Time series** format in the query editor. The query needs a time column in ascending order and a numeric value column.
+- **Keep queries efficient:** Alert queries run at the configured evaluation interval. Use filters, partitions, and narrow time ranges to reduce data scanned and query execution time.
+- **Use macros for time filtering:** Use `$__timeFilter(column)` to automatically filter data to the alert evaluation window.
+
+### Example alert query
+
+The following query counts errors per minute, which can be evaluated against a threshold.
+
+```sql
+SELECT
+  $__timeGroup(time, '1m') AS time,
+  COUNT(*) AS error_count
+FROM error_logs
+WHERE $__timeFilter(time) AND level = 'ERROR'
+GROUP BY 1
+ORDER BY 1 ASC
+```
+
+## Performance considerations
+
+Amazon Athena queries run asynchronously, which means they may take longer to complete than queries from other data sources. Keep the following considerations in mind when configuring alert rules.
+
+- **Evaluation interval:** Set an evaluation interval that accounts for Athena query execution time. Queries that scan large amounts of data may take several seconds or longer to complete.
+- **Query result reuse:** Enable [query result reuse](https://grafana.com/docs/plugins/grafana-athena-datasource/latest/query-editor/#query-result-reuse) to reduce costs and query time for alert queries that run frequently. This requires Athena engine version 3.
+- **Data scan costs:** Each alert evaluation runs a query against Athena, which incurs costs based on data scanned. Use partitioned tables and add `WHERE` clause filters to minimize the amount of data scanned per evaluation.
+- **Query caching:** Enable [query caching](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/#query-caching) to reduce the number of queries sent to Athena (available in Grafana Enterprise and Grafana Cloud).
+
+## Next steps
+
+- [Configure notification policies](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/alerting/configure-notifications/)
+- [Create contact points](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/alerting/configure-notifications/manage-contact-points/)
+- [Grafana Alerting documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/alerting/)

docs/sources/annotations.md

@@ -0,0 +1,66 @@
+---
+aliases:
+  - /docs/plugins/grafana-athena-datasource/annotations/
+description: Add annotations from Amazon Athena data in Grafana.
+keywords:
+  - grafana
+  - amazon athena
+  - athena
+  - aws
+  - annotations
+labels:
+  products:
+    - cloud
+    - enterprise
+    - oss
+menuTitle: Annotations
+title: Amazon Athena annotations
+weight: 450
+last_reviewed: 2026-02-20
+---
+
+# Amazon Athena annotations
+
+[Annotations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/annotate-visualizations/) let you overlay rich event information on top of graphs. You can add annotations by clicking on panels or by adding annotation queries through **Dashboard settings** > **Annotations**.
+
+## Create an annotation query
+
+To create an annotation query:
+
+1. Open the dashboard where you want to add annotations.
+1. Click the dashboard settings gear icon.
+1. Select **Annotations** from the left-side menu.
+1. Click **Add annotation query**.
+1. Select the Amazon Athena data source.
+1. Enter a SQL query that returns the required annotation columns.
+
+## Annotation columns
+
+The following table describes the columns that Amazon Athena annotation queries use to render annotations.
+
+| Column | Required | Description |
+| ----------- | -------- | ----------- |
+| **time** | Yes | The date/time field. Can be a column with a native SQL date/time data type or an epoch value. |
+| **timeend** | No | The end date/time field for region annotations. Can be a column with a native SQL date/time data type or an epoch value. |
+| **text** | No | The event description field displayed in the annotation tooltip. |
+| **tags** | No | A comma-separated string used as event tags for filtering annotations. |
+
+## Example annotation query
+
+The following query creates annotations for humidity readings that exceed 95, tagged by environment.
+
+```sql
+SELECT
+  time as time,
+  environment as tags,
+  humidity as text
+FROM
+  tableName
+WHERE
+  $__dateFilter(time) and humidity > 95
+```
+
+## Next steps
+
+- [Amazon Athena query editor](https://grafana.com/docs/plugins/grafana-athena-datasource/latest/query-editor/)
+- [Grafana annotations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/annotate-visualizations/)

docs/sources/configure.md

@@ -0,0 +1,239 @@
+---
+aliases:
+  - /docs/plugins/grafana-athena-datasource/configure/
+description: Configure the Amazon Athena data source for Grafana.
+keywords:
+  - grafana
+  - amazon athena
+  - athena
+  - aws
+  - configure
+  - authentication
+  - iam
+  - provisioning
+labels:
+  products:
+    - cloud
+    - enterprise
+    - oss
+menuTitle: Configure
+title: Configure the Amazon Athena data source
+weight: 200
+last_reviewed: 2026-02-20
+---
+
+# Configure the Amazon Athena data source
+
+This document explains how to configure the Amazon Athena data source in Grafana.
+
+## Before you begin
+
+Before you configure the data source, ensure you have the following prerequisites.
+
+- **Grafana permissions:** Organization administrator role.
+- **AWS account:** An active AWS account with Amazon Athena enabled.
+- **IAM credentials:** An IAM user or role with the required Athena, Glue, and S3 permissions. Refer to the [IAM policies](#iam-policies) section for details.
+- **Athena resources:** At least one Athena workgroup and data catalog configured in your AWS account.
+
+## Add the data source
+
+To add the Amazon Athena data source:
+
+1. Click **Connections** in the left-side menu.
+1. Click **Add new connection**.
+1. Type `Amazon Athena` in the search bar.
+1. Select **Amazon Athena**.
+1. Click **Add new data source**.
+
+## Configure settings
+
+The following table describes the available configuration settings.
+
+| Setting | Description |
+| ------------------------------ | ----------- |
+| **Name** | The data source name. This is how you refer to the data source in panels and queries. |
+| **Default** | Toggle to make this the default data source for new panels. |
+| **Authentication Provider** | The AWS credentials chain to use. Refer to [Authentication](#authentication) for details. |
+| **Assume Role ARN** (optional) | The ARN of an IAM role to assume. Use this for cross-account access. |
+| **External ID** (optional) | The external ID for assuming a role in another account. Required if the target role was created with an external ID condition. |
+| **Endpoint** (optional) | A custom endpoint for the Amazon Athena service. |
+| **Default Region** | The AWS region where your Athena resources are located. |
+| **Data Source** | The Athena data catalog to use. Catalogs are loaded automatically. |
+| **Database** | The database within the selected catalog. |
+| **Workgroup** | The Athena workgroup to use for query execution. |
+| **Output Location** (optional) | An S3 bucket to store query execution outputs. If not specified, the default query result location from the workgroup configuration is used. If [Override client-side settings](https://docs.aws.amazon.com/athena/latest/ug/workgroups-settings-override.html) is enabled in the AWS console, this setting is ignored. |
+
+## Authentication
+
+The Amazon Athena data source uses AWS authentication. The available authentication methods depend on your Grafana deployment.
+
+Open source Grafana enables the **AWS SDK Default**, **Credentials file**, and **Access and secret key** methods by default. Grafana Cloud enables **Access and secret key** by default.
+
+For more information about authentication options and configuration, refer to [AWS authentication](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/aws-cloudwatch/aws-authentication/).
+
+### IAM policies
+
+Grafana needs permissions granted through IAM to read Amazon Athena data. You can attach these permissions to IAM roles and use Grafana's built-in support for assuming roles. You must [create the required IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) before adding the data source to Grafana.
+
+Depending on the data you query with Amazon Athena, you may need different permissions. AWS provides [predefined managed policies](https://docs.aws.amazon.com/athena/latest/ug/managed-policies.html) you can use as a starting point.
+
+The following example shows a minimal IAM policy for querying Amazon Athena. It's based on the [`AmazonAthenaFullAccess`](https://docs.aws.amazon.com/athena/latest/ug/managed-policies.html#amazonathenafullaccess-managed-policy) managed policy, with write permissions removed where possible since Grafana should be used as read-only.
+
+{{< admonition type="note" >}}
+Update the ARN of the S3 bucket if you're using a custom one. If your AWS account uses AWS Lake Formation to manage data access, you must also include the `lakeformation:GetDataAccess` permission. Refer to the [AWS Lake Formation permissions for Athena](https://docs.aws.amazon.com/athena/latest/ug/lf-athena.html) documentation.
+{{< /admonition >}}
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "AthenaQueryAccess",
+      "Effect": "Allow",
+      "Action": [
+        "athena:ListDatabases",
+        "athena:ListDataCatalogs",
+        "athena:ListWorkGroups",
+        "athena:GetDatabase",
+        "athena:GetDataCatalog",
+        "athena:GetQueryExecution",
+        "athena:GetQueryResults",
+        "athena:GetTableMetadata",
+        "athena:GetWorkGroup",
+        "athena:ListTableMetadata",
+        "athena:StartQueryExecution",
+        "athena:StopQueryExecution"
+      ],
+      "Resource": ["*"]
+    },
+    {
+      "Sid": "GlueReadAccess",
+      "Effect": "Allow",
+      "Action": [
+        "glue:GetDatabase",
+        "glue:GetDatabases",
+        "glue:GetTable",
+        "glue:GetTables",
+        "glue:GetPartition",
+        "glue:GetPartitions",
+        "glue:BatchGetPartition"
+      ],
+      "Resource": ["*"]
+    },
+    {
+      "Sid": "AthenaS3Access",
+      "Effect": "Allow",
+      "Action": [
+        "s3:GetBucketLocation",
+        "s3:GetObject",
+        "s3:ListBucket",
+        "s3:ListBucketMultipartUploads",
+        "s3:ListMultipartUploadParts",
+        "s3:AbortMultipartUpload",
+        "s3:PutObject"
+      ],
+      "Resource": ["arn:aws:s3:::aws-athena-query-results-*"]
+    },
+    {
+      "Sid": "AthenaExamplesS3Access",
+      "Effect": "Allow",
+      "Action": ["s3:GetObject", "s3:ListBucket"],
+      "Resource": ["arn:aws:s3:::athena-examples*"]
+    },
+    {
+      "Sid": "LakeFormationAccess",
+      "Effect": "Allow",
+      "Action": [
+        "lakeformation:GetDataAccess"
+      ],
+      "Resource": ["*"]
+    }
+  ]
+}
+```
+
+## Verify the connection
+
+Click **Save & test** to verify that the data source is configured correctly. A success message confirms that Grafana can connect to your Amazon Athena instance.
+
+## Provision the data source
+
+You can define the Amazon Athena data source in YAML files as part of Grafana's provisioning system. For more information, refer to [Provisioning Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/provisioning/).
+
+The following examples show provisioning configurations for each authentication method.
+
+### Use AWS SDK (default)
+
+```yaml
+apiVersion: 1
+datasources:
+  - name: Athena
+    type: grafana-athena-datasource
+    jsonData:
+      authType: default
+      defaultRegion: eu-west-2
+      catalog: AwsDataCatalog
+      database: <YOUR_ATHENA_DATABASE>
+      workgroup: <YOUR_ATHENA_WORKGROUP>
+```
+
+### Use a credentials profile
+
+```yaml
+apiVersion: 1
+datasources:
+  - name: Athena
+    type: grafana-athena-datasource
+    jsonData:
+      authType: credentials
+      defaultRegion: eu-west-2
+      profile: secondary
+      catalog: AwsDataCatalog
+      database: <YOUR_ATHENA_DATABASE>
+      workgroup: <YOUR_ATHENA_WORKGROUP>
+```
+
+### Use access and secret keys
+
+```yaml
+apiVersion: 1
+datasources:
+  - name: Athena
+    type: grafana-athena-datasource
+    jsonData:
+      authType: keys
+      defaultRegion: eu-west-2
+      catalog: AwsDataCatalog
+      database: <YOUR_ATHENA_DATABASE>
+      workgroup: <YOUR_ATHENA_WORKGROUP>
+    secureJsonData:
+      accessKey: <YOUR_ACCESS_KEY>
+      secretKey: <YOUR_SECRET_KEY>
+```
+
+### Use AWS SDK with an assumed IAM role
+
+```yaml
+apiVersion: 1
+datasources:
+  - name: Athena
+    type: grafana-athena-datasource
+    jsonData:
+      authType: default
+      assumeRoleArn: arn:aws:iam::123456789012:root
+      defaultRegion: eu-west-2
+      catalog: AwsDataCatalog
+      database: <YOUR_ATHENA_DATABASE>
+      workgroup: <YOUR_ATHENA_WORKGROUP>
+```
+
+### Optional provisioning parameters
+
+You can also include the following optional parameters in your provisioning configuration.
+
+```yaml
+jsonData:
+  endpoint: https://<SERVICE>.<REGION>.amazonaws.com
+  externalId: <YOUR_ROLE_EXTERNAL_ID>
+  outputLocation: s3://<YOUR_S3_BUCKET>
+```