﻿<?xml version="1.0" encoding="utf-8"?>

<!-- EngineVersion = Java version -->
<ApiConfig Name="Apache Cassandra"
           Slug="apache-cassandra-connector"
           Type="JDBC"
           Category="no-sql"
           Id="92AA3F01-6C7E-5525-82C6-905DC818892D"
           Version="1"
           EngineVersion="8"
           Desc="Query Apache Cassandra, Amazon Keyspaces, and ScyllaDB with 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/apache-cassandra-connector.png"
           HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper">

    <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://github.com/ing-bank/cassandra-jdbc-wrapper" />
        <Param Name="MvnRepositoryDriverDownloadLink"
               Value="https://mvnrepository.com/artifact/com.ing.data/cassandra-jdbc-wrapper" />
        <Param Name="DriverDownloadLinks"
               Hidden="True"
               Value="cassandra-jdbc-wrapper-4.15.0-bundle.jar=https://github.com/ing-bank/cassandra-jdbc-wrapper/releases/download/v4.15.0/cassandra-jdbc-wrapper-4.15.0-bundle.jar" />
        <EndPoint Name="AdditionalDriverDownloadInstructions">
            <Body>
                <![CDATA[<li>
            <p>
                Prefer the GitHub <strong>bundle</strong> JAR
                (<a href="https://github.com/ing-bank/cassandra-jdbc-wrapper/releases/download/v4.15.0/cassandra-jdbc-wrapper-4.15.0-bundle.jar" target="_blank">cassandra-jdbc-wrapper-4.15.0-bundle.jar</a>).
                The thin Maven artifact does not include the DataStax Java driver.
            </p>
        </li>]]>
            </Body>
        </EndPoint>
    </Template>

    <Auths>
        <Auth Name="Default"
              Label="Default"
              ConnStr="jdbc:cassandra://[$HostName$]:[$Port$]/[$Keyspace$]?localdatacenter=[$LocalDataCenter$]"
              HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="com.ing.data.cassandra.jdbc.CassandraDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. com.ing.data.cassandra.jdbc.CassandraDriver)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\cassandra-jdbc-wrapper-4.15.0-bundle.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="HostName" Label="Host" Required="True" Value="MyHostName" Desc="JDBC host name or IP (e.g. MyHostName)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="Port" Label="TCP port" Required="True" Value="9042" Desc="JDBC port (e.g. 9042)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="Keyspace" Label="Keyspace" Required="True" Value="MyKeyspace" Desc="Cassandra keyspace (e.g. MyKeyspace)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="LocalDataCenter" Label="Local data center" Required="True" Value="DC1" Desc="Cassandra local datacenter (e.g. DC1)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="UserName" Label="User name" Required="False" Desc="Database user. Leave empty if the server allows anonymous JDBC." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="Password" Label="Password" Required="False" Secret="True" Desc="Database password. Leave empty if no password is required." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
            </Params>
            <Notes>
                <![CDATA[<p>Apache Cassandra JDBC (ING wrapper + DataStax Java driver bundle) from Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools. One tile covers Cassandra, Amazon Keyspaces, and ScyllaDB -- edit the JDBC URL after Finish rather than picking a second connector.</p>
<ol>
  <li>Note contact points (host1, host2), native port (default <code>9042</code>), keyspace, and local datacenter name (required by the default load-balancing policy).</li>
  <li>Create a Cassandra role if the cluster requires authentication. Paste user and password. Lab clusters sometimes allow empty credentials.</li>
  <li>The wizard downloads the GitHub <strong>bundle</strong> JAR (shaded with the DataStax driver). Do not use the thin Maven JAR alone.</li>
  <li>After Finish, replace hosts (e.g. MyHostName), port (e.g. 9042), keyspace (e.g. MyKeyspace), and local datacenter (e.g. DC1). The driver uses <code>--</code> between hosts (not a comma).</li>
  <li>Amazon Keyspaces: use <code>jdbc:cassandra:aws://cassandra.REGION.amazonaws.com:9142/keyspace?awsregion=REGION</code> plus SSL/IAM as in the AWS Keyspaces Java-driver docs. ScyllaDB uses the same <code>jdbc:cassandra://</code> URL on port 9042.</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="Ssl"
              Label="SSL"
              ConnStr="jdbc:cassandra://[$HostName$]:[$Port$]/[$Keyspace$]?localdatacenter=[$LocalDataCenter$]&amp;enablessl=[$EnableSsl$]"
              HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="com.ing.data.cassandra.jdbc.CassandraDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. com.ing.data.cassandra.jdbc.CassandraDriver)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\cassandra-jdbc-wrapper-4.15.0-bundle.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="HostName" Label="Host" Required="True" Value="MyHostName" Desc="JDBC host name or IP (e.g. MyHostName)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="Port" Label="TCP port" Required="True" Value="9042" Desc="JDBC port (e.g. 9042)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="Keyspace" Label="Keyspace" Required="True" Value="MyKeyspace" Desc="Cassandra keyspace (e.g. MyKeyspace)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="LocalDataCenter" Label="Local data center" Required="True" Value="DC1" Desc="Cassandra local datacenter (e.g. DC1)." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <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://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="UserName" Label="User name" Required="False" Desc="Database user. Leave empty if the server allows anonymous JDBC." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
                <Param Name="Password" Label="Password" Required="False" Secret="True" Desc="Database password. Leave empty if no password is required." HelpLink="https://github.com/ing-bank/cassandra-jdbc-wrapper" />
            </Params>
            <Notes>
                <![CDATA[<p>Cassandra / Scylla / Keyspaces with SSL. The bundle JAR still applies. Set JSSE truststore properties on the Bridge JVM when the cluster uses a private CA.</p>
<ol>
  <li>Enable client-to-node encryption on the cluster (or use Amazon Keyspaces, which requires TLS on 9142).</li>
  <li>This Auth sets <code>enablessl=true</code>. Point <code>javax.net.ssl.trustStore</code> at a JKS that trusts the cluster CA if the default Java truststore is not enough.</li>
  <li>Create a database role. Paste user and password. For Keyspaces IAM, keep this tile and put access-key style credentials in user/password after switching the URL to the <code>jdbc:cassandra:aws://</code> form -- do not add a second catalog tile.</li>
  <li>After Finish, replace hosts (e.g. MyHostName), keyspace (e.g. MyKeyspace), and local datacenter (for Keyspaces, local datacenter is the AWS region name).</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://cassandra.apache.org/doc/latest/cassandra/cql/">
            <Desc><![CDATA[<p>Lists tables in <code>MyKeyspace</code> from <code>system_schema</code>. Use this in Power BI or a SQL Server Linked Server to confirm the catalog.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT table_name
FROM system_schema.tables
WHERE keyspace_name = 'MyKeyspace']]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-rows" Label="Select rows" HelpLink="https://cassandra.apache.org/doc/latest/cassandra/cql/">
            <Desc><![CDATA[<p>Returns rows from <code>MyKeyspace.users</code>. Replace the keyspace and table. Works in Excel, SSRS, and Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM MyKeyspace.users]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="filter-rows" Label="Filter on primary key" HelpLink="https://cassandra.apache.org/doc/latest/cassandra/cql/">
            <Desc><![CDATA[<p>Returns one partition. Cassandra requires a primary-key restriction for efficient reads.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM MyKeyspace.users
WHERE id = 1]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="allow-filtering" Label="ALLOW FILTERING (lab only)" HelpLink="https://cassandra.apache.org/doc/latest/cassandra/cql/">
            <Desc><![CDATA[<p>Reads with a non-key filter. Avoid on large tables in production; prefer a secondary index or a new table.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM MyKeyspace.users
WHERE status = 'A'
ALLOW FILTERING]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-list" Label="Select specific columns" HelpLink="https://cassandra.apache.org/doc/latest/cassandra/cql/">
            <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 MyKeyspace.users]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="in-list" Label="IN list on partition key" HelpLink="https://cassandra.apache.org/doc/latest/cassandra/cql/">
            <Desc><![CDATA[<p>Returns several partitions. Use in Azure Data Factory when you extract a known id set.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT id, name, status
FROM MyKeyspace.users
WHERE id IN (1, 2, 3)]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="order-limit" Label="Clustering order and limit" HelpLink="https://cassandra.apache.org/doc/latest/cassandra/cql/">
            <Desc><![CDATA[<p>Returns the first 100 rows of a partition in clustering order. Preview in Excel or Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM MyKeyspace.users
WHERE id = 1
ORDER BY created_at DESC
LIMIT 100]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="count-all" Label="Count rows" HelpLink="https://cassandra.apache.org/doc/latest/cassandra/cql/">
            <Desc><![CDATA[<p>Counts rows in <code>MyKeyspace.users</code>. On large tables this is expensive; prefer a counter table for dashboards.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT COUNT(*) AS row_count FROM MyKeyspace.users]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="group-by" Label="GROUP BY partition key" HelpLink="https://cassandra.apache.org/doc/latest/cassandra/cql/">
            <Desc><![CDATA[<p>Aggregates per partition. CQL GROUP BY must follow the primary-key prefix.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT status, COUNT(*) AS row_count
FROM MyKeyspace.users
WHERE id = 1
GROUP BY id, status]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="list-keyspaces" Label="List keyspaces" HelpLink="https://cassandra.apache.org/doc/latest/cassandra/cql/">
            <Desc><![CDATA[<p>Lists keyspaces visible to this role. Confirm Amazon Keyspaces / Scylla catalogs the same way.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT keyspace_name FROM system_schema.keyspaces]]>
            </Code>
        </Example>
    </Examples>
</ApiConfig>
