Apache Rya 配置参数详解
Apache Rya 4.0.1 配置参数详解：通用键位（query.tblprefix 默认 rya_、tbl.spo/po/osp/ns）、Accumulo 连接键位与 web.rya environment.properties 映射
Apache Rya 配置参数详解
目标：详解 Apache Rya 4.0.1 的配置参数体系。Rya 是库形态组件，配置分三层：
RdfCloudTripleStoreConfiguration通用键位（表布局/查询行为/推断开关）、AbstractAccumuloRdfConfigurationBuilder的 Accumulo 连接键位、web.rya的environment.properties映射。本文列出键位、默认值与实测验证结果（含 RyaShellprint-instance-details回显），所有键位来自 4.0.1 源码与 Ubuntu 22.04 + JDK 8 实测环境。
⚠️ 受限前置说明：Rya 主存储必须为 Accumulo（含 ZooKeeper、Hadoop 依赖），无独立 standalone 模式；配置键位面向 Accumulo 后端（
accumulo.*前缀），MongoDB 后端为实验性 profile（install-with-mongo-parameters），本批未实测。生产部署需自行准备 Accumulo 1.6.4 + ZooKeeper 3.4.6 + Hadoop 2.5.0 集群，本批以 MiniAccumuloCluster 伪集群实测验证默认配置行为。
一、环境信息
- 操作系统：Ubuntu 22.04 LTS
- Java：OpenJDK 1.8.0_504；构建工具：Apache Maven 3.6.3
- Rya 版本：4.0.1（依赖 accumulo-core 1.6.4 / ZooKeeper 3.4.6 / RDF4J 2.3.1）
- 源码路径：
/opt/rya/rya-project/（键位提取自 common/rya.api 与 dao/accumulo.rya） - 实测路径：MiniAccumuloCluster 伪集群（实例 miniInstance）+ RyaShell
二、配置体系概览
| 配置层 | 载体类/文件 | 键位前缀 | 作用 |
|---|---|---|---|
| 通用查询配置 | RdfCloudTripleStoreConfiguration（common/rya.api） | query.、tbl.、infer. | 表布局、查询行为、推断开关 |
| Accumulo 连接配置 | AbstractAccumuloRdfConfigurationBuilder（dao/accumulo.rya） | accumulo.、use. | 连接参数与特性开关 |
| Web 服务配置 | web.rya 的 environment.properties（classpath） | instance.、sc.* | web.rya 指向数据库实例 |
| 安装配置 | Install.InstallConfiguration.builder()（API） | - | 附加索引开关 |
三类键位均为 Java Configuration（Apache Commons Configuration）字符串键值对，编程方式用 config.setString(key, value) / getString(key)。
三、通用查询配置键位（RdfCloudTripleStoreConfiguration）
3.1 表布局键位
| 键 | 常量 | 默认值 | 说明 |
|---|---|---|---|
query.tblprefix | CONF_TBL_PREFIX | rya_（TBL_PRFX_DEF） | 底层 Accumulo 表名前缀，实例名追加其后（如 rya_demo + spo） |
tbl.spo | CONF_TBL_SPO | rya_spo | SPO 主表 |
tbl.po | CONF_TBL_PO | rya_po | PO 倒排索引表 |
tbl.osp | CONF_TBL_OSP | rya_osp | OSP 倒排索引表 |
tbl.ns | CONF_TBL_NS | rya_ns | 命名空间表 |
tbl.eval | CONF_TBL_EVAL | rya_eval | 求值/统计表 |
tbl.hashprefix | CONF_PREFIX_ROW_WITH_HASH | false | 行键是否加哈希前缀（分片均衡） |
3.2 查询行为键位
| 键 | 常量 | 说明 |
|---|---|---|
query.ttl | CONF_TTL | 查询超时（毫秒） |
query.startTime | CONF_STARTTIME | 查询起始时间戳（历史查询） |
query.numthreads | CONF_NUM_THREADS | 查询线程数 |
query.performant | CONF_PERFORMANT | 高性能模式开关 |
query.infer | CONF_INFER | 是否启用 OWL/RDFS 推断 |
query.usestats | CONF_USE_STATS | 是否使用统计信息优化 |
query.usecompositecard | CONF_USE_COMPOSITE | 复合基数估算 |
query.useselectivity | CONF_USE_SELECTIVITY | 连接选择性估算 |
query.batchsize | CONF_BATCH_SIZE | 批量扫描行数 |
query.offset | CONF_OFFSET | 结果偏移量 |
query.limit | CONF_LIMIT | 结果条数上限 |
query.printqueryplan | CONF_QUERYPLAN_FLAG | 打印查询计划 |
query.auth | CONF_QUERY_AUTH | 查询可见性授权（Authorizations） |
query.resultformat | CONF_RESULT_FORMAT | 结果格式（如 SPARQL XML） |
query.optimizers | CONF_OPTIMIZERS | 自定义优化器列表 |
3.3 推断（Inference）开关键位
键位以 infer.include.* 形式控制 OWL 推断规则（query.infer=true 时生效）：infer.include.allvaluesfrom、domainrange、hasself、hasvalue、intersectionof、inverseof、oneof、propertychain、reflexiveprop、somevaluesfrom、sameas、subclassof、subpropof、symmprop、transprop，默认均为 false。
3.4 其他键位
conf.cv（confidentiality values）、use.statement.metadata 与 statement.metadata.properites（语句元数据）、pcj.query.optimizer 与 pcj.index.tables（预计算连接索引）、class.rdf.dao 与 class.rdf.evalstats（DAO 类）、conf.stats.rdftype.down（统计下推 rdf:type）。
四、Accumulo 连接配置键位（AbstractAccumuloRdfConfigurationBuilder）
| 键 | 常量 | 说明 |
|---|---|---|
accumulo.user | ACCUMULO_USER | Accumulo 用户名 |
accumulo.password | ACCUMULO_PASSWORD | Accumulo 密码 |
accumulo.instance | ACCUMULO_INSTANCE | Accumulo 实例名 |
accumulo.zookeepers | ACCUMULO_ZOOKEEPERS | ZooKeeper 地址（逗号分隔 host:port） |
accumulo.auths | ACCUMULO_AUTHS | 查询可见性标签集合（逗号分隔） |
accumulo.visibilities | ACCUMULO_VISIBILITIES | 写入数据的可见性标签 |
accumulo.rya.prefix | ACCUMULO_RYA_PREFIX | Rya 表前缀（对应 query.tblprefix） |
use.inference | USE_INFERENCE | 启用推断 |
use.display.plan | USE_DISPLAY_QUERY_PLAN | 显示查询计划 |
use.mock | USE_MOCK_ACCUMULO | 使用 MockAccumulo（内存模拟，测试用） |
use.prefix.hashing | USE_PREFIX_HASHING | 表行键哈希前缀（分片均衡） |
use.count.stats | USE_COUNT_STATS | 启用计数统计 |
use.join.selectivity | USE_JOIN_SELECTIVITY | 启用连接选择性统计 |
五、web.rya environment.properties 键位
web.rya.war 解包部署后，将 environment.properties 放入 classpath（如 WEB-INF/classes/），Spring 占位符按如下映射注入（web/web.rya 的 spring-root-extensions.xml）：
| environment.properties 键 | 注入目标 | 说明 |
|---|---|---|
instance.name | sc.cloudbase.instancename | Accumulo 实例名 |
instance.zk | sc.cloudbase.zookeepers | ZooKeeper 地址 |
instance.username | sc.cloudbase.username | Accumulo 用户名 |
instance.password | sc.cloudbase.password | Accumulo 密码 |
rya.displayqueryplan | query.printqueryplan | 是否打印查询计划 |
sc.freetext.doctable / sc.freetext.termtable | 自由文本索引表名 | 启用 freetext 索引时 |
sc.geo.table / sc.geo.predicates / sc.geo.numPartitions | 地理索引参数 | 启用 geo 索引时 |
官方示例（README.md）：
# Accumulo instance name
instance.name=accumulo
# Accumulo Zookeepers
instance.zk=localhost:2181
# Accumulo username
instance.username=root
# Accumulo password
instance.password=secret
六、安装配置与附加索引开关（InstallConfiguration）
编程安装 Rya 实例时用 Install.InstallConfiguration.builder() 控制附加索引（默认全部关闭）：
| builder 方法 | 对应开关 | 实测默认 |
|---|---|---|
setEnableTableHashPrefix(true) | 分片哈希前缀 | false |
setEnableEntityCentricIndex(true) | 实体中心索引 | false |
setEnableGeoIndex(true) | 地理索引 | false |
setEnableFreeTextIndex(true) | 自由文本索引 | false |
setEnableTemporalIndex(true) | 时间索引 | false |
setEnablePcjIndex(true) | 预计算连接（PCJ）索引 | false |
setFluoPcjAppName(...) | PCJ 增量更新 Fluo 应用名 | - |
RyaShell 命令 install-with-accumulo-parameters --instanceName <名> 安装时同样以默认配置（全部 false）安装，实测交互回显：
A Rya instance will be installed using the following values:
Instance Name: rya_shell_demo
Use Shard Balancing: false
Use Entity Centric Indexing: false
Use Free Text Indexing: false
Use Temporal Indexing: false
Use Precomputed Join Indexing: false
Continue with the install? (y/n) y
The Rya instance named 'rya_shell_demo' has been installed.
七、实测验证：默认配置行为
通过 RyaShell print-instance-details 验证默认安装的实例配置（Ubuntu 22.04 + JDK 8 + mini-accumulo 伪集群实测回显）：
rya/miniInstance:rya_shell_demo> print-instance-details
General Metadata:
Instance Name: rya_shell_demo
RYA Version: 4.0.1
Users: root
Secondary Indicies:
Entity Centric Index:
Enabled: false
Free Text Index:
Enabled: false
Temporal Index:
Enabled: false
PCJ Index:
Enabled: false
实测结论：
- 默认安装仅创建 SPO/PO/OSP/NS 基础表（
rya_<实例>spo/po/osp/ns），不创建任何附加索引，SPARQL 查询走基础三表扫描 + JOIN。 - 写入 8 条业务三元组后
COUNT(?s)返回 9，说明默认安装会额外写入 1 条实例内部元数据三元组。 query.tblprefix默认rya_在表名上直接可见（rya_demospo等）。
八、注意事项
⚠️ 注意：
- Rya 4.0.1 无独立配置文件；所有键位通过 Java
Configuration或 web.rya 的environment.properties注入，无 XML/conf 文件形态。accumulo.auths与accumulo.visibilities语义不同：auths 是查询时可见性标签集合，visibilities 是写入时给数据打的标签；root 用户需先用changeUserAuthorizations授予相应标签才能查询。- 附加索引（实体中心/自由文本/时间/PCJ）会显著增加表数量与写入开销，按需开启；
setEnablePcjIndex还需要配套 Fluo 应用（setFluoPcjAppName）。use.mock（MockAccumulo）仅适合单机测试，数据不落盘，生产必须关闭。- web.rya 是 war 形态（88M），部署到 Servlet 容器后通过
environment.properties指向 Accumulo；instance.*键映射到sc.cloudbase.*，勿直接写sc.cloudbase.*。
九、常见问题
Q1：如何修改表前缀？
设置 query.tblprefix（或 Accumulo 侧的 accumulo.rya.prefix），如 config.setString("query.tblprefix", "myrya_")；安装新实例后表名变为 myrya_<实例>spo 等。注意表前缀一旦安装不可修改，需重新安装实例。
Q2：查询返回空结果但数据已写入？
检查可见性：写入使用了 accumulo.visibilities 打标签，而查询 accumulo.auths 未包含该标签。给 root 授予 U 后查询方可命中。
Q3：query.infer 与 infer.include.* 的关系？
query.infer=true 是总开关，infer.include.* 是各条 OWL 规则的细粒度开关；默认全部关闭，推断开启会显著增加查询开销。
Q4：web.rya 启动后报连接拒绝？
确认 environment.properties 在 classpath（如 WEB-INF/classes/environment.properties），且 instance.zk 指向实际 ZooKeeper 地址；war 内默认无此文件，需自行创建。
Q5：PCJ 索引为什么查询没生效？
PCJ 索引需要 Fluo 应用持续增量更新（setEnablePcjIndex(true) + setFluoPcjAppName(...)），仅安装不启动 Fluo 时 PCJ 表为空，查询仍走基础表。