ODBC & JDBC drivers for Foundry datasets（Foundry 数据集的 ODBC 和 JDBC 驱动程序）¶

The ODBC and JDBC drivers for Foundry datasets present a read-only SQL-based interface for accessing datasets from client applications (such as BI tools and ETL tools). Users can explore projects and datasets in Foundry and execute SQL queries to access tabular data. The drivers leverage Foundry SQL Server on the server side to process and execute SQL queries.

JDBC or ODBC?¶

We recommend the use of JDBC over ODBC in cases where the client application supports both protocols. The JDBC driver is easier to install and configure, and data loading is more performant.

Foundry SQL Server¶

The drivers rely on Foundry SQL Server to process and execute SQL queries against Foundry datasets. Review the Foundry SQL Server architecture documentation to learn more about the architecture and how to improve query performance.

System requirements¶

ODBC¶

Operating System	Requirements
Windows	64-bit Administrator privileges The latest Microsoft Visual C++ Redistributable installed

:::callout{theme="neutral"} The ODBC driver is currently compatible with Windows only. :::

JDBC¶

Operating System	Requirements
Windows	Minimum Java version: Java 11 Maximum Java version: Java 15
macOS
Linux

:::callout{theme="neutral"} Java 16+ is supported with extra configuration. See the guide below for more details. :::

Setup guide¶

ODBC¶

Part 1. Install the ODBC driver¶

Run the ODBC driver installer following the instructions found in Downloads: ODBC Driver.

Part 2. Configure a Data Source Name (DSN) configuration¶

To use the driver within client applications, first configure a Data Source Name (DSN) configuration for your Foundry environment:

From the Start menu, search for ODBC and open the ODBC Data Sources tool. Choose the 64-bit version.
On either the User DSN or System DSN tab, click Add... .
Select FoundrySqlDriver from the list of drivers.
Enter the following required parameters:
Data Source Name: A name for the data source on your machine.
Server: The URL of your Foundry environment; for example https://<SUBDOMAIN>.palantirfoundry.com .
Token: A security token generated from the Settings page inside Foundry. See the User-generated tokens documentation for instructions on how to obtain a token. For additional authentication options, review the Use OAuth to authenticate guide.
Click Test... to verify a successful connection, then click OK to save the DSN configuration.

See Configuration parameters for additional configuration parameters and instructions on building a connection URL.

Part 3. Configure the DSN within client applications¶

Now that you created a DSN, you can reference it from client applications that support ODBC sources. Refer to the client application documentation on ODBC sources. Below are some set-up guides for applications commonly used with Foundry:

(Optional) Part 4: Execute a SQL query¶

If supported by the client application, test a SQL query that returns rows from a Foundry dataset:

SELECT * FROM "/Path/To/Dataset" LIMIT 10

The client application may instead allow you to browse projects and select datasets to access data.

JDBC¶

Part 1: Install the JDBC driver¶

Download the JDBC driver (.jar file) which can be found on the Downloads: JDBC Driver page. Once downloaded, place the file into the appropriate location as specified in the client application's documentation for configuring JDBC connections.

Part 2: Construct the JDBC connection string¶

The JDBC connection string format is:

jdbc:foundrysql://<FOUNDRY_HOSTNAME>?Password=<TOKEN>

FOUNDRY_HOSTNAME is the hostname of your Foundry environment (such as subdomain.palantirfoundry.com).
TOKEN is a security token generated from the Settings page inside Foundry. See the User-generated tokens documentation for instructions on how to obtain a token. For additional authentication options, review the Use OAuth to authenticate guide.

Optional parameters may be specified by appending &OptionalParam=<VALUE> to the connection string. See Configuration parameters for a full list of available parameters.

If the JDBC client requires the driver class to be specified explicitly, specify com.palantir.foundry.sql.jdbc.FoundryJdbcDriver.

(Optional) Part 3: Execute a SQL query¶

If supported by the client application, test a SQL query that returns rows from a Foundry dataset:

SELECT * FROM "/Path/To/Dataset" LIMIT 10

The client application may instead allow you to browse projects and select datasets to access data.

Reference¶

Configuration parameters¶

The available configuration parameters are the same across ODBC and JDBC. Each driver can be configured in one of two ways: using a connection string within the client application, or configuring outside the client application:

	Using a connection string	Outside the client application
ODBC	`Driver=FoundrySqlDriver;BaseUrl=<FOUNDRY_HOSTNAME>;Pwd=<TOKEN>;OptionalParamOne=ABC;OptionalParamTwo=XYZ`	Configure a DSN using the Windows ODBC Data Sources tool. See Part 2. Configure a Data Source Name (DSN) configuration.
JDBC	`jdbc:foundrysql://<FOUNDRY_HOSTNAME>?Password=<TOKEN>&OptionalParamOne=ABC&OptionalParamTwo=XYZ`	Use a `foundry.ini config` file. See Configure the JDBC driver using a foundry.ini config file.

Parameter reference¶

Parameter	Connection string key	Required	Description
Foundry URL	ODBC `BaseUrl` / JDBC N/A	Yes	Foundry URL, e.g. `https://<SUBDOMAIN>.palantirfoundry.com`
Auth Token	ODBC `Pwd` / JDBC `Password`	Yes	Authentication token generated using the Foundry UI or obtained via an OAuth authentication flow.
Dataset branch	`Branch`	No	The branch on which datasets will be queried. If not set, this defaults to `master`.
Project/Catalog	`Catalog`	No	Restrict the tables the driver displays to a single Project. Set to a full Project path, such as `/MyOrg/MyProject`. Setting this property can resolve table browsing issues in some applications.
Auth Method	`AuthMethod`	No	Authentication method to use for the connection. Allowed values: `Token` (default), `OauthFlow`, or `ClientCredentials`. See Use OAuth to authenticate for guidance on using OAuth-based authentication methods.
OAuth Client ID	`OauthClientId`	No	Client ID of a third-party application registered and enabled in Foundry. Required if `AuthMethod` is set to `OauthFlow` or `ClientCredentials`. Alternatively, may be set in an application's username field.
OAuth Client Secret	`OauthClientSecret`	No	Client secret of a third-party application registered and enabled in Foundry. Required if `AuthMethod` is set to `ClientCredentials`. Alternatively, may be set in an application's password field.
Proxy host	`ProxyHost`	No	Proxy host, if required to access Foundry. Should be specified as `myproxy.example.com`, without adding a leading `http`. On Windows, the driver will automatically use a proxy if it has been set as the default Windows proxy, so this parameter may not need to be used.
Proxy port	`ProxyPort`	No	Proxy port. Required if proxy host is set.
Proxy username	`ProxyUsername`	No	Proxy username, if your proxy requires authentication. Only HTTP basic authentication is supported.
Proxy password	`ProxyPassword`	No	Proxy password. Required if proxy username is set.
Proxy auto-detect	`EnableProxyAutoDetect`	No	Whether the driver should automatically load the configured operating system proxy (if one is set). Allowed values: `true` (default) or `false`. If credentials are required, they must still be manually specified. Set to `false` to disable and use a direct connection.
SSL trust store path	`TrustStorePath`	No	Path to a custom SSL certificate trust store in `.pem` file format. Only required if the Foundry certificate is not present in the default operating system trust store.
SQL Dialect	`Dialect`	No	The SQL dialect to be used by the connection. Allowed values: `ODBC` (default), `ANSI`, or `SPARK`.
UTC Timestamps	ODBC `UtcTimestamps` / JDBC N/A	No	Whether timestamps should be returned in UTC or in the local timezone. Allowed values: `true` or `false` (default). When using BI tools and publishing reports, this setting only applies to the local DSN and may differ after publishing. This setting only applies to OBDC timestamps, as JDBC timestamps are always returned as UTC.

Type handling¶

The following table shows how Foundry types are mapped to ODBC and JDBC types.

Foundry type	ODBC type	JDBC type
Array	Encoded into JSON and returned as a string (`SQL_WVARCHAR`).	Same as ODBC
Binary	Encoded as a hexadecimal string (`SQL_WVARCHAR`) preceded by `0x`.	`byte[]`
Boolean	`SQL_BIT`	`boolean`
Byte	`SQL_TINYINT`	`byte`
Date	`SQL_DATE`	`java.sql.Date`
Decimal	`SQL_DECIMAL`	`java.math.BigDecimal`
Double	`SQL_DOUBLE`	`double`
Float	`SQL_DOUBLE`	`float`
Integer	`SQL_INTEGER`	`int`
Long	`SQL_BIGINT`	`long`
Map	Encoded into JSON and returned as a string (`SQL_WVARCHAR`).	Same as ODBC
Short	`SQL_SMALLINT`	`short`
String	`SQL_WVARCHAR`. The max string column length parameter can be set via the `StringColumnLength` property.	`java.lang.String`
Struct	Encoded into JSON and returned as a string (`SQL_WVARCHAR`).	Same as ODBC
Timestamp	`SQL_TIMESTAMP`. By default, times are converted to the system's local timezone. This can be changed via the `UtcTimestamps` property.	`java.sql.Timestamp` in UTC timezone. The `UtcTimestamps` property has no effect.

SQL dialects¶

The following table outlines some of the SQL syntax and features of available SQL dialects (see Dialect parameter in Configuration parameters).

	Spark (recommended)	ANSI, ODBC
Quoting identifiers (column names, table names)	Backticks: SELECT * FROM `/Space/Project/...`	Double quotes: `SELECT * FROM "/Space/Project/..."`
Quoting string literals	Single or double quotes: `WHERE column = 'value' OR column = "value"`	Single quotes: `WHERE column = 'value'`
Date literals	`SELECT DATE 'yyyy-mm-dd'`	Same as Spark
Current date	`SELECT CURRENT_DATE`	Same as Spark
Additional references	Spark SQL Guide: SQL Reference ↗	Supported functions: ODBC Reference ↗

Usage guides¶

Use SQL to query Foundry datasets¶

Datasets can be referenced in SQL queries by path or by RID. The SQL syntax depends on the dialect set for the connection (see Configuration parameters).

SPARK dialect¶

-- Basic SELECT
SELECT * FROM `/Path/To/Dataset`

-- Filtering with a WHERE clause
SELECT * FROM `/Path/To/Dataset`
WHERE years < 13 AND category = 'Z';

-- Using JOIN
SELECT *
FROM `/Path/To/Dataset_A` a
JOIN `/Path/To/Dataset_B` b
    ON a.id = b.fk_id;

ODBC & ANSI dialect¶

-- Basic SELECT
SELECT * FROM "/Path/To/Dataset";

-- Filtering with a WHERE clause
SELECT * FROM "/Path/To/Dataset"
WHERE years < 13 AND category = 'Z';

-- Using JOIN
SELECT *
FROM "/Path/To/Dataset_A" a
JOIN "/Path/To/Dataset_B" b
    ON a.id = b.fk_id;

See Guides: Identifying a dataset's RID or filepath for further instructions on using dataset identifiers.

Use OAuth to authenticate¶

Instead of manually generating an authentication token tied to a single Foundry account, the ODBC & JDBC drivers support OAuth 2.0 flows for additional authentication options:

Individual users: The driver opens a login prompt in your browser for you to authenticate to Foundry.
Service users: The driver connects to Foundry as the service user attached to a third-party application registered in Foundry.
External applications (for developers): A third-party application integrates with Foundry’s OAuth system to fetch tokens on behalf of its users.

When possible, we recommend using these OAuth-based options over token generation as they are more secure and allow shared use of embedded connection strings without sharing an individual user’s token.

Individual users (ODBC on Windows only)¶

The ODBC driver supports an automatic OAuth login and authorization flow when running on Windows. This flow is only supported for desktop applications installed on your computer, not for applications that you access through a web browser.

Follow the steps below to set up this flow:

(Completed by a Foundry administrator) Register a third-party application in Foundry, specifying the following configuration options:
Client type: Public client is recommended in most cases; Confidential client is supported if your use case requires it.
Authorization grant types: Enable the Authorization code grant and set the redirect URL to http://127.0.0.1/foundrydriver/oauthredirect.
Ensure the application is Registered and Enabled.
Copy the application’s Client ID from the application details screen and share with any users who are setting up an ODBC connection on their machines.
After receiving the Client ID from your Foundry administrator, set the following ODBC connection parameters:
AuthMethod = OauthFlow
OauthClientId = <YOUR_CLIENT_ID>\ Alternatively, the Client ID can be set in an application's username field instead of OauthClientId, to allow configuring credentials in-app. AuthMethod must still be set.
(Optional) If you are configuring these settings in the Windows ODBC Administrator app, you can choose the Test option to trigger the login prompt and verify that login is working.

The next time you use the driver in a client application, you will be prompted to log in to Foundry in your browser. After that, you will not need to log in every time you use the driver, though you may occasionally be prompted again.

Service users¶

For workflows not associated with individual users (such as refreshing a dashboard's data on a schedule), we recommend OAuth-based service users, leveraging third-party applications with the OAuth Client Credentials grant type. The driver authenticates to Foundry with a long-lived client ID/secret pair that is easier to manage than manually created service accounts with generated tokens.

Follow the steps below to set up OAuth for a service user:

(Completed by a Foundry administrator.) Register a third-party application in Foundry:
Client type: Choose Confidential client.
Authorization grant types: Enable the Client credentials grant, and be sure to store the Client ID and Client Secret pair in a secure location.
Ensure the application is Registered and Enabled.
Ensure that the generated service user has been granted access to any datasets that will be accessed via the ODBC or JDBC driver. The service user generated for the application is listed in the Client credentials grant details panel.
Set the following configuration parameters when configuring the driver:
AuthMethod = ClientCredentials
OauthClientId = <YOUR_CLIENT_ID>
OauthClientSecret = <YOUR_CLIENT_SECRET>\ Alternatively, the Client ID and Client Secret can be set in an application's username and password fields instead of OauthClientId and OauthClientSecret, to allow configuring credentials in-app. AuthMethod must still be set.

The driver will now connect to Foundry as the OAuth app's service user.

External applications (for developers)¶

Application developers can integrate ODBC and JDBC drivers into an application that runs its own OAuth client to manage OAuth login flows with third-party applications. This option allows full control of the login flow, including redirecting the user to authentication with Foundry and handling the authorization response after the user has completed authentication and authorization. See the writing OAuth2 clients for Foundry documentation to fetch access tokens on behalf of a Foundry user.

Once your application has obtained an access token on behalf of a user, it can be passed to the driver via the standard password property:

ODBC Pwd / JDBC Password = <ACCESS_TOKEN_OBTAINED_FROM_TOKEN_ENDPOINT>

Enable logging in the ODBC driver¶

If you need to enable driver logging to troubleshoot an issue, follow the steps below. Note that these steps may require administrator permissions.

Create a folder in which to save the logs, such as My Documents\Foundry Driver logs.
Open the Windows ODBC Data Sources tool. You can find this by searching "ODBC" in the Windows search bar. Choose the 64-bit version.
Open the System DSN tab. Select the FoundrySql source, and then select Configure. Note that it does not matter which Foundry data source you select, as the logging settings are applied to all data sources that use the Foundry driver.
Select Logging Options on the configuration window.
Set the log level to DEBUG. Set the log path to the folder you created earlier.
Select OK to save the settings.

Restart the client application and perform the action want to troubleshoot. The logs should appear in the folder you selected. If you require support from Palantir or another support team, you can compress this folder into a zip file to share.

After troubleshooting is complete, return to the ODBC Data Sources tool and disable logging by setting the log level to OFF. This step is recommended to improve performance.

Enable logging in the JDBC driver¶

The JDBC driver will discover any SLF4J logger that your Java application provides on the classpath. Specifically, your application should provide implementations of the classes org.slf4j.impl.StaticLoggerBinder and org.slf4j.impl.StaticMDCBinder. You can use a default implementation by adding slf4j-simple (version 1.X) as a project dependency.

If you have not configured an SLF4J logger, you will see the following messages printed when the driver is first loaded:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
SLF4J: Failed to load class "org.slf4j.impl.StaticMDCBinder".
SLF4J: Defaulting to no-operation MDCAdapter implementation.
SLF4J: See http://www.slf4j.org/codes.html#no_static_mdc_binder for further details.

Configure the JDBC driver using a `foundry.ini` config file¶

The JDBC driver can be configured via a config file in addition to using the connection string. To do this, create a file called foundry.ini in the same directory as where the JDBC .jar file is located.

The .ini file is divided into two sections: low-priority and high-priority. Properties specified in the low-priority section have a lower priority than connection string properties. This means that if the same property is specified in the low-priority section and in the connection string, the connection value will be used. In contrast, properties specified in the high-priority section will take precedence over connection properties. This can be useful in situations where reports are published to a server from a development machine, and the server properties need to take precedence over the development properties.

Example foundry.ini file:

[high-priority]
proxyHost=myproxy.abc
proxyPort=1234

[low-priority]
branch=production-branch

Use the JDBC driver with Java 16 and above¶

The JDBC driver supports a maximum Java version of Java 15 by default. To use the driver with Java versions 16 and above, set the --add-opens Java runtime option within your application to java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED.

Example: Java command¶

java --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED -jar your_application.jar

Example: Environment variable¶

In some cases, it is more convenient to specify the option in the _JAVA_OPTIONS environment variable, which is detected and applied automatically by some Java environments. On Unix-based systems this can be configured using the export command:

export _JAVA_OPTIONS="--add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED"

中文翻译¶

Foundry 数据集的 ODBC 和 JDBC 驱动程序¶

Foundry 数据集的 ODBC 和 JDBC 驱动程序提供了一个只读的基于 SQL 的接口，用于从客户端应用程序（如 BI 工具和 ETL 工具）访问数据集。用户可以浏览 Foundry 中的项目和数据集，并执行 SQL 查询来访问表格数据。这些驱动程序利用服务器端的 Foundry SQL Server 来处理和执行 SQL 查询。

JDBC 还是 ODBC？¶

如果客户端应用程序同时支持这两种协议，我们建议优先使用 JDBC 而非 ODBC。JDBC 驱动程序更易于安装和配置，并且数据加载性能更优。

Foundry SQL Server¶

这些驱动程序依赖 Foundry SQL Server 来处理和执行针对 Foundry 数据集的 SQL 查询。请查阅 Foundry SQL Server 架构文档，了解更多关于架构以及如何提高查询性能的信息。

系统要求¶

ODBC¶

操作系统	要求
Windows	64 位管理员权限已安装最新的 Microsoft Visual C++ Redistributable

:::callout{theme="neutral"} ODBC 驱动程序目前仅兼容 Windows 系统。 :::

JDBC¶

操作系统	要求
Windows	最低 Java 版本：Java 11 最高 Java 版本：Java 15
macOS
Linux

:::callout{theme="neutral"} Java 16 及以上版本需要额外配置才能支持。详情请参阅下面的指南。 :::

设置指南¶

ODBC¶

第 1 部分：安装 ODBC 驱动程序¶

按照下载：ODBC 驱动程序中的说明运行 ODBC 驱动程序安装程序。

第 2 部分：配置数据源名称 (DSN)¶

要在客户端应用程序中使用该驱动程序，首先需要为您的 Foundry 环境配置一个数据源名称 (DSN)：

从开始菜单中搜索 ODBC，然后打开 ODBC 数据源 工具。选择 64 位版本。
在 用户 DSN 或 系统 DSN 选项卡上，单击 添加...。
从驱动程序列表中选择 FoundrySqlDriver。
输入以下必需参数：
数据源名称： 您计算机上数据源的名称。
服务器： 您的 Foundry 环境的 URL；例如 https://<SUBDOMAIN>.palantirfoundry.com。
令牌： 从 Foundry 内部的设置页面生成的安全令牌。有关如何获取令牌的说明，请参阅用户生成的令牌文档。有关其他身份验证选项，请查阅使用 OAuth 进行身份验证指南。
单击 测试... 以验证连接是否成功，然后单击确定保存 DSN 配置。

有关其他配置参数以及如何构建连接 URL 的说明，请参阅配置参数。

第 3 部分：在客户端应用程序中配置 DSN¶

现在您已创建了 DSN，可以在支持 ODBC 源的客户端应用程序中引用它。请参阅客户端应用程序关于 ODBC 源的文档。以下是一些与 Foundry 常用应用程序的设置指南：

（可选）第 4 部分：执行 SQL 查询¶

如果客户端应用程序支持，请测试一个从 Foundry 数据集返回行的 SQL 查询：

SELECT * FROM "/Path/To/Dataset" LIMIT 10

客户端应用程序也可能允许您浏览项目并选择数据集来访问数据。

JDBC¶

第 1 部分：安装 JDBC 驱动程序¶

下载 JDBC 驱动程序（.jar 文件），可在下载：JDBC 驱动程序页面上找到。下载后，根据客户端应用程序文档中关于配置 JDBC 连接的要求，将文件放置在适当的位置。

第 2 部分：构建 JDBC 连接字符串¶

JDBC 连接字符串格式为：

jdbc:foundrysql://<FOUNDRY_HOSTNAME>?Password=<TOKEN>

FOUNDRY_HOSTNAME 是您的 Foundry 环境的主机名（例如 subdomain.palantirfoundry.com）。
TOKEN 是从 Foundry 内部的设置页面生成的安全令牌。有关如何获取令牌的说明，请参阅用户生成的令牌文档。有关其他身份验证选项，请查阅使用 OAuth 进行身份验证指南。

可以通过在连接字符串后附加 &OptionalParam=<VALUE> 来指定可选参数。有关可用参数的完整列表，请参阅配置参数。

如果 JDBC 客户端要求显式指定驱动程序类，请指定 com.palantir.foundry.sql.jdbc.FoundryJdbcDriver。

（可选）第 3 部分：执行 SQL 查询¶

如果客户端应用程序支持，请测试一个从 Foundry 数据集返回行的 SQL 查询：

SELECT * FROM "/Path/To/Dataset" LIMIT 10

客户端应用程序也可能允许您浏览项目并选择数据集来访问数据。

参考¶

配置参数¶

ODBC 和 JDBC 的可用配置参数相同。每个驱动程序可以通过以下两种方式之一进行配置：在客户端应用程序中使用连接字符串，或在客户端应用程序外部进行配置：

	使用连接字符串	在客户端应用程序外部
ODBC	`Driver=FoundrySqlDriver;BaseUrl=<FOUNDRY_HOSTNAME>;Pwd=<TOKEN>;OptionalParamOne=ABC;OptionalParamTwo=XYZ`	使用 Windows ODBC 数据源工具配置 DSN。请参阅第 2 部分：配置数据源名称 (DSN)。
JDBC	`jdbc:foundrysql://<FOUNDRY_HOSTNAME>?Password=<TOKEN>&OptionalParamOne=ABC&OptionalParamTwo=XYZ`	使用 `foundry.ini` 配置文件。请参阅使用 foundry.ini 配置文件配置 JDBC 驱动程序。

参数参考¶

参数	连接字符串键	必需	描述
Foundry URL	ODBC `BaseUrl` / JDBC 不适用	是	Foundry URL，例如 `https://<SUBDOMAIN>.palantirfoundry.com`
身份验证令牌	ODBC `Pwd` / JDBC `Password`	是	使用 Foundry UI 生成或通过 OAuth 身份验证流程获取的身份验证令牌。
数据集分支	`Branch`	否	将查询数据集的分支。如果未设置，默认为 `master`。
项目/目录	`Catalog`	否	将驱动程序显示的表限制为单个项目。设置为完整的项目路径，例如 `/MyOrg/MyProject`。设置此属性可以解决某些应用程序中的表浏览问题。
身份验证方法	`AuthMethod`	否	用于连接的身份验证方法。允许的值：`Token`（默认）、`OauthFlow` 或 `ClientCredentials`。有关使用基于 OAuth 的身份验证方法的指导，请参阅使用 OAuth 进行身份验证。
OAuth 客户端 ID	`OauthClientId`	否	在 Foundry 中注册并启用的第三方应用程序的客户端 ID。如果 `AuthMethod` 设置为 `OauthFlow` 或 `ClientCredentials`，则为必需。或者，可以在应用程序的用户名字段中设置。
OAuth 客户端密钥	`OauthClientSecret`	否	在 Foundry 中注册并启用的第三方应用程序的客户端密钥。如果 `AuthMethod` 设置为 `ClientCredentials`，则为必需。或者，可以在应用程序的密码字段中设置。
代理主机	`ProxyHost`	否	如果需要代理才能访问 Foundry，请指定代理主机。应指定为 `myproxy.example.com`，不要添加前导的 `http`。在 Windows 上，如果已将代理设置为 Windows 默认代理，驱动程序将自动使用该代理，因此可能不需要使用此参数。
代理端口	`ProxyPort`	否	代理端口。如果设置了代理主机，则为必需。
代理用户名	`ProxyUsername`	否	代理用户名，如果您的代理需要身份验证。仅支持 HTTP 基本身份验证。
代理密码	`ProxyPassword`	否	代理密码。如果设置了代理用户名，则为必需。
代理自动检测	`EnableProxyAutoDetect`	否	驱动程序是否应自动加载已配置的操作系统代理（如果已设置）。允许的值：`true`（默认）或 `false`。如果需要凭据，仍必须手动指定。设置为 `false` 以禁用并使用直接连接。
SSL 信任库路径	`TrustStorePath`	否	自定义 SSL 证书信任库的路径，格式为 `.pem` 文件。仅当 Foundry 证书不存在于默认操作系统信任库中时才需要。
SQL 方言	`Dialect`	否	连接使用的 SQL 方言。允许的值：`ODBC`（默认）、`ANSI` 或 `SPARK`。
UTC 时间戳	ODBC `UtcTimestamps` / JDBC 不适用	否	时间戳是否应以 UTC 还是本地时区返回。允许的值：`true` 或 `false`（默认）。使用 BI 工具和发布报告时，此设置仅适用于本地 DSN，并且在发布后可能会有所不同。此设置仅适用于 ODBC 时间戳，因为 JDBC 时间戳始终以 UTC 返回。

类型处理¶

下表显示了 Foundry 类型如何映射到 ODBC 和 JDBC 类型。

Foundry 类型	ODBC 类型	JDBC 类型
数组	编码为 JSON 并以字符串形式返回（`SQL_WVARCHAR`）。	与 ODBC 相同
二进制	编码为以 `0x` 开头的十六进制字符串（`SQL_WVARCHAR`）。	`byte[]`
布尔值	`SQL_BIT`	`boolean`
字节	`SQL_TINYINT`	`byte`
日期	`SQL_DATE`	`java.sql.Date`
十进制数	`SQL_DECIMAL`	`java.math.BigDecimal`
双精度浮点数	`SQL_DOUBLE`	`double`
单精度浮点数	`SQL_DOUBLE`	`float`
整数	`SQL_INTEGER`	`int`
长整数	`SQL_BIGINT`	`long`
映射	编码为 JSON 并以字符串形式返回（`SQL_WVARCHAR`）。	与 ODBC 相同
短整数	`SQL_SMALLINT`	`short`
字符串	`SQL_WVARCHAR`。最大字符串列长度参数可以通过 `StringColumnLength` 属性设置。	`java.lang.String`
结构体	编码为 JSON 并以字符串形式返回（`SQL_WVARCHAR`）。	与 ODBC 相同
时间戳	`SQL_TIMESTAMP`。默认情况下，时间会转换为系统的本地时区。可以通过 `UtcTimestamps` 属性更改此行为。	`java.sql.Timestamp`（UTC 时区）。`UtcTimestamps` 属性无效。

SQL 方言¶

下表概述了可用 SQL 方言的一些 SQL 语法和特性（请参阅配置参数中的 Dialect 参数）。

	Spark（推荐）	ANSI, ODBC
引用标识符（列名、表名）	反引号： SELECT * FROM `/Space/Project/...`	双引号： `SELECT * FROM "/Space/Project/..."`
引用字符串字面量	单引号或双引号： `WHERE column = 'value' OR column = "value"`	单引号： `WHERE column = 'value'`
日期字面量	`SELECT DATE 'yyyy-mm-dd'`	与 Spark 相同
当前日期	`SELECT CURRENT_DATE`	与 Spark 相同
其他参考	Spark SQL 指南：SQL 参考 ↗	支持的函数：ODBC 参考 ↗

使用指南¶

使用 SQL 查询 Foundry 数据集¶

可以通过路径或 RID 在 SQL 查询中引用数据集。SQL 语法取决于为连接设置的方言（请参阅配置参数）。

SPARK 方言¶

-- 基本 SELECT
SELECT * FROM `/Path/To/Dataset`

-- 使用 WHERE 子句进行过滤
SELECT * FROM `/Path/To/Dataset`
WHERE years < 13 AND category = 'Z';

-- 使用 JOIN
SELECT *
FROM `/Path/To/Dataset_A` a
JOIN `/Path/To/Dataset_B` b
    ON a.id = b.fk_id;

ODBC 和 ANSI 方言¶

-- 基本 SELECT
SELECT * FROM "/Path/To/Dataset";

-- 使用 WHERE 子句进行过滤
SELECT * FROM "/Path/To/Dataset"
WHERE years < 13 AND category = 'Z';

-- 使用 JOIN
SELECT *
FROM "/Path/To/Dataset_A" a
JOIN "/Path/To/Dataset_B" b
    ON a.id = b.fk_id;

有关使用数据集标识符的更多说明，请参阅指南：识别数据集的 RID 或文件路径。

使用 OAuth 进行身份验证¶

ODBC 和 JDBC 驱动程序支持 OAuth 2.0 流程，以提供额外的身份验证选项，而无需手动生成绑定到单个 Foundry 帐户的身份验证令牌：

个人用户： 驱动程序会在您的浏览器中打开一个登录提示，供您向 Foundry 进行身份验证。
服务用户：驱动程序以附加到 Foundry 中注册的第三方应用程序的服务用户身份连接到 Foundry。
外部应用程序（面向开发者）：第三方应用程序与 Foundry 的 OAuth 系统集成，代表其用户获取令牌。

在可能的情况下，我们建议使用这些基于 OAuth 的选项，而不是生成令牌，因为它们更安全，并且允许共享使用嵌入式连接字符串，而无需共享单个用户的令牌。

个人用户（仅限 Windows 上的 ODBC）¶

ODBC 驱动程序在 Windows 上运行时支持自动的 OAuth 登录和授权流程。此流程仅支持安装在您计算机上的桌面应用程序，不支持通过 Web 浏览器访问的应用程序。

请按照以下步骤设置此流程：

（由 Foundry 管理员完成） 在 Foundry 中注册一个第三方应用程序，指定以下配置选项：
客户端类型： 大多数情况下建议使用 公共客户端；如果您的用例需要，也支持 机密客户端。
授权授予类型： 启用 授权码授予，并将重定向 URL 设置为 http://127.0.0.1/foundrydriver/oauthredirect。
确保应用程序已注册并启用。
从应用程序详细信息屏幕复制应用程序的 客户端 ID，并与任何在其计算机上设置 ODBC 连接的用户共享。
收到来自 Foundry 管理员的 客户端 ID 后，设置以下 ODBC 连接参数：
AuthMethod = OauthFlow
OauthClientId = <YOUR_CLIENT_ID>\ 或者，客户端 ID 可以设置在应用程序的用户名字段中，而不是 OauthClientId，以允许在应用程序内配置凭据。AuthMethod 仍必须设置。
（可选）如果您在 Windows ODBC 管理员应用程序中配置这些设置，可以选择测试选项来触发登录提示并验证登录是否正常工作。

下次您在客户端应用程序中使用该驱动程序时，系统会提示您在浏览器中登录 Foundry。之后，您无需每次使用驱动程序时都登录，但偶尔可能会再次收到提示。

服务用户¶

对于与个人用户无关的工作流程（例如按计划刷新仪表板数据），我们建议使用基于 OAuth 的服务用户，利用具有 OAuth 客户端凭据授予类型的第三方应用程序。驱动程序使用长期有效的客户端 ID/密钥对向 Foundry 进行身份验证，这比使用生成令牌的手动创建的服务帐户更易于管理。

请按照以下步骤为服务用户设置 OAuth：

（由 Foundry 管理员完成。） 在 Foundry 中注册一个第三方应用程序：
客户端类型： 选择 机密客户端。
授权授予类型： 启用 客户端凭据授予，并务必将 客户端 ID 和 客户端密钥 对存储在安全位置。
确保应用程序已注册并启用。
确保生成的服务用户已被授予访问将通过 ODBC 或 JDBC 驱动程序访问的任何数据集的权限。为应用程序生成的服务用户列在 客户端凭据授予 详细信息面板中。
配置驱动程序时设置以下配置参数：
AuthMethod = ClientCredentials
OauthClientId = <YOUR_CLIENT_ID>
OauthClientSecret = <YOUR_CLIENT_SECRET>\ 或者，客户端 ID 和 客户端密钥 可以设置在应用程序的用户名和密码字段中，而不是 OauthClientId 和 OauthClientSecret，以允许在应用程序内配置凭据。AuthMethod 仍必须设置。

驱动程序现在将以 OAuth 应用程序的服务用户身份连接到 Foundry。

外部应用程序（面向开发者）¶

应用程序开发者可以将 ODBC 和 JDBC 驱动程序集成到运行自己的 OAuth 客户端以管理第三方应用程序的 OAuth 登录流程的应用程序中。此选项允许完全控制登录流程，包括将用户重定向到 Foundry 进行身份验证，以及在用户完成身份验证和授权后处理授权响应。请参阅为 Foundry 编写 OAuth2 客户端文档，以代表 Foundry 用户获取访问令牌。

一旦您的应用程序代表用户获得了访问令牌，就可以通过标准的密码属性将其传递给驱动程序：

ODBC Pwd / JDBC Password = <从令牌端点获取的访问令牌>

在 ODBC 驱动程序中启用日志记录¶

如果您需要启用驱动程序日志记录来排查问题，请按照以下步骤操作。请注意，这些步骤可能需要管理员权限。

创建一个用于保存日志的文件夹，例如 我的文档\Foundry Driver logs。
打开 Windows ODBC 数据源 工具。您可以通过在 Windows 搜索栏中搜索 "ODBC" 来找到它。选择 64 位版本。
打开 系统 DSN 选项卡。选择 FoundrySql 源，然后选择配置。请注意，选择哪个 Foundry 数据源无关紧要，因为日志记录设置将应用于所有使用 Foundry 驱动程序的数据源。
在配置窗口中选择 日志记录选项。
将日志级别设置为 DEBUG。将日志路径设置为您之前创建的文件夹。
选择确定保存设置。

重新启动客户端应用程序并执行您想要排查的操作。日志应出现在您选择的文件夹中。如果您需要 Palantir 或其他支持团队的帮助，可以将此文件夹压缩为 zip 文件进行共享。

排查完成后，返回 ODBC 数据源 工具，通过将日志级别设置为 OFF 来禁用日志记录。建议执行此步骤以提高性能。

在 JDBC 驱动程序中启用日志记录¶

JDBC 驱动程序将发现您的 Java 应用程序在类路径上提供的任何 SLF4J 日志记录器。具体来说，您的应用程序应提供 org.slf4j.impl.StaticLoggerBinder 和 org.slf4j.impl.StaticMDCBinder 类的实现。您可以通过将 slf4j-simple（版本 1.X）添加为项目依赖项来使用默认实现。

如果您尚未配置 SLF4J 日志记录器，则在首次加载驱动程序时会看到以下消息：

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
SLF4J: Failed to load class "org.slf4j.impl.StaticMDCBinder".
SLF4J: Defaulting to no-operation MDCAdapter implementation.
SLF4J: See http://www.slf4j.org/codes.html#no_static_mdc_binder for further details.

使用 `foundry.ini` 配置文件配置 JDBC 驱动程序¶

除了使用连接字符串之外，还可以通过配置文件配置 JDBC 驱动程序。为此，请在 JDBC .jar 文件所在的目录中创建一个名为 foundry.ini 的文件。

.ini 文件分为两个部分：low-priority 和 high-priority。在 low-priority 部分中指定的属性优先级低于连接字符串属性。这意味着如果同一属性在 low-priority 部分和连接字符串中都指定了，则将使用连接字符串中的值。相反，在 high-priority 部分中指定的属性将优先于连接属性。这在以下情况下很有用：报告从开发机器发布到服务器，并且服务器属性需要优先于开发属性。

foundry.ini 文件示例：

[high-priority]
proxyHost=myproxy.abc
proxyPort=1234

[low-priority]
branch=production-branch

在 Java 16 及以上版本中使用 JDBC 驱动程序¶

JDBC 驱动程序默认支持的最高 Java 版本是 Java 15。要在 Java 16 及以上版本中使用该驱动程序，请在您的应用程序中设置 --add-opens Java 运行时选项为 java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED。

示例：Java 命令¶

java --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED -jar your_application.jar

示例：环境变量¶

在某些情况下，在 _JAVA_OPTIONS 环境变量中指定该选项更为方便，某些 Java 环境会自动检测并应用该变量。在基于 Unix 的系统上，可以使用 export 命令进行配置：

export _JAVA_OPTIONS="--add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED"

ODBC & JDBC drivers for Foundry datasets（Foundry 数据集的 ODBC 和 JDBC 驱动程序）¶

JDBC or ODBC?¶

Foundry SQL Server¶

System requirements¶

ODBC¶

JDBC¶

Setup guide¶

ODBC¶

Part 1. Install the ODBC driver¶

Part 2. Configure a Data Source Name (DSN) configuration¶

Part 3. Configure the DSN within client applications¶

(Optional) Part 4: Execute a SQL query¶

JDBC¶

Part 1: Install the JDBC driver¶

Part 2: Construct the JDBC connection string¶

(Optional) Part 3: Execute a SQL query¶

Reference¶

Configuration parameters¶

Parameter reference¶

Type handling¶

SQL dialects¶

Usage guides¶

Use SQL to query Foundry datasets¶

SPARK dialect¶

ODBC & ANSI dialect¶

Use OAuth to authenticate¶

Individual users (ODBC on Windows only)¶

Service users¶

External applications (for developers)¶

Enable logging in the ODBC driver¶

Enable logging in the JDBC driver¶

Configure the JDBC driver using a foundry.ini config file¶

Use the JDBC driver with Java 16 and above¶

Example: Java command¶

Example: Environment variable¶

中文翻译¶

Foundry 数据集的 ODBC 和 JDBC 驱动程序¶

JDBC 还是 ODBC？¶

Foundry SQL Server¶

系统要求¶

ODBC¶

JDBC¶

设置指南¶

ODBC¶

第 1 部分：安装 ODBC 驱动程序¶

第 2 部分：配置数据源名称 (DSN)¶

第 3 部分：在客户端应用程序中配置 DSN¶

（可选）第 4 部分：执行 SQL 查询¶

JDBC¶

第 1 部分：安装 JDBC 驱动程序¶

第 2 部分：构建 JDBC 连接字符串¶

（可选）第 3 部分：执行 SQL 查询¶

参考¶

配置参数¶

参数参考¶

类型处理¶

SQL 方言¶

使用指南¶

使用 SQL 查询 Foundry 数据集¶

SPARK 方言¶

ODBC 和 ANSI 方言¶

使用 OAuth 进行身份验证¶

个人用户（仅限 Windows 上的 ODBC）¶

服务用户¶

外部应用程序（面向开发者）¶

在 ODBC 驱动程序中启用日志记录¶

在 JDBC 驱动程序中启用日志记录¶

使用 foundry.ini 配置文件配置 JDBC 驱动程序¶

在 Java 16 及以上版本中使用 JDBC 驱动程序¶

示例：Java 命令¶

示例：环境变量¶

Configure the JDBC driver using a `foundry.ini` config file¶

使用 `foundry.ini` 配置文件配置 JDBC 驱动程序¶