In this section
The choices you make when creating a connector can include which superclass and dialect to use, and how you want to tune your connection using Tableau capabilities.
Also be sure to read the Security Considerations page.
The class attribute is a unique key for your connector. Make it something that is unlikely to be used by another connector. When Tableau loads the connectors at startup, if the class is already registered, the connector will not be loaded. The class is also stamped in Tableau Workbook (.twb or .twbx) files and Tableau Data Source (.tds) files to identify what connector that particular connection was using.
Important note: The connector class attribute cannot be changed once the connector is released. If the connector class is changed, workbooks and datasources made with the old version of the connector will not work.
Connectors work using an inheritance pattern. The superclass refers to the Tableau native connector from which your connector inherits behavior.
Because Tableau’s native connectors have special code and optimizations that may not be appropriate for your connection, we recommend using “odbc” or “jdbc” for your superclass. These connect to and retrieve data in a standard way and can be further customized as needed.
These are available superclass values:
You might find other superclass values in the workbook XML from an existing Tableau connection, but we don’t recommend using them. They haven’t been tested.
Plugin-version is a requirement for submitting your connector to Tableau Exchange. It helps customers and partners understand which version of a connector is being used currently and if it is the most up-to-date.
You should start your plugin version with plugin-version='1.0.0' and increment it based on major or minor changes to your connector.
The min-version-tableau value is set in manifest.xml, and represents the oldest version of Tableau that the connector will work with. If the current version of Tableau is less than the min-tableau-version then the connector is not loaded.
The packager will automatically set this value based on the features the connector uses. In most cases, the value of min-version-tableau detected by the packager is accurate and no action is needed on the part of the connector author. If that value has been set manually in manifest.xml before packaging, the packager will not overwrite a min-version-tableau value that is higher than the one the packager detected, but will overwrite an existing value that is lower.
Note: version in the manifest file does not refer to plugin version. Please leave this set to version='18.1'
FAQs about Versioning
The dialect determines what SQL is generated for various Tableau actions.
Choosing the right dialect is a critical part of writing a connector. For example:
These are valid values for base:
If you want to customize the generated SQL, or if your connector inherits from ODBC or JDBC, then you need to create a custom dialect file.
Only if your database follows the SQL standards of a database that Tableau currently supports (listed above) should you consider choosing that base dialect as a starting point. Also, any new Tableau version can change those base dialects’ behavior, which may cause unintended side effects for connectors inheriting from those base dialects.
Without a dialect file, the dialect from the superclass is used. For more information, see Create a Tableau Dialect Definition (TDD) File.
Tableau capabilities are Boolean settings you can use to tune many aspects of your connector behavior based on database functionality, including:
Common capabilities and how they are used: Capabilities
Important: Your database must support subqueries or temporary tables for complete integration with Tableau. For the best user experience it is recommended both are supported.
If your database supports temp tables, we recommend that you enable them through the appropriate Capabilities. If the temp table capabilities are set, the connector will perform a simple check at connection time to confirm that the user can create a temp table in the current database environment. If the user does not have permission or the capabilities are disabled, then Tableau will attempt to generate an alternative query to retrieve the necessary results. Often these queries need subqueries and the performance can be poor, particularly with large datasets. If the connector does not support temporary tables or subqueries, then Tableau will report an error and will be unable to proceed.
A common example is filtering the top three regions by sum of sales. You can try this using our Staples sample table by dragging [Market Segment] to Rows, then drag it again to Filters. Click the Top tab and select [Sales Total] aggregated by sum.
There are some capabilities for which Tableau either cannot provide a sensible default, or the platform default and current recommendation are different for backwards compatibility reasons.
Review the full list of latest recommendations, highlighted in Red, when writing a connector.
Common customizations:
Does your database support null column metadata? Tableau relies on accurate column metadata from the ODBC or JDBC result set in order to make certain query optimizations. If information about whether a column contains null values is inaccurate, Tableau may generate inefficient or incorrect queries. If your database does not support null column information, then it is safer to indicate that all columns contain null values. This ensures that Tableau does not generate an optimized query that actually returns incorrect results. Tableau uses “SQLColAttribute” with “SQL_DESC_NULLABLE” on the result set metadata for ODBC connections and the “isNullable” method on the “ResultSetMetaData” object for JDBC.