<?xml version="1.0" encoding="utf-8"?>

<!-- EngineVersion = Java version -->
<ApiConfig Name="Amazon Athena"
           Slug="amazon-athena-connector"
           Type="JDBC"
           Category="big-data"
           Id="e3f5c7a1-4b6d-4f8e-9c3d-2a7b8e9d5f6a"
           Version="2"
           EngineVersion="8"
           Desc="Query Amazon Athena catalogs and S3 results from Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools -- almost no coding required."
           Logo="https://cdn.zappysys.com/api/Images/logos/amazon-athena-connector.png"
           HelpLink="https://community.zappysys.com/tag/amazon-athena-connector">

    <VersionHistory>
      <Change Ver="2" Date="2026-09-15" Type="Modified">Auth Notes (numbered steps), documented params, Maven DriverDownloadLinks, extra SQL examples for ODBC apps.</Change>
      <Change Ver="1" Date="2025-04-29" Type="New">Initial version.</Change>
    </VersionHistory>
    <Template>
        <Param Name="DriverDownloadPageLink"
               Value="https://docs.aws.amazon.com/athena/latest/ug/jdbc-v3-driver.html" />
        <Param Name="DriverDownloadLinks"
               Hidden="True"
               Value="athena-jdbc-3.8.1-with-dependencies.jar=https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.8.1/athena-jdbc-3.8.1-with-dependencies.jar" />
    </Template>
    <Auths>
        <Auth Name="Default"
              Label="IAM access key"
              ConnStr="jdbc:athena://WorkGroup=[$WorkGroup$];Region=[$Region$];Catalog=[$Catalog$];OutputLocation=[$OutputLocation$];"
              HelpLink="https://docs.aws.amazon.com/athena/latest/ug/jdbc-v3-driver-getting-started.html">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="com.amazon.athena.jdbc.AthenaDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. com.amazon.athena.jdbc.AthenaDriver)." HelpLink="https://docs.aws.amazon.com/athena/latest/ug/jdbc-v3-driver-getting-started.html" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\athena-jdbc-3.8.1-with-dependencies.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://docs.aws.amazon.com/athena/latest/ug/jdbc-v3-driver-getting-started.html" />
                <Param Name="WorkGroup" Label="Workgroup" Required="True" Value="primary" Desc="Athena workgroup (e.g. primary)." HelpLink="https://docs.aws.amazon.com/athena/latest/ug/jdbc-v3-driver-getting-started.html" />
                <Param Name="Region" Label="AWS region" Required="True" Value="us-east-1" Desc="AWS region (e.g. us-east-1)." HelpLink="https://docs.aws.amazon.com/athena/latest/ug/jdbc-v3-driver-getting-started.html" />
                <Param Name="Catalog" Label="Athena catalog" Required="True" Value="MyAwsDataCatalog" Desc="Athena catalog (e.g. MyAwsDataCatalog)." HelpLink="https://docs.aws.amazon.com/athena/latest/ug/jdbc-v3-driver-getting-started.html" />
                <Param Name="OutputLocation" Label="Output location" Required="True" Value="s3://my-s3-bucket/" Desc="Athena query result S3 location (e.g. s3://my-s3-bucket/)." HelpLink="https://docs.aws.amazon.com/athena/latest/ug/jdbc-v3-driver-getting-started.html" />
                <Param Name="UserName" Label="Access key ID" Required="True" Desc="IAM access key ID (not a personal AWS console login). Paste from IAM &gt; Security credentials." HelpLink="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html" />
                <Param Name="Password" Label="Secret access key" Required="True" Secret="True" Desc="IAM secret access key for the same access key ID." HelpLink="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html" />
            </Params>
            <Notes>
                <![CDATA[<p>Athena JDBC v3 uses IAM access keys (same idea as a Stripe secret key). Query results land in S3. Bridge then serves Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools.</p>
<ol>
  <li>Sign in to the <a target="_blank" href="https://console.aws.amazon.com/iam/">IAM console</a>.</li>
  <li>Create (or reuse) an IAM user or role with Athena and Glue catalog permissions plus <code>s3:GetObject</code> / <code>s3:PutObject</code> on the query-results bucket.</li>
  <li>Open <strong>Security credentials</strong> and create an access key. Copy <strong>Access key ID</strong> into User name and <strong>Secret access key</strong> into Password. Do not check keys into XML or TFVC.</li>
  <li>In the Athena console, note Region, WorkGroup (often <code>primary</code>), Catalog, and the S3 output location (<code>s3://your-bucket/prefix/</code>).</li>
  <li>After Finish, edit the JDBC URL on the DSN Main UI to replace WorkGroup, Region, Catalog, and OutputLocation.</li>
  <li>Finish the wizard. Then click <strong>Test Connection</strong> on the DSN Main UI (the wizard does not run Test Connection).</li><li>Done. You can query from C#, Python, PowerShell, and ODBC apps.</li>
</ol>]]>
            </Notes>
        </Auth>
    </Auths>

    <Examples>
        <Example Group="ODBC" Slug="list-tables" Label="List tables" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html">
            <Desc><![CDATA[<p>Lists tables available to this connection. Use this in Power BI or a SQL Server Linked Server to confirm the catalog before building reports.</p>]]></Desc>
            <Code>
                <![CDATA[SHOW TABLES IN AwsDataCatalog.default]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-rows" Label="Select rows" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html">
            <Desc><![CDATA[<p>Returns rows from <code>AwsDataCatalog.default.MyTable</code>. Replace the identifier with your catalog object. Works in Excel, SSRS, and Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM AwsDataCatalog.default.MyTable]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="filter-rows" Label="Filter with WHERE" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html">
            <Desc><![CDATA[<p>Returns matching rows from <code>AwsDataCatalog.default.MyTable</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM AwsDataCatalog.default.MyTable
WHERE id = 1]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="join-tables" Label="Join tables" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html">
            <Desc><![CDATA[<p>Joins two tables on a key. Use in Azure Data Factory or SSIS when you need a combined extract.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT a.id, a.name, b.amount
FROM AwsDataCatalog.default.MyTable AS a
JOIN my_other_table AS b ON a.id = b.parent_id]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="group-by" Label="Aggregate with GROUP BY" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html">
            <Desc><![CDATA[<p>Counts rows per group. Typical Power BI import pattern before a visual.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT status, COUNT(*) AS row_count
FROM AwsDataCatalog.default.MyTable
GROUP BY status]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="order-limit" Label="Order and limit" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html">
            <Desc><![CDATA[<p>Returns the first 100 rows. Useful for preview in Excel or Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM AwsDataCatalog.default.MyTable
ORDER BY 1
LIMIT 100]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="count-all" Label="Count rows" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html">
            <Desc><![CDATA[<p>Returns the number of rows in <code>AwsDataCatalog.default.MyTable</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT COUNT(*) AS row_count FROM AwsDataCatalog.default.MyTable]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="case-expr" Label="CASE expression" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html">
            <Desc><![CDATA[<p>Maps a column to labels with <code>CASE</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT id,
       CASE WHEN status = 'A' THEN 'Active' ELSE 'Other' END AS status_label
FROM AwsDataCatalog.default.MyTable]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-list" Label="Select specific columns" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html">
            <Desc><![CDATA[<p>Returns a column list instead of star. Prefer this in Linked Server views.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT id, name, status
FROM AwsDataCatalog.default.MyTable]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="having" Label="Filter groups with HAVING" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html">
            <Desc><![CDATA[<p>Keeps groups whose count is at least 1.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT status, COUNT(*) AS row_count
FROM AwsDataCatalog.default.MyTable
GROUP BY status
HAVING COUNT(*) >= 1]]>
            </Code>
        </Example>

        <Example Default="True" Group="ODBC" Slug="query-amazon-route-53-logs-in-descending-query-timestamp-order" Label="Query Amazon Route 53 logs in descending query_timestamp order" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/querying-r53-resolver-logs-example-queries.html">
            <Desc><![CDATA[<p>Return Route 53 Resolver query logs ordered by <code>query_timestamp</code> so the newest DNS queries appear first. Useful in Power BI.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM "r53_rlogs"
ORDER BY query_timestamp DESC]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="query-amazon-emr-step-logs-for-occurrences-of-error-warn-info-exception-fatal-or-debug" Label="Query Amazon EMR step logs for occurrences of ERROR, WARN, INFO, EXCEPTION, FATAL, or DEBUG" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/emr-create-table.html">
            <Desc><![CDATA[<p>Search EMR step logs in <code>default.myemrlogs</code> for log levels. Limits to 100 matching rows.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT data,
       "$PATH"
FROM "default"."myemrlogs"
WHERE regexp_like("$PATH",'s-86URH188Z6B1')
  AND regexp_like(data, 'ERROR|WARN|INFO|EXCEPTION|FATAL|DEBUG')
LIMIT 100;]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="create-an-external-table-to-query-json-data" Label="Create an external table to query JSON data" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/querying-JSON.html">
            <Desc><![CDATA[<p>Creates <code>planets_json</code> over JSON in S3. Run this DDL once, then SELECT.</p>]]></Desc>
            <Code>
                <![CDATA[CREATE EXTERNAL TABLE `planets_json`(
  `name` string,
  `distancefromsun` double,
  `orbitalperiod` double,
  `daylength` double)
ROW FORMAT SERDE
  'org.openx.data.jsonserde.JsonSerDe'
STORED AS INPUTFORMAT
  'org.apache.hadoop.mapred.TextInputFormat'
OUTPUTFORMAT
  'org.apache.hadoop.hive.ql.io.IgnoreKeyTextOutputFormat'
LOCATION
  's3://amzn-s3-demo-bucket/json/']]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="query-json-via-created-external-table" Label="Query JSON via created external table" HelpLink="https://docs.aws.amazon.com/athena/latest/ug/querying-JSON.html">
            <Desc><![CDATA[<p>Selects from the <code>planets_json</code> external table created in the previous example.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM planets_json]]>
            </Code>
        </Example>
    </Examples>
</ApiConfig>
