﻿<?xml version="1.0" encoding="utf-8"?>

<!-- EngineVersion = Java version -->
<ApiConfig Name="Amazon Neptune"
           Slug="amazon-neptune-connector"
           Type="JDBC"
           Category="graph"
           Id="BE114290-FB8A-59BC-B28E-DF9CBABAD136"
           Version="1"
           EngineVersion="8"
           Desc="Query Amazon Neptune graphs with SQL-Gremlin JDBC 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-neptune-connector.png"
           HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html">

    <VersionHistory>
      <Change Ver="1" Date="2026-09-15" Type="New">Initial JDBC Bridge catalog version. Hands-free JAR download. Auth Notes and SQL examples for ODBC apps.</Change>
    </VersionHistory>
    <Template>
        <Param Name="DriverDownloadPageLink"
               Value="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
        <Param Name="MvnRepositoryDriverDownloadLink"
               Value="https://mvnrepository.com/artifact/software.amazon.neptune/amazon-neptune-jdbc-driver" />
        <Param Name="DriverDownloadLinks"
               Hidden="True"
               Value="amazon-neptune-jdbc-driver-3.0.3-all.jar=https://repo1.maven.org/maven2/software/amazon/neptune/amazon-neptune-jdbc-driver/3.0.3/amazon-neptune-jdbc-driver-3.0.3-all.jar" />
    </Template>

    <Auths>
        <Auth Name="None"
              Label="None (no IAM)"
              ConnStr="jdbc:neptune:sqlgremlin://[$HostName$];port=[$Port$];authScheme=None;enableSsl=[$EnableSsl$]"
              HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="software.amazon.neptune.jdbc.NeptuneDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. software.amazon.neptune.jdbc.NeptuneDriver)." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\amazon-neptune-jdbc-driver-3.0.3-all.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/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="HostName" Label="Host" Required="True" Value="MyHostName" Desc="JDBC host name or IP (e.g. MyHostName)." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="Port" Label="TCP port" Required="True" Value="8182" Desc="JDBC port (e.g. 8182)." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="EnableSsl" Label="Enable SSL" Required="False" Options="Notset=;Yes=true;No=false" Value="true" Desc="Enable TLS for this JDBC URL (e.g. Yes from the dropdown)." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="UserName" Label="User name" Required="False" Desc="Database user. Leave empty if the server allows anonymous JDBC." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="Password" Label="Password" Required="False" Secret="True" Desc="Database password. Leave empty if no password is required." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
            </Params>
            <Notes>
                <![CDATA[<p>Amazon Neptune JDBC (SQL-Gremlin) from Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools. Neptune is VPC-only. Use this Auth when IAM DB authentication is off, or when you already opened an SSH tunnel to port 8182.</p>
<ol>
  <li>Confirm the cluster endpoint in the Neptune console (not a public hostname). Default port is <code>8182</code>.</li>
  <li>From outside the VPC, open an SSH tunnel through a bastion in the same VPC, or run JDBC Bridge on an EC2 host that can reach the cluster.</li>
  <li>Enable SSL on the cluster. After Finish, replace the host (e.g. MyHostName) on the DSN Main UI. Keep <code>authScheme=None</code> for this profile.</li>
  <li>Prefer SQL-Gremlin (<code>jdbc:neptune:sqlgremlin://</code>) for Power BI and other ODBC tools. Gremlin / openCypher / SPARQL URLs are for graph-native clients.</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>
        <Auth Name="IAMSigV4"
              Label="IAM SigV4"
              ConnStr="jdbc:neptune:sqlgremlin://[$HostName$];port=[$Port$];authScheme=IAMSigV4;enableSsl=[$EnableSsl$];serviceRegion=[$serviceRegion$]"
              HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="software.amazon.neptune.jdbc.NeptuneDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. software.amazon.neptune.jdbc.NeptuneDriver)." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\amazon-neptune-jdbc-driver-3.0.3-all.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/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="HostName" Label="Host" Required="True" Value="MyHostName" Desc="JDBC host name or IP (e.g. MyHostName)." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="Port" Label="TCP port" Required="True" Value="8182" Desc="JDBC port (e.g. 8182)." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="EnableSsl" Label="Enable SSL" Required="False" Options="Notset=;Yes=true;No=false" Value="true" Desc="Enable TLS for this JDBC URL (e.g. Yes from the dropdown)." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="serviceRegion" Label="Service region" Required="True" Value="us-east-1" Desc="AWS region of the Neptune cluster. Required for IAM SigV4 (e.g. us-east-1)." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="UserName" Label="Access key ID" Required="False" Desc="IAM access key ID (not a personal AWS console login). Leave empty to use an instance profile or AWS_PROFILE." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
                <Param Name="Password" Label="Secret access key" Required="False" Secret="True" Desc="IAM secret access key for the same access key ID. Leave empty for the default credential chain." HelpLink="https://docs.aws.amazon.com/neptune/latest/userguide/neptune-jdbc.html" />
            </Params>
            <Notes>
                <![CDATA[<p>IAM SigV4 for Neptune JDBC. SSL is required. Create IAM access keys in the console (same idea as a Stripe secret key), or rely on the default credential chain on an EC2 instance / role.</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 Neptune connect/query permissions. Do not use a personal employee login for unattended Linked Server or Power BI refresh.</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. Alternatively leave them empty and use an instance profile / <code>AWS_PROFILE</code>.</li>
  <li>Set <strong>Service region</strong> to the cluster region (for example <code>us-east-1</code>). Keep <code>enableSsl=true</code>.</li>
  <li>Neptune has no public endpoint. After Finish, replace the host (e.g. MyHostName) (and SSH-tunnel port if you forwarded 8182 locally).</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 Default="True" Group="ODBC" Slug="list-tables" Label="List tables" HelpLink="https://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <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[SELECT * FROM country]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-rows" Label="Select rows" HelpLink="https://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <Desc><![CDATA[<p>Returns rows from <code>country</code>. Replace the identifier with your catalog object. Works in Excel, SSRS, and Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM country]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="filter-rows" Label="Filter with WHERE" HelpLink="https://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <Desc><![CDATA[<p>Returns matching rows from <code>country</code>. Swap the column and literal for your schema.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM country
WHERE id = 1]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="join-tables" Label="Join tables" HelpLink="https://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <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 country 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://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <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 country
GROUP BY status]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="having" Label="Filter groups with HAVING" HelpLink="https://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <Desc><![CDATA[<p>Keeps groups whose count is at least 10.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT status, COUNT(*) AS row_count
FROM country
GROUP BY status
HAVING COUNT(*) >= 10]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="order-limit" Label="Order and limit" HelpLink="https://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <Desc><![CDATA[<p>Returns the first 100 rows ordered by a column. Useful for preview in Excel or Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM country
ORDER BY id
LIMIT 100]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="count-all" Label="Count rows" HelpLink="https://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <Desc><![CDATA[<p>Returns the number of rows in <code>country</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT COUNT(*) AS row_count FROM country]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="case-expr" Label="CASE expression" HelpLink="https://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <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 country]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-list" Label="Select specific columns" HelpLink="https://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <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 country]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="filter-name" Label="Filter by name" HelpLink="https://github.com/aws/amazon-neptune-jdbc-driver/blob/develop/markdown/sql.md">
            <Desc><![CDATA[<p>Returns countries whose DESC label matches a literal. Swap the vertex label and property for your graph.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM country
WHERE DESC = 'Canada']]>
            </Code>
        </Example>
    </Examples>
</ApiConfig>
