Vertica 集成 IBM InfoSphere DataStage¶

本文整理自 Vertica 官方 DataStage 连接指南，补充了配置项原理解析和故障排查根因分析。

关于 Vertica 连接指南¶

Vertica 连接指南提供将第三方合作伙伴产品连接到 Vertica 的基本说明，基于 Vertica 与合作伙伴产品的实际测试。

1. DataStage 概述¶

IBM InfoSphere DataStage 是一款企业级 ETL 工具，用于将源系统数据集成并转换为数据市场和数仓。其客户端包含四个核心组件：

组件	功能	使用场景
Administrator Client	项目管理	创建项目、配置环境变量、管理用户权限
Designer Client	作业设计	拖拽式设计 ETL 作业（Pipeline），定义数据流和转换逻辑
Director Client	作业运维	运行、监控、调度作业，查看执行日志
Metadata Asset Manager	元数据导入	通过 JDBC 批量导入数据库表定义（Web 控制台）

DataStage 与 Vertica 的连接方式：DataStage 同时支持 ODBC 和 JDBC 两种通道连接 Vertica。ODBC 用于在 Designer Client 中直接导入表定义；JDBC 通过 Metadata Asset Manager 批量导入元数据。

2. 环境准备¶

2.1 安装 DataStage¶

从 IBM Support 下载对应操作系统的 DataStage 安装包
参阅 IBM Knowledge Center 中对应版本的安装说明
按说明完成 DataStage 服务器端和客户端的安装

2.2 安装 Vertica 客户端驱动¶

DataStage 需要同时安装 JDBC 和 ODBC 两种 Vertica 驱动：

驱动	用途	安装方式
JDBC	Metadata Asset Manager 元数据导入	将 `.jar` 复制到 DataStage 外部库目录
ODBC	Designer Client 表定义导入 + 作业运行时连接	按标准 ODBC 安装 + 创建 DSN

安装步骤：

访问 Vertica Client Drivers 页面
下载与 DataStage 操作系统架构（32/64 位）和 Vertica 服务器版本兼容的驱动包
JDBC：按 Installing the Client Drivers and Tools on Windows 说明安装，将 .jar 文件拷贝到 DataStage 外部库目录
ODBC：按 Creating an ODBC Data Source Name (DSN) 创建系统 DSN

兼容性提示：Vertica 驱动向前兼容，详见 Client Driver and Server Version Compatibility。

3. 项目环境变量配置¶

在创建 DataStage 项目之前，必须配置与 Vertica 交互相关的环境变量。这些变量影响数据传输块大小、并行度、超时和调试信息。

3.1 配置入口¶

打开 Administrator Client（IBM InfoSphere DataStage and QualityStage Administrator）
输入凭据登录
选择 Projects 选项卡 → 选择项目 → Properties → Environment

3.2 环境变量一览¶

并行传输性能¶

变量	分类	推荐值	作用
`APT_DEFAULT_TRANSPORT_BLOCK_SIZE`	Parallel	`10000000`（≈10 MB）	数据传输块大小（字节），增大可避免 "String data right truncation" 错误
`APT_IO_MAXIMUM_OUTSTANDING`	Parallel	`2097152`	最大未完成 I/O 请求数，控制并行读写吞吐量
`APT_USE_IPV4`	Parallel	`True`	强制使用 IPv4 协议（避免 IPv6 环境下的连接问题）

超时控制¶

变量	分类	推荐值	作用
`APT_PM_CONDUCTOR_TIMEOUT`	User-Defined	`320`	Conductor 节点超时时间（秒），复杂作业需要较长超时
`APT_PM_PLAYER_TIMEOUT`	User-Defined	`120`	Player 节点超时时间（秒）

调试与报告¶

变量	分类	推荐值	作用
`APT_PM_SHOW_PIDS`	Parallel > Reporting	`True`	显示进程 PID，便于故障排查
`APT_PM_PLAYER_TIMING`	Parallel > Reporting	`True`	显示各 Player 节点的执行耗时
`APT_PM_SHOWRSH`	Parallel > Reporting	`True`	显示远程 Shell 命令，便于调试
`APT_DUMP_SCORE`	Parallel > Reporting	`True`	输出作业执行计划的 Score 信息
`APT_STARTUP_STATUS`	Parallel > Reporting	`True`	显示启动阶段状态信息

其他¶

变量	分类	推荐值	作用
`APT_PMCONDUCTOR_HOSTNAME`	Parallel	当前机器名	指定 Conductor 节点主机名

4. 连接 DataStage 到 Vertica¶

DataStage 提供两条连接到 Vertica 的路径，各自有不同的适用场景。

4.1 ODBC 通道¶

ODBC 用于在 Designer Client 中导入表定义，以及在 Parallel Job 的 ODBC Connector 阶段中读写 Vertica。

4.1.1 配置 ODBC DSN¶

⚠️ 重要：DataStage Client 使用 32 位 ODBC DSN，必须通过 32 位 ODBC 数据源管理器配置。

打开 Control Panel → Administrative Tools → ODBC Data Source Administrator (32-bit)
创建 System DSN，选择 Vertica 驱动
填入服务器 IP、端口（默认 5433）、数据库名、用户名
点击 Test Connection 验证连通性

4.1.2 通过 ODBC 导入表定义¶

在 Designer Client 中选择 Import → Table Definitions → ODBC Table Definitions
从 DSN 下拉列表选择对应的数据源名称
输入数据库凭据，点击 OK
在 Import Meta Data 窗口中：
选择 DSN
输入凭据
勾选所需表，点击 Import
DataStage 验证 ODBC 配置并列出该数据库上的表，导入的表定义显示在 Table Definitions 文件夹中

4.1.3 DSN 列表为空的处理¶

如果 Import Meta Data 页面的 DSN 下拉列表为空，检查 DSHOME/Projects 目录下的 uvodbc.config 文件，确保包含正确的 DSHOME 路径：

DSHOME=C:\IBM\InformationServer\Server\DSEngine

4.2 JDBC 通道¶

JDBC 通过 Metadata Asset Manager（Web 控制台）批量导入 Vertica 的表和视图定义。

4.2.1 配置 JDBC 连接¶

编辑 DSHOME 目录下的 isjdbc.config 文件（Windows 上默认为 C:\IBM\InformationServer\Server\DSEngine\isjdbc.config），追加 Vertica JDBC 驱动的类路径：

CLASSPATH=/opt/vertica/vertica-jdbc-23.4.0.jar;
CLASS_NAMES=com.vertica.jdbc.Driver;

确保 isjdbc.config 文件对 DataStage 服务账户（如 dsadm）具有读取权限。

4.2.2 通过 Metadata Asset Manager 导入元数据¶

浏览器访问 Metadata Asset Manager：https://<server-IP>:<port>/ibm/iis/imam/console
登录后，点击 Import → New Import Area
填写 Import Area 名称，选择 Metadata Interchange Server
选择连接器：IBM → JDBC Connector
创建新的数据连接：
Name：连接名称
URL：jdbc:vertica://<hostname>:5433/<db_name>
User name / Password：数据库凭据
点击 Test Connection 验证
选择要导入的资产（表和视图），可按 schema 名称或表名过滤
选择目标主机和数据库，提供导入描述
选择 Express Import 或 Managed Import，点击 Import
导入完成后，在 Designer Client 中通过 Repository → Metadata Sharing → Create Table Definition from shared Table 创建表定义

5. 关键注意事项¶

5.1 必须使用 Parallel Job¶

⚠️ 创建 DataStage 作业时，必须使用 Parallel Job 类型。

Parallel Job：同时包含 ODBC 和 JDBC 连接器，支持并行数据处理
Serial Job：仅包含 ODBC 连接器，无 JDBC 支持，不适合 Vertica 的数据量级

连接 Vertica 时，在 Stage 属性中从 Database 下拉菜单选择 ODBC 或 JDBC 连接器。

5.2 Transport Block Size 的重要性¶

APT_DEFAULT_TRANSPORT_BLOCK_SIZE 是影响 Vertica 数据传输稳定性的最关键参数：

默认值较小，写入宽行（如 LONG VARCHAR）时可能触发 "String data right truncation" 错误
推荐值 10000000（10 MB），可有效避免此问题
此参数控制的是 DataStage 内部各 Stage 之间传输数据块的缓冲区大小

5.3 LOB 数据的 Array Size 限制¶

读取 LOB（Large Object）类型字段时，ODBC Connector 阶段的 Array Size 必须设为 1。否则会报错：

The array size must be set to 1 when reading LOBs

6. 故障排查¶

6.1 String Data Right Truncation（数据截断）¶

错误信息：

ODBC function "SQLPutData()" reported: SQLSTATE = 22001: Native Error Code = 10,170:
Msg = [Vertica][ODBC] (10170) String data right truncation on data from data source

根因：DataStage 传输块大小不足以容纳宽列数据，导致字符串右侧被截断。

解决：将 APT_DEFAULT_TRANSPORT_BLOCK_SIZE 设置为 10000000（10 MB）。详见第 3.2 节环境变量配置。

6.2 ODBC Connector Array Size 与 LOB 不兼容¶

错误信息：

ODBC_Connector_0,0: The array size must be set to 1 when reading LOBs

根因：ODBC Connector 的 Array Size 参数用于批量获取行以提高吞吐量，但 LOB 类型不支持批量读取。

解决：在 DataStage Designer 中，将 ODBC Connector 阶段的 Array Size 属性值改为 1。

6.3 DSN 下拉列表为空¶

现象：在 Import Meta Data (ODBC) 页面，DSN 下拉列表不显示任何值。

根因：uvodbc.config 文件中缺少正确的 DSHOME 路径配置。

解决：编辑 DSHOME/Projects 目录下的 uvodbc.config 文件，添加：

DSHOME=C:\IBM\InformationServer\Server\DSEngine

6.4 JDBC 连接权限问题¶

现象：使用 JDBC 访问 Vertica 时报错。

根因：DataStage 服务账户（dsadm）没有 isjdbc.config 文件的读取权限。

解决：为 dsadm 用户或所有用户赋予 isjdbc.config 的读取权限。文件位于 DSEngine 目录（如 C:\IBM\InformationServer\Server\DSEngine\isjdbc.config）。

6.5 NUMERIC 精度超限（Pxbridge 错误）¶

错误信息：

Error in "pxbridge" operator: Parsing parameters "1024,0" for schema type "decimal":
Precision must be > 0 and <= 255, got: "1024"

根因：Vertica 的 NUMERIC 类型支持最高 1024 位精度，但 DataStage 的 pxbridge 组件限制精度不超过 255。

解决：修改源表 DDL，将 NUMERIC 列的精度降到 1-255 范围内。

6.6 SQLGetPrivateProfileString 错误¶

现象：ODBC 驱动无法读取配置文件，通常在 Linux 环境下出现。

根因：Vertica ODBC 驱动期望在 ErrorMessagePath（默认 /opt/vertica/lib64）下找到 en-US 语言目录。

解决：在 /opt/vertica/lib64 目录下创建 en-US 子目录。

7. 已知数据类型限制¶

7.1 ODBC 通道限制¶

数据类型	限制表现	影响评估
TIME	不显示毫秒	低 — 通常 ETL 场景不依赖毫秒精度
TIMESTAMP	写入时不显示毫秒	中 — 如需精确时间戳需转换格式
TIMETZ / TIMESTAMPTZ	不显示毫秒和时区偏移	中 — 时区信息丢失，需应用层补偿
NUMERIC	精度上限 255 位	中 — 大多数场景精度足够
LONG VARBINARY (8 MB) / LONG VARCHAR (32 MB)	报错 "record too big to fit in a block"	高 — 需调整 Block Size 或拆分数据
INTERVAL 系列	显示为未知数据类型	高 — 无法直接导入 INTERVAL 列
UUID	显示为未知数据类型	低 — 可转为 VARCHAR 处理

7.2 JDBC 通道限制¶

数据类型	限制表现	影响评估
INTERVAL 系列	执行作业时报 "Driver does not support"	高 — JDBC 通道完全不支持 INTERVAL
TIME	不显示毫秒	低
TIMETZ / TIMESTAMPTZ	不显示毫秒和时区偏移	中
NUMERIC	精度上限 255 位	中
LONG VARBINARY (8 MB) / LONG VARCHAR (32 MB)	尝试显示数据时界面无响应	高 — 实际不可用

7.3 限制应对策略¶

受限类型	推荐处理方式
INTERVAL	在 Vertica 侧转换为 NUMERIC 或 VARCHAR 再导入
TIMETZ / TIMESTAMPTZ	转换为 UTC 时间戳 + 独立的时区列，或统一使用 TIMESTAMP
LONG VARCHAR / LONG VARBINARY	增大 `APT_DEFAULT_TRANSPORT_BLOCK_SIZE`；或拆分为多个小字段
UUID	转为 VARCHAR(36)
TIME 毫秒精度	拆分秒和毫秒为两列，或转 NUMERIC 表示

8. 交付检查清单¶

在实际项目中交付 DataStage 集成 Vertica 时，建议逐项确认：

环境层¶

[ ] DataStage 服务器和客户端已安装（版本 ≥ 11.7）
[ ] Vertica JDBC 驱动 .jar 已放入 DataStage 外部库目录
[ ] Vertica ODBC 驱动已安装，32 位 System DSN 已创建并通过 Test Connection
[ ] isjdbc.config 已配置 CLASSPATH 和 CLASS_NAMES
[ ] isjdbc.config 对 DataStage 服务账户可读

项目配置层¶

[ ] 项目环境变量已按第 3.2 节配置（尤其 APT_DEFAULT_TRANSPORT_BLOCK_SIZE=10000000）
[ ] uvodbc.config 中 DSHOME 路径正确
[ ] Designer Client 可正常登录并连接项目

连接层¶

[ ] ODBC 表定义导入成功（目标表出现在 Table Definitions 文件夹中）
[ ] JDBC Metadata Asset Manager 导入成功（Web 控制台可见导入资产）
[ ] 作业类型为 Parallel Job（非 Serial Job）

数据验证层¶

[ ] 小批量数据测试读写正常
[ ] INTERVAL / TIMETZ 等受限类型已按要求转换
[ ] LOB 类型字段的 Array Size 已设为 1
[ ] 大批量数据写入无 "String data right truncation" 错误

总结¶

DataStage 与 Vertica 的集成的关键要点：

双通道并存：ODBC 用于 Designer Client 直连和作业运行，JDBC 用于 Metadata Asset Manager 批量元数据导入，两者互为补充
Block Size 是头号关键参数：APT_DEFAULT_TRANSPORT_BLOCK_SIZE=10000000 几乎每次交付都需要设置，否则 LONG VARCHAR 等宽列写入必定失败
作业类型务必选 Parallel：Serial Job 不支持 JDBC 且性能受限
数据类型映射是集成工作的主要工作量：INTERVAL、TIMETZ、UUID 等类型需要提前规划转换策略
32 位 ODBC 管理器是 Windows 平台上最容易踩的坑：必须使用 32 位版本配置 DSN，64 位 DataStage 客户端内部仍使用 32 位 ODBC

原文来源：https://www.vertica.com/kb/DataStageCG_HTML/Content/Partner/DataStageCG_HTML.htm

组件	版本
IBM InfoSphere DataStage	11.7.1
DataStage 平台	Windows 10 Pro（服务器 + 客户端）
Vertica 客户端	JDBC 23.4 / ODBC 23.4
Vertica 服务器	Vertica Analytic Database 23.4

Vertica 集成 IBM InfoSphere DataStage¶

关于 Vertica 连接指南¶

最新测试版本¶

1. DataStage 概述¶

2. 环境准备¶

2.1 安装 DataStage¶

2.2 安装 Vertica 客户端驱动¶

3. 项目环境变量配置¶

3.1 配置入口¶

3.2 环境变量一览¶

并行传输性能¶

超时控制¶

调试与报告¶

其他¶

4. 连接 DataStage 到 Vertica¶

4.1 ODBC 通道¶

4.1.1 配置 ODBC DSN¶

4.1.2 通过 ODBC 导入表定义¶

4.1.3 DSN 列表为空的处理¶

4.2 JDBC 通道¶

4.2.1 配置 JDBC 连接¶

4.2.2 通过 Metadata Asset Manager 导入元数据¶

5. 关键注意事项¶

5.1 必须使用 Parallel Job¶

5.2 Transport Block Size 的重要性¶

5.3 LOB 数据的 Array Size 限制¶

6. 故障排查¶

6.1 String Data Right Truncation（数据截断）¶

6.2 ODBC Connector Array Size 与 LOB 不兼容¶

6.3 DSN 下拉列表为空¶

6.4 JDBC 连接权限问题¶

6.5 NUMERIC 精度超限（Pxbridge 错误）¶

6.6 SQLGetPrivateProfileString 错误¶

7. 已知数据类型限制¶

7.1 ODBC 通道限制¶

7.2 JDBC 通道限制¶

7.3 限制应对策略¶

8. 交付检查清单¶

环境层¶

项目配置层¶

连接层¶

数据验证层¶

总结¶