Apache Rya 常用工具与 API 详解

Apache Rya 4.0.1 常用工具与 API 详解:RyaShell CLI(connect/install/load-data/sparql-query 实测)、RyaClient API 与 web.rya REST 端点。

Apache RyaApache Rya2026/10/13

Apache Rya 常用工具与 API 详解

目标:详解 Apache Rya 4.0.1 的常用工具与 API。Rya 唯一的独立 CLI 工具是 RyaShell(Spring Shell,extras/shell 模块 shaded jar),提供连接 Accumulo、安装实例、加载 RDF 数据、执行 SPARQL 查询等命令;编程侧提供 RyaClient API(安装/加载/查询子接口)与 RyaSail(RDF4J Sail 集成);另有 web.rya REST 端点。本文命令回显均在 Ubuntu 22.04 + JDK 8 + MiniAccumuloCluster 伪集群实测。

⚠️ 受限前置说明:Rya 主存储必须为 Accumulo(含 ZooKeeper、Hadoop 依赖);所有工具(RyaShell、RyaClient、web.rya)都面向 Accumulo 后端。RyaShell 的 connect-mongo / install-with-mongo-parameters 为 MongoDB 实验性 profile,本批未实测。正式生产需自行部署 Accumulo 1.6.4 + ZooKeeper 3.4.6 + Hadoop 2.5.0 集群。

一、环境信息

  • 操作系统:Ubuntu 22.04 LTS;Java:OpenJDK 1.8.0_504;Maven 3.6.3
  • Rya 版本:4.0.1(构建产物 rya.shell-4.0.1-shaded.jar 100M、web.rya.war 88M)
  • 实测伪集群:MiniAccumuloCluster(实例 miniInstance,ZooKeeper 随机端口)
  • 测试数据:/opt/rya/shell-test/triples.nt(6 条 N-Triples)、query.sparql

二、工具概览

工具/API形态作用
RyaShellCLI(java -jar rya.shell-4.0.1-shaded.jar)连接 Accumulo、安装实例、加载数据、执行 SPARQL
RyaClientJava API(rya.api + accumulo.rya)编程方式安装/加载/查询 Rya 实例
RyaSailJava API(rya.sail)RDF4J Sail 集成,与 RDF4J Repository 体系对接
web.ryawar + RESTHTTP 加载 RDF(/loadrdf)等 Web 服务

三、RyaShell 使用

3.1 启动

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
java -jar /opt/rya/rya-project/extras/shell/target/rya.shell-4.0.1-shaded.jar

启动回显(横幅 + 版本 4.0.1):

 _____                _____ _          _ _
|  __ \              / ____| |        | | |
| |__) |   _  __ _  | (___ | |__   ___| | |
|  _  / | | |/ _` |  \___ \| '_ \ / _ \ | |
| | \ \ |_| | (_| |  ____) | | | |  __/ | |
|_|  \_\__, |\__,_| |_____/|_| |_|\___|_|_|
        __/ |
       |___/
4.0.1

Welcome to the Rya Shell.

Execute one of the connect commands to start interacting with an instance of Rya.
You may press tab at any time to see which of the commands are available.

3.2 命令清单(help,共 36 条含系统命令)

rya> help
* ! - Allows execution of operating system (OS) commands
* // - Inline comment markers (start of line only)
* ; - Inline comment markers (start of line only)
* add-user - Adds an authorized user to the Rya instance.
* clear - Clears the console
* cls - Clears the console
* connect-accumulo - Connect the shell to an instance of Accumulo.
* connect-mongo - Connect the shell to an instance of MongoDB.
* connect-rya - Connect to a specific Rya instance
* create-pcj - Creates and starts the maintenance of a new PCJ using a Fluo application.
* create-periodic-pcj - Creates and starts the maintenance of a new Periodic PCJ and registers the associated Periodic Notification with Kafka.
* date - Displays the local date and time
* delete-pcj - Deletes and halts maintenance of a PCJ.
* delete-periodic-pcj - Deletes and halts maintenance of a Periodic PCJ.
* disconnect - Disconnect the shell's Rya storage connection (Accumulo).
* exit - Exits the shell
* help - List all commands usage
* install - Create a new instance of Rya interactively.
* install-with-accumulo-parameters - Create a new Accumulo instance of Rya with command line parameters.
* install-with-mongo-parameters - Create a new MongoDB instance of Rya with command line parameters.
* list-incremental-queries - Lists relevant information about all SPARQL queries maintained by the Fluo application.
* list-instances - List the names of the installed Rya instances.
* load-data - Loads RDF Statement data from a local file to the connected Rya instance.
* print-connection-details - Print information about the Shell's Rya storage connection.
* print-instance-details - Print information about how the Rya instance is configured.
* quit - Exits the shell
* remove-user - Removes an authorized user from the Rya instance.
* script - Parses the specified resource file and executes its commands
* sparql-query - Executes the provided SPARQL Query on the connected Rya instance.
* streams-configure - Connect a Rya Streams subsystem to a Rya Instance.
* streams-details - Print information about which Rya Streams subsystem the Rya instance is connected to.
* streams-queries-add - Add a SPARQL query to the Rya Streams subsystem.
* streams-queries-delete - Delete a SPARQL query from the Rya Streams subsystem.
* streams-queries-details - Print detailed information about a specific query managed by the Rya Streams subsystem.
* streams-queries-list - List the queries that are being managed by the configured Rya Streams subsystem.
* streams-queries-start - Start processing a SPARQL query using the Rya Streams subsystem.
* streams-queries-stop - Stop processing a SPARQL query using the Rya Streams subsystem.
* system properties - Shows the shell's properties
* uninstall - Uninstall an instance of Rya.
* version - Displays shell version

3.3 常用命令签名

命令必填选项可选选项说明
connect-accumulo--username、--instanceName、--zookeepers-连接 Accumulo;无 --password 选项,交互式密码提示
connect-rya--instance-选择已安装的 Rya 实例
install-with-accumulo-parameters--instanceName-安装新 Rya 实例(交互 y/n 确认,默认配置)
load-data--file--format加载 RDF 文件;format 支持 RDF/XML、N-Triples、Turtle、N3、TriX、TriG、BinaryRDF、N-Quads、JSON-LD、RDF/JSON、RDFa
sparql-query--file-执行文件中的 SPARQL 查询
list-instances--列出已安装实例
print-connection-details--显示 Accumulo 连接参数
print-instance-details--显示实例配置与索引状态

3.4 全流程实测(连接→安装→加载→查询)

伪集群就绪后(MINI_ACCUMULO_READY instance=miniInstance zookeepers=localhost:26007),用管道喂 stdin 执行(--cmdfile 模式会因密码提示 NPE,须管道喂):

printf 'connect-accumulo --username root --instanceName miniInstance --zookeepers localhost:26007\nq1w2e3r4\ninstall-with-accumulo-parameters --instanceName rya_shell_demo\ny\nconnect-rya --instance rya_shell_demo\nload-data --file /opt/rya/shell-test/triples.nt\nsparql-query --file /opt/rya/shell-test/query.sparql\nexit\n' | java -jar rya.shell-4.0.1-shaded.jar

真实回显(关键段):

rya> connect-accumulo --username root --instanceName miniInstance --zookeepers localhost:26007
Password: ********
Connected. You must select a Rya instance to interact with next.
rya/miniInstance> install-with-accumulo-parameters --instanceName rya_shell_demo

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.
rya/miniInstance> connect-rya --instance rya_shell_demo
rya/miniInstance:rya_shell_demo> load-data --file /opt/rya/shell-test/triples.nt
Loaded the file: '/opt/rya/shell-test/triples.nt' successfully in 0.101 seconds.
rya/miniInstance:rya_shell_demo> sparql-query --file /opt/rya/shell-test/query.sparql
Executing Query...
Query Results:
name,thing
"Thing 1",http://Thing1
"Thing 3",http://Thing3
Done.
rya/miniInstance:rya_shell_demo> exit

测试数据 triples.nt 为 6 条 N-Triples:<Thing1>、<Thing2>、<Thing3> 的类型与名称(rdf:type 分别为 Monkey/Gorilla/Monkey,predicates#name 为 "Thing 1/2/3");query.sparql 查询 ?thing rdf:type <http://types#Monkey> . ?thing <predicates#name> ?name,命中 Thing 1 与 Thing 3。

3.5 管理命令实测回显

rya/miniInstance> list-instances
Rya instance names:
   rya_shell_demo

rya/miniInstance> print-connection-details
The shell is connected to an instance of Accumulo using the following parameters:
    Username: root
    Instance Name: miniInstance
    Zookeepers: localhost:26007

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

四、RyaClient API

4.1 获取 RyaClient

AccumuloRyaClientFactory.build(connectionDetails, connector) 基于已有 Accumulo Connector 构造客户端;AccumuloConnectionDetails 封装用户名、密码、实例名、ZooKeeper 地址:

final AccumuloConnectionDetails connectionDetails =
        new AccumuloConnectionDetails(username, password.toCharArray(), cluster.getInstanceName(), cluster.getZooKeepers());
final RyaClient ryaClient = AccumuloRyaClientFactory.build(connectionDetails, connector);

4.2 子接口速查

RyaClient 子接口关键方法作用
Installinstall(instanceName, InstallConfiguration)安装 Rya 实例(建表 + 内部元数据)
LoadStatementsloadStatements(instanceName, Iterable<Statement>)批量写入 RDF 三元组
ExecuteSparqlQueryexecuteSparqlQuery(instanceName, String sparql)执行 SPARQL 查询,返回 TupleQueryResult
CreateSparqlQuery / DeleteSparqlQuery查询创建/删除管理命名查询(fluo 场景)
GetRyaDetailsgetRyaDetails(instanceName)获取实例详情(索引配置等)

4.3 安装示例

import org.apache.rya.api.client.Install.InstallConfiguration;

// 默认配置安装(不启用附加索引)
ryaClient.getInstall().install("rya_demo", InstallConfiguration.builder().build());

// 启用全部附加索引
InstallConfiguration config = InstallConfiguration.builder()
        .setEnableTableHashPrefix(true)
        .setEnableEntityCentricIndex(true)
        .setEnableGeoIndex(true)
        .setEnableFreeTextIndex(true)
        .setEnableTemporalIndex(true)
        .setEnablePcjIndex(true)
        .setFluoPcjAppName("demoInstance_pcjUpdater")
        .build();

4.4 加载与查询示例

import org.eclipse.rdf4j.model.Statement;
import org.eclipse.rdf4j.model.ValueFactory;
import org.eclipse.rdf4j.model.impl.SimpleValueFactory;
import org.eclipse.rdf4j.query.BindingSet;
import org.eclipse.rdf4j.query.TupleQueryResult;

// 写入
final ValueFactory vf = SimpleValueFactory.getInstance();
final List<Statement> statements = new ArrayList<Statement>();
statements.add(vf.createStatement(vf.createIRI("http://Eve"), vf.createIRI("http://talksTo"), vf.createIRI("http://Bob")));
ryaClient.getLoadStatements().loadStatements("rya_demo", statements);

// 查询(返回 RDF4J TupleQueryResult,遍历 BindingSet)
final String sparql = "SELECT ?patron ?employee WHERE { ?patron <http://talksTo> ?employee. ?employee <http://worksAt> <http://CoffeeShop>. }";
final TupleQueryResult result = ryaClient.getExecuteSparqlQuery().executeSparqlQuery("rya_demo", sparql);
while (result.hasNext()) {
    final BindingSet bs = result.next();
    System.out.println("patron=" + bs.getValue("patron") + ", employee=" + bs.getValue("employee"));
}
result.close();

实测该 JOIN 查询返回 4 行:David→Alice、Eve→Bob、Eve→Charlie、George→Frank。

4.5 RyaSail(RDF4J Sail 集成)

rya.sail 提供 RyaSailFactory 创建基于 Accumulo 的 RDF4J Sail,可用 SailRepository 包装后走 RDF4J 标准 API(RepositoryConnection.add() / prepareTupleQuery())。使用前需构造 AbstractAccumuloRdfConfiguration(键位见《配置参数详解》篇 accumulo.* 系列),设置 accumulo.user/password/instance/zookeepers 与表前缀。

五、web.rya REST 端点

web.rya.war(88M)部署到 Servlet 容器后提供 REST 端点:

端点方法作用
/loadrdfPOST加载 RDF 数据(body 为 RDF 内容,Content-Type 声明格式)

部署要求:environment.properties 放入 classpath(WEB-INF/classes/),键 instance.name / instance.zk / instance.username / instance.password 指向 Accumulo;war 内默认无此文件,需自行创建后重启。

六、注意事项

⚠️ 注意:

  1. RyaShell connect-accumulo 没有 --password 选项,密码必须交互式输入;--cmdfile 脚本模式会因密码提示触发 NPE,自动化请用管道喂 stdin。
  2. RyaShell 与 RyaClient 均依赖 JDK 8 运行;JDK 11 下启动可能因字节码版本或内部 API 变化失败。
  3. load-data 未指定 --format 时会按文件扩展名推断(.nt 视为 N-Triples);扩展名不识别时显式传 --format N-Triples。
  4. RyaClient 的 executeSparqlQuery 返回的是 RDF4J TupleQueryResult,需 close() 释放;BOOLEAN/GRAPH 类查询请用对应子接口(ExecuteBooleanQuery / ExecuteGraphQuery,fluo/高级场景)。
  5. PCJ、Streams、Fluo 相关命令(create-pcj、streams-* 等)依赖额外组件(Fluo 应用、Kafka),仅安装 Rya 时不可用,会提示未配置。
  6. web.rya 是 war 形态,需 Servlet 容器(Tomcat 等)承载;本批未部署实测,相关配置见《配置参数详解》篇第五节。

七、常见问题

Q1:RyaShell 启动后 connect-accumulo 报 Command not found? 未连接状态下只有连接类命令可用;确认 connect-accumulo 三个选项(--username / --instanceName / --zookeepers)全部提供,缺任一必填选项即报命令错误。

Q2:密码输入后一直卡住或报 NPE? --cmdfile 模式下密码提示读取失败会 NPE;改用管道 printf '...\n密码\n...' | java -jar rya.shell-4.0.1-shaded.jar 方式运行。

Q3:sparql-query --file 提示查询文件无法加载? 查询文件必须存在且为合法 SPARQL;路径使用绝对路径。文件含 ASF License 头注释不影响解析。

Q4:load-data 成功但查询无结果? 数据已写入但可能带可见性标签(accumulo.visibilities)而查询授权不足;本批演示数据无标签,root 用户默认可见。检查 print-instance-details 确认实例索引状态与预期一致。

Q5:RyaClient 无法连接 Accumulo? 确认 AccumuloConnectionDetails 的 instanceName 与 ZooKeeper 地址与目标 Accumulo 一致,且用户具有 Authorizations 权限;MiniAccumuloCluster 的 ZooKeeper 端口每次启动随机,需以启动回显(MINI_ACCUMULO_READY / Mini Accumulo started)为准。