跳转至

Arrow Flight SQL

:::callout{theme="neutral" title="Beta"} Arrow Flight SQL support is in the beta phase of development and may not be available on your enrollment. Functionality may change during active development. Contact Palantir Support to request enabling Arrow Flight SQL. :::

Arrow Flight SQL ↗ is a protocol for interacting with SQL servers. Arrow Flight SQL uses the Apache Arrow in-memory format and Flight RPC protocol for efficient and portable data transfer.

Foundry implements the Arrow Flight SQL protocol, meaning that any Flight SQL client can connect to Foundry, enabling many third-party connections without the need for custom configuration.

JDBC Driver

Arrow Flight SQL offers a JDBC driver ↗ that can be used with any JDBC-based client application, such as DBeaver ↗, DataGrip ↗, or others. Follow the instructions below to set up and use the JDBC driver in Foundry.

:::callout{theme="warning" title="Timestamp display"} As of version 19.0.0, the Flight SQL JDBC driver can display incorrect timestamp values when the client application's local timezone is not UTC. Depending on how the application reads timestamps, the timezone offset may be applied in the wrong direction. The displayed time can be wrong by twice the local UTC offset — for example, a client in UTC+1 may show timestamps two hours behind the correct value. If your client application supports configuring its timezone, we recommend setting it to UTC. :::

Part 1: Install the JDBC driver

Download the JDBC driver (.jar file) ↗. Once downloaded, place the file into the appropriate location as specified in the client application's documentation for configuring JDBC connections.

Part 2: Configure the JDBC connection

The JDBC connection string format is:

jdbc:arrow-flight-sql://<FOUNDRY_HOSTNAME>:443
  • FOUNDRY_HOSTNAME is the hostname of your Foundry environment (such as subdomain.palantirfoundry.com).

If the JDBC client requires the driver class to be specified explicitly, specify org.apache.arrow.driver.jdbc.ArrowFlightJdbcDriver.

Authenticate with a token

Authenticate using a security token generated from the Settings page in Foundry. See the user-generated tokens documentation for instructions on how to obtain a token.

If the client application provides username and password fields, set the username to token and the password to your user-generated token. This is the recommended way to provide the token.

If the client application does not provide separate credential fields, include the token directly in the connection string instead:

jdbc:arrow-flight-sql://<FOUNDRY_HOSTNAME>:443/?token=<TOKEN>

Authenticate with OAuth 2.0 client credentials

For service-to-service connections, you can authenticate using the OAuth 2.0 client credentials flow with a registered third-party application instead of a user-generated token. The third-party application must be registered as a confidential client configured with a client secret. Public clients are not supported.

Set the following connection properties on the JDBC driver:

Property Value
oauth.flow client_credentials
oauth.tokenUri https://<FOUNDRY_HOSTNAME>/multipass/api/oauth2/token
oauth.clientId The client ID of your registered third-party application.
oauth.clientSecret The client secret of your registered third-party application.
oauth.scope foundry-sql-server:query

The client application must be granted the relevant SQL operations on the resources it queries. See SQL permissions for details.

For the full set of OAuth options supported by the driver, see the Flight SQL JDBC driver OAuth documentation ↗.

(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.

For the full set of JDBC connection parameters, see the Flight SQL documentation ↗.

Roles and permissions

Access to SQL queries via Arrow Flight SQL is governed by SQL permissions. See SQL permissions for more details.

中文翻译

Arrow Flight SQL

:::callout{theme="neutral" title="Beta 测试版"} Arrow Flight SQL 支持目前处于 beta 测试版 开发阶段，您的环境中可能尚未提供。在活跃开发期间，功能可能会发生变化。请联系 Palantir 支持团队以请求启用 Arrow Flight SQL。 :::

Arrow Flight SQL ↗ 是一种用于与 SQL 服务器交互的协议。Arrow Flight SQL 采用 Apache Arrow 内存格式和 Flight RPC 协议，实现高效且可移植的数据传输。

Foundry 实现了 Arrow Flight SQL 协议，这意味着任何 Flight SQL 客户端都可以连接到 Foundry，从而实现多种第三方连接，无需进行自定义配置。

JDBC 驱动程序

Arrow Flight SQL 提供了 JDBC 驱动程序 ↗，可与任何基于 JDBC 的客户端应用程序（如 DBeaver ↗、DataGrip ↗ 等）配合使用。请按照以下说明在 Foundry 中设置和使用 JDBC 驱动程序。

:::callout{theme="warning" title="时间戳显示"} 自版本 19.0.0 起，当客户端应用程序的本地时区不是 UTC 时，Flight SQL JDBC 驱动程序可能会显示错误的时间戳值。根据应用程序读取时间戳的方式，时区偏移量可能被错误地应用。显示的时间可能比实际值偏差两倍的本地 UTC 偏移量——例如，UTC+1 时区的客户端可能显示的时间比正确值晚两小时。如果您的客户端应用程序支持配置时区，建议将其设置为 UTC。 :::

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

下载 JDBC 驱动程序（.jar 文件）↗。下载完成后，将文件放置在客户端应用程序文档中指定的用于配置 JDBC 连接的相应位置。

第 2 部分：配置 JDBC 连接

JDBC 连接字符串格式如下：

jdbc:arrow-flight-sql://<FOUNDRY_HOSTNAME>:443
  • FOUNDRY_HOSTNAME 是您的 Foundry 环境的主机名（例如 subdomain.palantirfoundry.com）。

如果 JDBC 客户端要求显式指定驱动程序类，请指定 org.apache.arrow.driver.jdbc.ArrowFlightJdbcDriver。

使用令牌进行身份验证

使用从 Foundry 的 设置 页面生成的安全令牌进行身份验证。有关如何获取令牌的说明，请参阅 用户生成令牌 文档。

如果客户端应用程序提供用户名和密码字段，请将用户名设置为 token，密码设置为您的用户生成令牌。这是提供令牌的推荐方式。

如果客户端应用程序不提供单独的凭据字段，请将令牌直接包含在连接字符串中：

jdbc:arrow-flight-sql://<FOUNDRY_HOSTNAME>:443/?token=<TOKEN>

使用 OAuth 2.0 客户端凭据进行身份验证

对于服务到服务的连接，您可以使用 OAuth 2.0 客户端凭据流程进行身份验证，使用已注册的第三方应用程序，而不是用户生成令牌。第三方应用程序必须注册为配置了客户端密钥的 机密客户端。不支持公共客户端。

在 JDBC 驱动程序上设置以下连接属性：

属性 值
oauth.flow client_credentials
oauth.tokenUri https://<FOUNDRY_HOSTNAME>/multipass/api/oauth2/token
oauth.clientId 您注册的第三方应用程序的客户端 ID。
oauth.clientSecret 您注册的第三方应用程序的客户端密钥。
oauth.scope foundry-sql-server:query

必须授予客户端应用程序对其查询资源的相关 SQL 操作权限。有关详细信息，请参阅 SQL 权限。

有关驱动程序支持的全部 OAuth 选项，请参阅 Flight SQL JDBC 驱动程序 OAuth 文档 ↗。

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

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

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

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

有关完整的 JDBC 连接参数集，请参阅 Flight SQL 文档 ↗。

角色与权限

通过 Arrow Flight SQL 进行 SQL 查询的访问权限由 SQL 权限控制。有关更多详细信息，请参阅 SQL 权限。