如何在Oracle 23c中使用Java 17调用Property Graph特性

PGX 是 Oracle 提供的独立内存图分析引擎，不嵌入数据库进程，需单独下载配置；Oracle 23c 中不再默认启用，须用 PGX 23.4+ 版本，依赖 ojdbc17.jar ≥ 23.6、Java 17 及 --add-opens 参数，并严格区分 OraclePropertyGraph（DB-backed 只读）与 PgxGraph（内存可写）两种图加载方式。

PGX 是 Oracle 提供的内存图分析引擎，它不直接嵌入数据库进程，而是作为独立服务运行（或以嵌入模式加载），通过 Java API 对已加载的图执行 PGQL 查询和图算法。在 Oracle 23c 中，**PGX 不再是默认启用或随数据库一同部署的组件**；它需单独下载、配置，并与数据库配合使用（例如从 Oracle Database 加载图数据）。Java 17 是官方推荐且完全支持的运行时环境。以下是你实际编码时必须面对的关键点和操作路径：

确认 PGX 版本与 ojdbc17.jar 兼容性

oracle 23c（含 23ai）对应的 pgx 最新版是 pgx 23.4 或更高（截至 2026 年初）。它要求：

ojdbc17.jar 版本 ≥ 23.6（否则 oracle.pg.rdbms.pgql 包中部分类会抛 NoClassDefFoundError）
JVM 必须启用 --add-opens java.base/java.lang=ALL-UNNAMED（PGX 内部反射访问需要）
PGX 客户端 JAR（如 pgx-client-23.4.0.jar）必须显式加入 classpath，它不包含在 ojdbc17.jar 中

加载图到 PGX 的两种方式不能混用

你无法“直接用 Java 17 调用数据库里的图”——必须先将图数据导入 PGX 实例。常见错误是以为 CREATE PROPERTY GRAPH 语句一执行，PGX 就自动感知该图。

从 Oracle DB 加载：用 oracle.pg.rdbms.pgql 包中的 OraclePropertyGraph 类，通过 JDBC 连接串 + 图名初始化，再调 load()。这依赖数据库中已存在用 CREATE PROPERTY GRAPH 定义的图元数据（即 property graph schema）
从文件加载：用 oracle.pgx.api 包中的 PgxServer 和 PgxGraph，指定顶点/边 CSV 路径。此时图与数据库无关，PGX 完全自治
二者底层图对象类型不同：OraclePropertyGraph 是只读代理，PgxGraph 是可写内存图；混用会导致 ClassCastException 或静默失败

PGQL 查询必须区分执行上下文

同样的 PGQL 字符串，在不同 API 下行为不同：

Java Maven Code Review

审查Java Maven项目（ZIP压缩包或GitLab仓库URL），检查代码规范、命名、模块边界、可维护性问题以及重复代码。

下载

对 OraclePropertyGraph（DB-backed）：调用 queryPgql(String pgql) 返回 PgqlResultSet，结果行映射为 Map<string object></string>，字段名来自 PGQL 中的变量别名（如 SELECT n.name AS user_name → key = "user_name"）
对 PgxGraph（in-memory）：调用 queryPgql(String pgql) 返回 PgxResult，需用 .getResults() 获取 List<pgxvertex></pgxvertex> 或 List<pgxedge></pgxedge>，不支持聚合函数（如 COUNT(*)）除非启用分析模式
注意：oracle.pgx.api.PgxGraph.queryPgql() 默认不解析 GROUP BY 或 ORDER BY，这些需由 Java 层后处理；而 OraclePropertyGraph.queryPgql() 委托给数据库执行，完整支持

连接 PGX Server 时容易漏掉 wallet 配置

若 PGX Server 启用了 TLS（生产环境强制），且 Oracle DB 使用了 Oracle Wallet 存储证书，则 Java 客户端必须显式设置：

System.setProperty("oracle.pgx.wallet.dir", "/path/to/wallet")
否则报错：javax.net.ssl.SSLHandshakeException: PKIX path building failed
Wallet 目录下必须包含 cwallet.sso 和 ewallet.p12（取决于 PGX Server 启动参数）
不要试图用 JVM 的 -Djavax.net.ssl.trustStore=... 替代——PGX 客户端不读取标准 JVM SSL 参数

PGX 的 Java 集成不是“连上数据库就能跑图查询”的黑盒。最常卡住的地方，是误把数据库侧的 GRAPH_TABLE SQL 功能和 PGX 的内存图能力当成一回事。它们共存但边界清晰：前者是 SQL 引擎内建图视图，后者是独立图计算引擎。选哪条路，取决于你要实时响应（用 SQL Graph）还是深度遍历/算法（用 PGX）。