# OLAP API

> 本文档是为TuGraph的用户设计的引导程序，用户在阅读详细的文档之前，应该首先阅读该文档，对TuGraph的图计算运行流程有一个大致的了解，之后再阅读详细文档会更加方便。引导程序是基于Tugraph的一个简单的[BFS(宽度优先搜索)](https://en.wikipedia.org/wiki/Breadth-first_search "wikipedia")程序实例，我们将重点介绍其使用方式。

## 1. TuGraph 图分析引擎介绍

TuGraph的图分析引擎，面向的场景主要是全图/全量数据分析类的任务。借助TuGraph的 C++ / Python 图分析引擎 API ，用户可以对不同数据来源的图数据快速导出一个待处理的复杂子图，然后在该子图上运行诸如PageRank、LPA、WCC等迭代式图算法，最后根据运行结果做出相应的对策。

在TuGraph中，导出和计算过程均可以通过在内存中并行处理的方式进行加速，从而达到近乎实时的处理分析，和传统方法相比，即避免了数据导出落盘的开销，又能使用紧凑的图数据结构获得计算的理想性能。

TuGraph图计算系统社区版内置6个算法，商业版内置了25种算法，用户几乎不需要自己实现具体的图计算过程。其详细介绍可参考algorithms.md。

根据数据来源及实现不同，可分为Procedure、Embed和Standalone三种运行方式，均继承于OlapBase API，OlapBase API接口文档可参考olapbase-api.md。

其中Procedure和Embed的数据来源是图数据库中预加载的db数据，可以分别编译生成tugraph-web加载使用的.so文件和后台终端使用的embed文件，输入的图数据均通过db的加载形式，其接口文档可参考olapondb-api.md。
Standalone用于编译生成standalone文件，区别于前者，该文件的输入图数据通过txt、二进制、ODPS文件的形式加载，其接口文档可参考olapondisk-api.md。

## 2. Procedure 编译与运行

该种方式主要用于tugraph-web界面进行可视化加载及运行。使用方法如下：

### C++:
在tugraph-db/procedures 目录下执行`bash make_so_cpp.sh bfs`即可在tugraph-db/procedures目录下得到bfs.so文件，将该文件以插件形式上传至tugraph-web，输入参数后即可执行。

### Python:
在tugraph-web的前端将python文件以插件形式上传，输入参数后即可执行。

示例：
在tugraph-db/procedures 编译.so算法文件
`bash make_so_cpp.sh bfs`

将bfs.so（或tugraph-db/procedures/algo_cython/bfs.py）文件以插件形式加载至tugraph-web后，输入如下json参数：

```json
{
    "root":"10",
    "label":"user",
    "field":"id"
}
```
即可得到返回结果如下。

```json
{
  "core_cost": 0.013641119003295898,
  "found_vertices": 3829,
  "num_edges": 88234,
  "num_vertices": 4039,
  "output_cost": 8.821487426757813e-06,
  "prepare_cost": 0.03479194641113281,
  "total_cost": 0.04844188690185547
}
```

输出内容解释如下：
- core_cost: 表示算法运行所需要的时间。
- found_vertices: 表示查找到点的个数。
- num_edges: 表示该图数据的边数量。
- num_vertices: 表示该图数据点的数量。
- output_cost: 表示算法结果写回db所需要的时间。
- prepare_cost: 表示预处理阶段所需要的时间。预处理阶段的工作：加载参数、图数据加载、索引初始化等。
- total_cost: 表示执行该算法整体运行时间。

make_so.sh文件介绍：该文件用于将TuGraph-OLAP所涉及到的图算法文件编译成一个可供tugraph-web使用的.so文件。

## 3. Embed 编译与运行

该种方式主要用于TuGraph在后台程序中对预加载的db图数据进行算法分析。其使用方法如下：
在tugraph-db/procedures 目录下对embed_main.cpp文件完善，补充数据名称、输入参数、数据路径等信息，示例如下：

### C++:

```C++
#include <iostream>
#include "lgraph/lgraph.h"
#include "lgraph/olap_base.h"
using namespace std;

extern "C" bool Process(lgraph_api::GraphDB &db, const std::string &request, std::string &response);

int main(int argc, char **argv) {
    // db_path表示预加载图数据存放的路径
    std::string db_path = "../fb_db/";
    if (argc > 1)
        db_path = argv[1];
    lgraph_api::Galaxy g(db_path);
    g.SetCurrentUser("admin", "73@TuGraph");
    // 指定图数据的名称
    lgraph_api::GraphDB db = g.OpenGraph("fb_db");
    std::string resp;
    // 以json形式输入算法参数
    bool r = Process(db, "{\"root_id\":\"0\", \"label\":\"node\",\"field\":\"id\"}", resp);
    cout << r << endl;
    cout << resp << endl;
    return 0;
}
```
保存后在tugraph-db/procedures 目录下执行`bash make_embed.sh bfs`即可在tugraph-db/procedures/algo_cpp 目录下得到bfs_procedure文件。

在tugraph-db/procedures 文件夹下执行`./algo_cpp/bfs_procedure` 即可得到返回结果：

```json
{
  "core_cost":0.025603055953979492,
  "found_vertices":3829,
  "num_edges":88234,
  "num_vertices":4039,
  "output_cost":9.059906005859375e-06,
  "prepare_cost":0.056738853454589844,
  "total_cost":0.0823509693145752
}
```

参数解释同上。

### Python：
在tugraph-db/procedures文件夹下执行
`bash make_so_cython.sh bfs`
或在tugraph-db/procedures/algo_cython文件夹下执行
`python3 setup.py build_ext -i`
得到bfs.so后，在Python中import bfs可使用，如tugraph-db/procedures/run_embed.py所示

```python
# tugraph-db/procedures/run_embed.py
from lgraph_db_python import *

import bfs as python_plugin

if __name__ == "__main__":
    galaxy = PyGalaxy("../build/output/lgraph_db")
    galaxy.SetCurrentUser("admin", "73@TuGraph")
    db = galaxy.OpenGraph("default", False)
    res = python_plugin.Process(db, "{\"root_id\":\"0\", \"label\":\"node\",\"field\":\"id\"}".encode('utf-8'))
    print(res)
    del db
    del galaxy
```
通过如下命令执行

```bash
python3 run_embed.py
```

输出结果与C++相同。

## 4. Standalone 编译与运行

该文件主要用于在终端处直接加载图数据，并运行打印输出结果。使用方法如下：
在tugraph-db/build目录下执行`make bfs_standalone` (需要在g++默认include路径中包含boost/sort/sort.hpp)即可得到bfs_standalone文件,该文件生成于tugraph-db/build/output/algo文件夹下。
运行方式：在tugraph-db/build目录下执行`./output/algo/bfs_standalone -–type [type] –-input_dir [input_dir] --id_mapping [id_mapping] -–vertices [vertices] --root [root] –-output_dir [output_dir]`即可运行。

- `[type]`：表示输入图文件的类型来源，包含text文本文件、BINARY_FILE二进制文件和ODPS源。
- `[input_dir]`：表示输入图文件的文件夹路径，文件夹下可包含一个或多个输入文件。TuGraph在读取输入文件时会读取[input_dir]下的所有文件，要求[input_dir]下只能包含输入文件，不能包含其它文件。参数不可省略。
- `[id_mapping]`：当读入边表时，是否对输入数据做id映射，使达到符合算法运行的形式。1为需要做id映射，0为不需要做。该过程会消耗一定时间。参数可省略，默认值为0。
- `[vertices]`：表示图的点个数，为0时表示用户希望系统自动识别点数量；为非零值时表示用户希望自定义点个数，要求用户自定义点个数需大于最大的点ID。参数可省略，默认值为0。
- `[root]`：表示进行bfs的起始点id。参数不可省略。
- `[output_dir]`：表示输出数据保存的文件夹路径，将输出内容保存至该文件中，参数不可省略。

示例：

### C++:
在tugraph-db/build编译standalone算法程序

```bash
make bfs_standalone
```

在tugraph-db/build/output目录下运行text源文件

```bash
./output/algo/bfs_standalone --type text --input_dir ../test/integration/data/algo/fb_unweighted --root 0
```

得到运行结果：

```text
prepare_cost = 0.10(s)
core_cost = 0.02(s)
found_vertices = 3829
output_cost = 0.00(s)
total_cost = 0.11(s)
DONE.
```

结果参数解释同上。

对于新的算法，运行时不了解该算法的所需参数时，可通过`./output/algo/bfs_standalone -h`进行查阅对应参数。

### Python:
Python语言的bfs拓展编译过程与embed模式无区别，在运行时通过`Standalone`接口调用，示例如下：
```python
# tugraph-db/procedures/run_standalone.py
import bfs as python_plugin

if __name__ == "__main__":
    python_plugin.Standalone(input_dir=
                             "../test/integration/data/algo/fb_unweighted",
                             root=0)
```

通过如下命令执行

```bash
python3 run_standalone.py
```

至此，通过TuGraph对上图进行bfs运算的过程已经完成。