北京大学王选所数据管理实验室

使用手册

如何使用

gStore 的所有指令都应该在 gStore 根目录下使用，例如 bin/ghttp 。因为所有的可执行程序都在 bin/ 中，它们可能使用了一些文件，其路径在代码中声明，但不是绝对路径。我们之后会让使用者给出他们系统中安装/配置 gStore 的绝对路径，以确保所有的路径都是绝对的。然而，现在你必须这么做以避免错误。

0. 数据格式

RDF 数据应该以 N-Triple 格式给出（目前不支持 XML ），查询必须符合 SPARQL 1.1 语法。并非所有 SPARQL 1.1 中的语法都可以在 gStore 中解析，例如， gStore 不支持实体属性查询，数据和查询的实体、字面量或谓词中不允许出现制表符、 ’<’ 和’>’ 。

1. gbuild

gbuild 用于由 RDF 三元格式文件 build 一个新的数据库。

bin/gbuild db_name rdf_triple_file_path

在上述命令的参数中，db_name 是你设置的数据库名称，rdf_triple_fle_path 是数据文件所在的路径。例如，我们从 data/lubm 文件夹下的 lumb.nt 文件 build 数据库。

[bookug@localhost gStore]$ bin/gbuild lumb ./data/lubm/lubm.nt
gbuild...
argc: 3 DB_store:lubm RDF_data: ./lubm.nt
begin encode RDF from : ./data/lubm/lubm.nt ...

2. gquery

gquery 用包含 SPARQL 的文件查询一个已有的数据库（每个文件包含一条 SPARQL 查询）。

输入 bin/gquery db_name query_file 在名为 db_name 的数据库中用 query_fle 中的语句执行 SPARQL 查询。

使用 bin/gquery --help 获取关于 gquery 用法的详细信息。

输入 bin/gquery db_name 进入 gquery 控制台。程序会给出一个命令提示符（“ gsql>”），你可以在此处输入命令。使用 help 查看所有指令的基本信息，help command_t 给出特定指令的详细信息。
输入 quit 离开 gquery 控制台。

对于 sparql 指令，输入包含单个 SPARQL 查询的文件路径。 (支持将结果重新定向到文件。 )

程序完成查询时，会再次显示命令提示符。

我们还是以 lubm.nt 为例。

[bookug@localhost gStore]$ bin/gquery lubm
gquery...
argc: 2 DB_store:lubm/
loadTree...
LRUCache initial...
LRUCache initial finish
finish loadCache
finish loadEntityID2FileLineMap
open KVstore
finish load
finish loading
Type `help` for information of all commands
Type `help command_t` for detail of command_t
gsql>sparql ./data/lubm/lubm_q0.sql
... ...
Total time used: 4ms.
final result is :
<http://www.Department0.University0.edu/FullProfessor0>
<http://www.Department1.University0.edu/FullProfessor0>
<http://www.Department2.University0.edu/FullProfessor0>
<http://www.Department3.University0.edu/FullProfessor0>
<http://www.Department4.University0.edu/FullProfessor0>
<http://www.Department5.University0.edu/FullProfessor0>
<http://www.Department6.University0.edu/FullProfessor0>
<http://www.Department7.University0.edu/FullProfessor0>
<http://www.Department8.University0.edu/FullProfessor0>
<http://www.Department9.University0.edu/FullProfessor0>
<http://www.Department10.University0.edu/FullProfessor0>
<http://www.Department11.University0.edu/FullProfessor0>
<http://www.Department12.University0.edu/FullProfessor0>
<http://www.Department13.University0.edu/FullProfessor0>
<http://www.Department14.University0.edu/FullProfessor0>

注意：

• 如果没有答案，会输出 “[empty result]” ，在所有结果后面会有一个空行。

• 我们使用了 readline 库，你可以用键盘上的方向键查看历史指令、移动或修改整个命令。

• 支持路径补全（不是内嵌命令补全）。

3. ghttp

ghttp 以类似 HTTP 服务器的方式运行 gStore （你需要指定一个端口，并在你的环境中打开这个端口，建议使用 iptables 工具）。从浏览器访问特定的 url ， gStore 就能执行相应的操作。

输入 bin/ghttp db_name serverPort 或者 bin/ghttp serverPort db_name 在 serverPort 端口上启动服务，并 load 名为 db_name 的数据库。

注意：参数 serverPort 或 db_name 可以省略。如果省略了 serverPort，其值会被默认设置为 9000 。如果省略了 db_name，服务会以没有 load 数据库的形式启动。

操作

build, load, unload, query, monitor, show, checkpoint, checkall, user, drop

// build a new database by a RDF file.
gc.build("test", "data/lubm/lubm.nt", "root", "123456");
// drop a database already built but leave a backup.
gc.drop("test", "root", "123456");
// drop a database already built completely.
gc.drop_r("test", "root", "123456");
// load database
gc.load("test", "root", "123456");
// then you can execute SPARQL query on this database.
answer = gc.query("root", "123456", "test", sparql);
// output information of a database
cout << answer << std::endl;
// unload this database
gc.unload("lubm", "root", "123456");
// show all databases already built and if they are loaded
gc.show();
// show statistical information of a loaded database
gc.monitor("lubm");
//add a user(with username: Jack, password: 2)
answer = gc.user("add_user", "root", "123456", "Jack", "2");
//add privilege to user Jack(add_query, add_load, add_unload)
answer = gc.user("add_query", "root", "123456", "Jack", "lubm");
//delete privilege of a user Jack(delete_query, delete_load, delete_unload)
answer = gc.user("delete_query", "root", "123456", "Jack", "lubm");
//delete user(with username: Jack, password: 2)
answer = gc.user("delete_user", "root", "123456", "Jack", "2");

参数

db_name ：数据库名称，例如 lubm
format ： html, json, txt, csv
sparql ： select ?s where ?s ?p ?o .
ds_path in the server ：例如 /home/data/test.n3
operation ：操作类型，例如 load, unload, query ...
type: 针对 user 的操作类型，例如 add_user, delete_user, add_query, add_load...
username ：执行操作的用户名
password ：执行操作的用户密码

为了统一响应格式，同时让用户更有效地处理响应信息，我们把 ghttp.cpp 中的响应格式都改成了 JSON 。

用户发送的请求会收到 JSON 格式的响应，包括 StatusCode （一个代表响应状态的数字）， StatusMsg （一个描述服务器信息的字符串）和 ResponseBody（响应的主体部分，如果是一个 query 请求，主体部分就是查询结果，有时主体部分可以为空）。

我们定义了一些 StatusCode 和对应的信息。用户向 ghttp 发送请求后，他可以解析服务器返回的 JSON 获取 StatusCode ， StatusMsg 和 ResponseBody ，然后根据需求利用这些信息。

ghttp 支持并发只读查询，但当查询中包含更新操作时，整个数据库将被上锁。虽然我们在实验中可以运行 13000 个并发查询，但是在几十个内核线程的机器上，我们还是建议并发数低于 300 。想要使用 gStore 的并发特性，最好将系统设置中的’open fles’ 和’maximum processes’ 设置为 65535 或更大值。 setup 文件夹下有三个脚本，可以用来在不同的 Linux 发行版本中修改设置。

如果通过 ghttp 发送了包含更新操作的查询，在关闭数据库服务器前，必须在 ghttp 控制台中输入并完成 checkpoint 命令。否则，更新可能不能同步到磁盘，会在 ghttp 服务器关闭时丢失。

注意：你无法通过 Ctrl+C 停止 ghttp ，这会导致数据库的变更丢失。要停止服务，请输入 bin/shutdown serverPort 。

4. gserver

这一功能暂时停止维护。

gserver 是一个后台程序。在使用 gclient 或 socket API 连接 gStore 之前，应该启动 gserver 。它通过套接字与客户端通信。

[bookug@localhost gStore]$ bin/gserver -s
Server started at port 3305
[bookug@localhost gStore]$ bin/gserver -t
Server stopped at port 3305
你也可以为监听分配一个指定端口。
[bookug@localhost gStore]$ bin/gserver -s -p 3307
Server started at port 3307.

注意： gserver 不支持多线程。如果你同时在多个终端启动 gclient ， gserver 会崩溃。

5. gclient

这一功能暂时停止维护。

gclient 是用于发送命令和接收反馈的客户端。

[bookug@localhost gStore]$ bin/gclient
ip=127.0.0.1 port=3305
gsql>
gsql>quit

你也可以分配 gserver 的 ip 和端口。

[bookug@localhost gStore]$ bin/gclient 172.31.19.15 3307
ip=172.31.19.15 port=3307
gsql>

我们现在可以使用以下命令：

• help 显示所有指令的信息
• import db_name rdf_triple_file_name 从一个 RDF 三元组文件 build 数据库
• load db_name load 一个已存在的数据库
• unload db_name unload 一个数据库，但不会从磁盘上删除它，你可以再次 load
• sparql "query_string" 用一个 SPARQL 查询字符串（在 “” 内）查询当前数据库
• show 显示当前数据库的名称

注意：

• 在 gclient 控制台最多只能载入一个数据库
• 你可以在指令的不同部分之间加上 ‘ ’ 或 ‘\t’ ，但不要使用 ‘;’ 之类的字符
• 在指令前不能有空格或制表符

6. gconsole

gconsole 是 gStore 的主要控制台，与其他函数和一些系统指令整合对 gStore 进行操作。提供了完整的命令名称、命令行编辑特征、可以获取历史命令。尝试 gconsole 将是一次奇妙之旅！（空格或制表符可以在开头或结尾使用，不需要输入任何特殊字符作为分隔符）

在 gStore 根目录下输入 bin/gconsole 来使用控制台，你会看到 gstore> 提示符，意味着你处于本机模式并可以输入本机命令。控制台还有另一种模式，称为远程模式。在本机模式下输入 connect 进入远程模式，输入 disconnect 退回到本机模式。（控制台连接到 gStore 服务器，其 ip 为 ‘127.0.0.1’，端口号为3305 ，你可以输入 connect gStore_server_ip gStore_server_port 来指定它们。）

你可以在本机模式或远程模式中用 help 或 ? 查看帮助信息，你也可以输入 help command_name 或 ? command_name 查看某一指令的信息。请注意，本机模式和远程模式的指令有一些区别。例如， ls ， cd 和 pwd 这样的系统指令在本机模式中提供，但不在远程模式中提供。也请注意，帮助页中的一些指令还没有完全实现，将来我们可能会改变控制台的一些函数。

我们已经完成的工作足以让你便捷地使用 gStore ，尽情享受吧！

7. gadd

gadd 向数据库中插入一个文件中的三元组。

用法： bin/gadd db_name rdf_triple_file_path

[bookug@localhost gStore]$ bin/gadd lubm ./data/lubm/lubm.nt
...
argc: 3 DB_store:lubm insert file:./data/lubm/lubm.nt
get important pre ID
...
insert rdf triples done.
inserted triples num: 99550

8. gsub

gsub 从数据库中删除某一文件中的三元组。
用法： bin/gsub db_name rdf_triple_file_path

[bookug@localhost gStore]$ bin/gsub lubm ./data/lubm/lubm.nt
...
argc: 3 DB_store:lubm remove file: ./data/lubm/lubm.nt
...
remove rdf triples done.
removed triples num: 99550

9. gmonitor

启动 ghttp 后，输入 bin/gmonitor ip port 查看服务器信息。

[bookug@localhost bin]$ ./gmonitor 127.0.0.1 9000
parameter: ?operation=monitor
request: http://127.0.0.1:9000/?operation=monitor
null--->[HTTP/1.1 200 OK]
Content-Length--->[127]
database: lubm
triple num: 99550
entity num: 28413
literal num: 0
subject num: 14569
predicate num: 17
connection num: 7

10. gshow

启动 ghttp 后，输入 bin/gshow ip port 查看当前加载的数据库。

[bookug@localhost gStore]$ bin/gshow 127.0.0.1 9000
parameter: ?operation=show
request: http://127.0.0.1:9000/?operation=show
null--->[HTTP/1.1 200 OK]
Content-Length--->[4]
lubm

11. shutdown

启动 ghttp 之后，你可以输入 bin/shutdown port 来停止服务。

12. ginit

如果想要恢复 ghttp 服务器的初始配置，输入 bin/ginit 来重建 system.db 。

13. 测试工具

test/ 文件夹下有一系列测试程序，我们会介绍两个比较有用的：gtest.cpp 和 full_test.sh 。

gtest 用多个数据集和查询测试 gStore 。

要使用 gtest ，请先输入 make gtest 编译 gtest 程序。 gtest 程序为数据集生产结构日志。请在工作目录下输入 ./gtest --help 获取更多信息。

如果需要请改变 test/gtest.cpp 中的路径。你应该如下设置数据集和查询：

DIR/WatDiv/database/*.nt
DIR/WatDiv/query/*.sql

请注意， DIR 是你要用于 gtest 的所有数据集的根目录， WatDiv 和 lubm 一样，是数据集类。在 WatDiv 内，请将所有的数据集（用.nt 命名）放在 database/ 文件夹下，并将所有查询（和数据集对应，用.sql 命名）放在 query 文件夹下。之后你可以用指定的参数运行 gtest 程序，输出会被分类并储存到 gStore 根目录下的三个日志内： load.log/ （数据库加载时间和大小）， time.log/ （查询时间）和 result.log/ （所有查询结果，不是整个结束字符串，而是记录选定的两个数据库系统是否匹配的信息。）

程序产生的所有日志都以 TSV 格式储存（用 ‘\t’ 分隔），你可以直接将它们加载入 Calc/Excel/Gnumeric 。请注意，时间单位是 ms ，空间单位是 kb 。

full_test.sh 用多个数据集和查询比较 gStore 和其他数据库系统的性能。

要使用 full_test.sh ，请下载你想要比较的数据库系统，并在这一脚本中准确设置数据库系统和数据集的位置。命名策略和日志策略应该与 gtest 的要求一致。

在这一脚本中仅测试比较了 gStore 和 Jena ，如果你愿意花时间阅读这一脚本，很容易添加其他数据库系统