Skip to content

Commit

Permalink
Merge 2.5.0 to book (#931)
Browse files Browse the repository at this point in the history 
* Update 4.storage-service.md

* Update source_install-nebula-graph-by-rpm-or-deb.md

* Update st-ug-crud-tag.md

* fix faq

* Update 3.graph-config.md

* Update 3.graph-config.md

* Update 3.deploy-listener.md

* fix

* Update st-ug-import-data.md

* math

* Update 1.configurations.md

* Update source_install-nebula-graph-by-rpm-or-deb.md

* Update 1.configurations.md

* Update source_connect-to-nebula-graph.md

* Update source_install-nebula-graph-by-rpm-or-deb.md

* Update source_manage-service.md

* Update source_install-nebula-graph-by-rpm-or-deb.md

* Update 3.vid.md

Co-authored-by: foesa <[email protected]>
Co-authored-by: min.wu <[email protected]>
Co-authored-by: abby.huang <[email protected]>
Co-authored-by: [email protected] <[email protected]>
  • Loading branch information
@cooper-lzy @foesa-yang
@whitewum @abby-cyber @izhuxiaoqing
5 people authored Sep 6, 2021
1 parent 4571d57 commit 10fd5fd
Show file tree
Hide file tree
Showing 20 changed files with 495 additions and 457 deletions.
8 changes: 6 additions & 2 deletions .github/workflows/deploy.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ on:

jobs:
deploy:
runs-on: ubuntu-20.04
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v2
with:
Expand Down Expand Up @@ -64,4 +64,8 @@ jobs:
script: |
mkdir -p /usr/web/nebula-docs/
tar -xzf /usr/web/book.tar.gz -C /usr/web/nebula-docs/
# - name: Deploy
# uses: peaceiris/actions-gh-pages@v3
# with:
# github_token: ${{ secrets.DEPLOY_TOKEN }}
# publish_dir: ./site
460 changes: 230 additions & 230 deletions docs-2.0/0.foreground/0-graph.md
View file

Large diffs are not rendered by default.

5 changes: 1 addition & 4 deletions docs-2.0/0.foreground/1-graph-database.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ https://www.marketsandmarkets.com/Market-Reports/graph-database-market-126230231
熟悉数据库的读者可能都知道结构化查询语言SQL。通过使用SQL，人们以接近自然语言的方式访问数据库。在 SQL 被广泛采用和标准化之前，关系型数据库的市场是非常碎片和割裂的——各家厂商的产品都有完全不同的接入访问方式，数据库产品自身的开发人员、数据库产品周边工具的开发人员、数据库最终的使用人员，都不得不学习各个厂商的完全不同的产品，在不同产品之间迁移极其困难。当1989年SQL-89标准被制定后，整个关系型数据库的市场快速收敛到SQL-89上。这大大降低了上述各种人员的学习曲线。

类似的，在图数据库领域，图语言(GQL)承担了类似于SQL的作用，是一种用户与图数据库主要的交互方式。但不同于SQL-89这种国际标准，GQL还没有任何国际标准。目前有两种主流的图语言：

Neo4j的Cypher (及其后续——ISO正在制定过程中的 GQL-standard 草案)和Apache TinkerPop的Gremlin。前者通常被称为声明式语言(Declarative query language)——也即用户只需要告诉系统“要什么”，而不管“怎么做”；后者通常被称为命令式语言(Imperative query language)，用户会显式地指定系统的操作。

GQL国际标准正在制定过程中。
Expand Down Expand Up @@ -176,8 +177,6 @@ Cypher 启发了一系列后续的图查询语言，包括

[^fosdem20]: https://neo4j.com/fosdem20/



其语法风格大体是
```Cypher
USE graphA # S1.1 从 Shard A 读
Expand Down Expand Up @@ -244,5 +243,3 @@ Oracle graph[^Oracle] 是关系型数据库巨头 Oracle 在图技术与图数
#### 新一代开源分布式图数据库 Nebula Graph

在下一章，我们将正式介绍新一代开源分布式图数据库 Nebula Graph。


3 changes: 1 addition & 2 deletions docs-2.0/1.introduction/3.vid.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,6 @@ VID的数据类型必须在[创建图空间](../3.ngql-guide/9.space-statements/
2. 例如, `LOOKUP ON player WHERE player.name == "Tony Parker"` 或者 `MATCH (v:player {name:"Tony Parker"}) `，是通过属性 `player.name` 的索引来定位到 `start vid`；


!!! caution "不能在没有 `start vid` 情况下进行全局扫描"
!!! caution 不能在没有 `start vid` 情况下进行全局扫描；

例如 `match (n) return n;` 会返回错误，因为此时无法定位到 `start vid`；这是一个全局扫描，因此被禁止。

127 changes: 68 additions & 59 deletions docs-2.0/20.appendix/0.FAQ.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,25 +32,41 @@ Nebula Graph一直在持续开发，功能或操作的行为可能会有变化

## 关于执行

### 使用GO和MATCH执行相同语义的查询，查询结果为什么不同？
### 关于悬挂边

路径的类型不同，导致查询结果可能会不同。
悬挂边 (Dangling edge) 是指一条边的起点或者终点在数据库中不存在。

- `GO`语句采用的是`walk`类型，遍历时点和边可以重复。
Nebula Graph {{ nebula.release }} 的数据模型中，允许存在"悬挂边"；也没有 openCypher 中的 MERGE 语句。对于悬挂边的保证完全依赖应用层面。详见[INSERT VERTEX](../3.ngql-guide/12.vertex-statements/1.insert-vertex.md), [DELETE VERTEX](../3.ngql-guide/12.vertex-statements/4.delete-vertex.md), [INSERT EDGE](../3.ngql-guide/13.edge-statements/1.insert-edge.md), [DELETE EDGE](../3.ngql-guide/13.edge-statements/4.delete-edge.md)。

- `MATCH`语句兼容openCypher，采用的是`trail`类型，遍历时只有点可以重复，边不可以重复。

例如下图。

![路径示例](../images/path1.png)
### 如何处理错误信息 `[ERROR (-1005)]: Used memory hits the high watermark(0.800000) of total system memory.`

从点A开始查询距离5跳的点，都会查询到点C（`A->B->C->D->E->C`），查询6跳的点时，`GO`语句会查询到点D（`A->B->C->D->E->C->D`），因为边`C->D`可以重复查询，而`MATCH`语句查询为空，因为边不可以重复。
报错原因：Nebula Graph的`system_memory_high_watermark_ratio`参数指定了内存高水位报警机制的触发阈值，默认为`0.8`。系统内存占用率高于该值会触发报警机制，Nebula Graph会停止接受查询。

所以使用`GO`和`MATCH`执行相同语义的查询，可能会出现`MATCH`语句的查询结果比`GO`语句少。
解决方案：

关于路径的详细说明，请参见[维基百科](https://en.wikipedia.org/wiki/Path_(graph_theory)#Walk,_trail,_path)。
* 清理系统内存，使其降低到阈值以下。
* [修改Graph配置](../5.configurations-and-logs/1.configurations/1.configurations.md)。在所有Graph服务器的配置文件中增加`system_memory_high_watermark_ratio`参数，为其设置一个大于`0.8`的值，例如`0.9`。

### 返回消息中`time spent`的含义是什么？
!!! note

仅Graph服务支持`system_memory_high_watermark_ratio`，Storage和Meta服务不支持该参数。

### 如何处理错误信息 `Storage Error E_RPC_FAILURE`

报错原因通常为Graph服务向Storage服务请求了过多的数据，导致Storage服务超时。请尝试以下解决方案：

* [修改配置文件](../5.configurations-and-logs/1.configurations/3.graph-config.md): 在`nebula-graphd.conf`文件中修改`--storage_client_timeout_ms`参数的值，以增加Storage client的连接超时时间。该值的单位为毫秒（ms）。例如，设置`--storage_client_timeout_ms=60000`。如果`nebula-graphd.conf`文件中未配置该参数，请手动增加。提示：请在配置文件开头添加--local_config=true再重启服务。
* 优化查询语句：减少全库扫描型的查询，无论是否用`LIMIT`限制了返回结果的数量；用 GO 语句改写 MATCH 语句（前者有优化，后者无优化）。
* 检查Storaged是否发生的 OOM。(`dmesg |grep nebula`)。
* 为 Storage 服务器提供性能更好的SSD或者内存。
* 重试请求。

### 如何处理错误信息 `The leader has changed. Try again later`

已知问题，通常需要重试 1-N 次(N==partition数量)。原因为 meta client 更新leader缓存需要1-2个心跳或者通过错误触发强制更新。

### 返回消息中 `time spent` 的含义是什么？

将命令`SHOW SPACES`返回的消息作为示例：

Expand All @@ -72,14 +88,38 @@ Got 1 rows (time spent 1235/1934 us)

不要这样设置。

Storage服务使用Raft协议（多数表决），为保证可用性，要求出故障的副本数量不能达到一半。
Storage 服务使用 Raft 协议（多数表决），为保证可用性，要求出故障的副本数量不能达到一半。

当机器数量为1时，`replica_factor`只能设置为`1`。

当机器数量足够时，如果`replica_factor=2`，当其中一个副本故障时，就会导致系统无法正常工作；如果`replica_factor=4`，只能有一个副本可以出现故障，这和`replica_factor=3`是一样。以此类推，所以`replica_factor`设置为奇数即可。

建议在生产环境中设置`replica_factor=3`，测试环境中设置`replica_factor=1`，不要使用偶数。

### 是否支持停止或者中断慢查询

支持。

详情请参见[终止查询](../3.ngql-guide/18.operation-and-maintenance-statements/6.kill-query.md)。

### 使用`GO`和`MATCH`执行相同语义的查询，查询结果为什么不同？

路径的类型不同，导致查询结果可能会不同。

- `GO`语句采用的是`walk`类型，遍历时点和边可以重复。

- `MATCH`语句兼容openCypher，采用的是`trail`类型，遍历时只有点可以重复，边不可以重复。

例如下图。

![路径示例](../images/path1.png)

从点A开始查询距离5跳的点，都会查询到点C（`A->B->C->D->E->C`），查询6跳的点时，`GO`语句会查询到点D（`A->B->C->D->E->C->D`），因为边`C->D`可以重复查询，而`MATCH`语句查询为空，因为边不可以重复。

所以使用`GO`和`MATCH`执行相同语义的查询，可能会出现`MATCH`语句的查询结果比`GO`语句少。

关于路径的详细说明，请参见[维基百科](https://en.wikipedia.org/wiki/Path_(graph_theory)#Walk,_trail,_path)。

### 如何处理错误信息`[ERROR (-7)]: SyntaxError: syntax error near`？

大部分情况下，查询语句需要有`YIELD`或`RETURN`，请检查查询语句是否包含。
Expand Down Expand Up @@ -134,57 +174,41 @@ Storage服务使用Raft协议（多数表决），为保证可用性，要求出
检查输入的 vid 是否是 create space 设置的整型或者 `fix_string(N)`. 如果是字符串类型，检查长度是否超过`N` (默认为 `8`).
见[create space](../3.ngql-guide/9.space-statements/1.create-space.md).

### 如何处理错误信息`edge conflict`或`vertex conflict`
### 如何处理错误信息 `edge conflict` 或 `vertex conflict`

Storage服务在毫秒级时间内多次收到插入或者更新同一点或边的请求时，可能返回该错误。请稍后重试。

### 如何处理错误信息`Storage Error E_RPC_FAILURE`

报错原因通常为Graph服务向Storage服务请求了过多的数据，导致Storage服务超时。请尝试以下解决方案：

* [修改配置文件](../5.configurations-and-logs/1.configurations/3.graph-config.md): 在`nebula-graphd.conf`文件中修改`--storage_client_timeout_ms`参数的值，以增加Storage client的连接超时时间。该值的单位为毫秒（ms）。例如，设置`--storage_client_timeout_ms=60000`。如果`nebula-graphd.conf`文件中未配置该参数，请手动增加。
<!--提示：请在配置文件开头添加--local_config=true再重启服务。-->
* 优化查询语句：减少全库扫描型的查询，无论是否用`LIMIT`限制了返回结果的数量；用 GO 语句改写 MATCH 语句（前者有优化，后者无优化）。
* 检查Storaged是否发生的 OOM。(`dmesg |grep nebula`)。
* 为 Storage 服务器提供性能更好的SSD或者内存。
* 重试请求。

### 如何处理错误信息`The leader has changed. Try again later`

已知问题，通常需要重试1-N次(N==partition数量)。原因为 meta client 更新leader缓存需要1-2个心跳或者通过错误触发强制更新。

### 如何处理错误信息`RPC failure in MetaClient: Connection refused`
### 如何处理错误信息 `RPC failure in MetaClient: Connection refused`

报错原因通常为metad服务状态异常，或是metad和graphd服务所在机器网络不通。请尝试以下解决方案：

- 在metad所在服务器查看下metad服务状态，如果服务状态异常，可以重新启动metad服务。
- 在metad所在服务器查看下 metad 服务状态，如果服务状态异常，可以重新启动metad服务。

- 在报错服务器下使用`telnet meta-ip:port`查看网络状态。

- 检查配置文件中的端口配置，如果端口号与连接时使用的不同，改用配置文件中的端口或者修改配置。

### 如何处理`nebula-graph.INFO`错误日志`StorageClientBase.inl:214] Request to "x.x.x.x":9779 failed: N6apache6thrift9transport19TTransportExceptionE: Timed Out`
### 如何处理 `nebula-graph.INFO` 中错误日志 `StorageClientBase.inl:214] Request to "x.x.x.x":9779 failed: N6apache6thrift9transport19TTransportExceptionE: Timed Out`

报错原因可能是查询的数据量比较大，storaged 处理超时。请尝试以下解决方法：

- 导入数据时，手动[compaction](../8.service-tuning/compaction.md)，加速读的速度。

- 增加Graph服务与Storage服务的RPC连接超时时间，在`nebula-storaged.conf`文件里面修改`--storage_client_timeout_ms`参数的值。该值的单位为毫秒（ms），默认值为60000毫秒。

<!--提示：请在配置文件开头添加--local_config=true再重启服务。-->

### 如何处理`nebula-storaged.INFO`错误日志`MetaClient.cpp:65] Heartbeat failed, status:Wrong cluster!`或者 `nebula-metad.INFO`含有错误日志`HBProcessor.cpp:54] Reject wrong cluster host "x.x.x.x":9771!`
### 如何处理 `nebula-storaged.INFO` 中错误日志 `MetaClient.cpp:65] Heartbeat failed, status:Wrong cluster!` 或者 `nebula-metad.INFO` 含有错误日志`HBProcessor.cpp:54] Reject wrong cluster host "x.x.x.x":9771!`

报错的原因可能是用户修改了 metad 的 ip 或者端口信息，或者 storage 之前加入过其他集群。请尝试以下解决方法：

用户到storage部署的机器所在的安装目录（默认安装目录为 `/usr/local/nebula`）下面将`cluster.id`文件删除，然后重启 storaged 服务。

### 是否支持停止或者中断慢查询

支持。详情请参见[终止查询](../3.ngql-guide/18.operation-and-maintenance-statements/6.kill-query.md)。

### 能不能用中文字符做标识符，比如图空间、Tag、Edge type、属性、索引的名称？

不能。图空间、Tag、Edge type、属性以及索引的名称都需由大小写英文字母、数字或下划线组成，暂不支持使用中文字符。
不能。

图空间、Tag、Edge type、属性以及索引的名称都需由大小写英文字母、数字或下划线组成，暂不支持使用中文字符。

同时，上述标识符区分大小写，且不可使用[关键字和保留字](../3.ngql-guide/1.nGQL-overview/keywords-and-reserved-words.md) 。

Expand All @@ -197,22 +221,11 @@ nebula > MATCH (s)-[e]->() WHERE id(s) == "given" RETURN count(e); #出度
nebula > MATCH (s)<-[e]-() WHERE id(s) == "given" RETURN count(e); #入度
```

### 是否有办法快速获取所有点的出度和入度？
### 是否有办法快速获取“所有”点的出度和入度？

没有直接命令。可以使用 [Nebula Algorithm](../nebula-algorithm.md)。
没有直接命令。

### 如何处理错误信息`[ERROR (-1005)]: Used memory hits the high watermark(0.800000) of total system memory.`

报错原因：Nebula Graph的`system_memory_high_watermark_ratio`参数指定了内存高水位报警机制的触发阈值，默认为`0.8`。系统内存占用率高于该值会触发报警机制，Nebula Graph会停止接受查询。

解决方案：

* 清理系统内存，使其降低到阈值以下。
* [修改Graph配置](../5.configurations-and-logs/1.configurations/1.configurations.md)。在所有Graph服务器的配置文件中增加`system_memory_high_watermark_ratio`参数，为其设置一个大于`0.8`的值，例如`0.9`。

!!! note

仅Graph服务支持`system_memory_high_watermark_ratio`，Storage和Meta服务不支持该参数。
可以使用 [Nebula Algorithm](../nebula-algorithm.md)。

### [ERROR (-1005)]: Schema not exist: xxx

Expand All @@ -222,12 +235,6 @@ nebula > MATCH (s)<-[e]-() WHERE id(s) == "given" RETURN count(e); #入度

- Tag或Edge type的名称是否为关键字，如果是关键字，请使用反引号（\`）将它们括起来。详情请参见[关键字](../3.ngql-guide/1.nGQL-overview/keywords-and-reserved-words.md)。

### 关于悬挂边

悬挂边 (Dangling edge) 是指一条边的起点或者终点在数据库中不存在。

Nebula Graph {{ nebula.release }} 的数据模型中，允许存在"悬挂边"；也没有 openCypher 中的 MERGE 语句。对于悬挂边的保证完全依赖应用层面。详见[INSERT VERTEX](../3.ngql-guide/12.vertex-statements/1.insert-vertex.md), [DELETE VERTEX](../3.ngql-guide/12.vertex-statements/4.delete-vertex.md), [INSERT EDGE](../3.ngql-guide/13.edge-statements/1.insert-edge.md), [DELETE EDGE](../3.ngql-guide/13.edge-statements/4.delete-edge.md)。

## 关于运维

### 日志文件过大时如何回收日志？
Expand Down Expand Up @@ -282,9 +289,9 @@ Nebula Graph {{ nebula.release }} 未提供运维命令以实现自动扩缩容

storaged扩缩容之后，还需要运行[Balance Data 和 Balance Leader 命令](../8.service-tuning/load-balance.md)。

### 修改Host名称后，旧的Host一直显示`OFFLINE`怎么办？
### 修改Host名称后，旧的Host一直显示 `OFFLINE` 怎么办？

`OFFLINE`状态的Host将在一天后自动删除。
`OFFLINE` 状态的 Host 将在一天后自动删除。

## 关于连接

Expand All @@ -300,6 +307,8 @@ storaged扩缩容之后，还需要运行[Balance Data 和 Balance Leader 命令

如果修改过配置文件中预设的端口，请找出实际使用的端口并在防火墙中开放它们。

周边工具各自使用不用的端口，请参考各工具文档。

### 如何测试端口是否已开放

用户可以使用如下telnet命令检查端口状态：
Expand Down
Loading

0 comments on commit 10fd5fd

Please sign in to comment.