quick start

docs-2.0/2.quickstart/0.FAQ.md

@@ -0,0 +1,103 @@
+# 常见问题FAQ
+
+## 关于openCypher兼容性
+
+### nGQL兼容openCypher 9吗？
+
+nGQL部分兼容openCypher 9。
+
+在[Nebula Graph Issues](https://github.com/vesoft-inc/nebula-graph/issues)中已经列出已知的不兼容项。如果您发现这种类型的新问题，请提交问题并附带`incompatible`标签。您可以通过关键字`compatibility`搜索兼容性问题。
+
+下面是nGQL和openCypher 9的主要差异（由于设计原因而不兼容）。
+
+|类别| openCypher 9 | nGQL |
+| :--- | :--- |:--- |
+|Schema| 弱Schema | 强Schema |
+|相等运算符| `=` | `==` |
+|数学求幂| `^` | 使用`pow(x, y)`替代`^` | 
+|边rank| 无此概念 | 用`@rank`设置 |
+|语句|-|不支持openCypher 9的所有DML语句（`CREATE`、`MERGE`等）和部分`MATCH`语句。 |
+
+>**说明**：请注意[openCypher 9](http://www.opencypher.org/)和[Cypher](https://neo4j.com/developer/cypher/)在语法和许可上有一些不同。例如Cypher要求所有Cypher语句必须显式地在一个事务中执行，而openCypher没有这样的要求。另外，nGQL暂不支持事务。
+
+### 哪里可以找到更多nGQL的示例？
+
+您可以在Nebula Graph GitHub的[features](https://github.com/vesoft-inc/nebula-graph/tree/master/tests/tck/features)目录内查看超过2500条nGQL示例。
+
+features目录内包含很多.features格式的文件，每个文件都记录了使用nGQL的场景和示例。例如：
+
+```text
+Feature: Match seek by tag
+
+ Background: Prepare space
+ Given a graph with space named "nba"
+
+ Scenario: seek by empty tag index
+ When executing query:
+ """
+ MATCH (v:bachelor)
+ RETURN id(v) AS vid
+ """
+ Then the result should be, in any order:
+ | vid |
+ | 'Tim Duncan' |
+ And no side effects
+ When executing query:
+ """
+ MATCH (v:bachelor)
+ RETURN id(v) AS vid, v.age AS age
+ """
+ Then the result should be, in any order:
+ | vid | age |
+ | 'Tim Duncan' | 42 |
+ And no side effects
+```
+
+示例中的关键字说明如下。
+
+|关键字|说明|
+|:---|:---|
+|`Feature`|描述当前文档的主题。|
+|`Background`|描述当前文档的背景信息。|
+|`Given`|描述执行示例语句的前提条件。|
+|`Scenario`|描述具体场景。如果场景之前有`@skip`标识，表示这个场景下示例语句可能无法正常工作，请不要在生产环境中使用该示例语句。|
+|`When`|描述要执行的nGQL示例语句。|
+|`Then`|描述执行`When`内语句的预期返回结果。如果您的返回结果和文档不同，请提交[issue](https://github.com/vesoft-inc/nebula-graph/issues)通知Nebula Graph团队。|
+|`And`|描述执行`When`内语句的副作用。|
+| `@skip` | 跳过这个示例。通常表示测试代码还没有准备好。 |
+
+欢迎您[增加更多实用场景示例](https://docs.nebula-graph.io/1.1/manual-EN/4.contributions/how-to-contribute/)，成为Nebula Graph贡献者。
+
+## 关于程序执行
+
+### 返回消息中`time spent`的含义是什么？
+
+将命令`SHOW SPACES`返回的消息作为示例：
+
+```nGQL
+nebula> SHOW SPACES;
++------+
+| Name |
++------+
+| nba |
++------+
+Got 1 rows (time spent 1235/1934 us)
+```
+
+- 第一个数字`1235`表示数据库本身执行该命令花费的时间，即查询引擎从客户端接收到一个查询，然后从存储服务器获取数据并执行一系列计算所花费的时间。
+
+- 第二个数字`1934`表示从客户端角度看所花费的时间，即从客户端发送请求、接收结果，然后在屏幕上显示结果所花费的时间。
+
+### 可以在`CREATE SPACE`时设置`replica_factor`为偶数（例如设置为2）吗？
+
+不要这样设置。
+
+Storage服务使用Raft协议，为保证可用性，要求出故障的副本数量不能超过一半。
+
+如果`replica_factor=2`，当其中一个副本故障时，就会导致系统无法工作；如果`replica_factor=4`，只能有一个副本可以出现故障，这和`replica_factor=3`是一样。以此类推，所以`replica_factor`设置为奇数即可。
+
+建议您在生产环境中设置`replica_factor=3`，测试环境中设置`replica_factor=1`，不要使用偶数。
+
+### 如何处理报错`[ERROR (-7)]: SyntaxError: syntax error near`？
+
+大部分情况下，查询语句需要有`YIELD`或`RETURN`，请检查您的查询语句是否包含。

docs-2.0/2.quickstart/1.quick-start-workflow.md

@@ -0,0 +1,15 @@
+# 快速入门
+
+快速入门将介绍如何简单地使用Nebula Graph，包括部署、连接Nebula Graph，以及基础的增删改查操作。
+
+1. [Docker Compose部署Nebula Graph](2.deploy-nebula-graph-with-docker-compose.md)
+
+2. [连接Nebula Graph](3.connect-to-nebula-graph.md)
+
+3. [基础操作语法](4.nebula-graph-crud.md)
+
+以下是其他推荐您阅读的文档。在您尝试过快速入门的操作后，您可能会需要阅读它们来进一步了解和使用Nebula Graph。
+
+- [常见问题FAQ](./0.FAQ.md)
+- 部署Nebula Graph集群 (TODO: doc）
+- [Compaction](../8.service-tuning/compaction.md)

docs-2.0/2.quickstart/2.deploy-nebula-graph-with-docker-compose.md

@@ -0,0 +1,262 @@
+# Docker Compose部署Nebula Graph
+
+有多种方式可以部署Nebula Graph，但是使用Docker Compose通常是最快的方式。
+
+## 阅读指南
+
+如果您是带着如下问题阅读本文，可以直接单击问题跳转查看对应的说明。
+
+- [部署Nebula Graph之前需要做什么准备工作？](#前提条件)
+
+- [如何通过Docker Compose快速部署Nebula Graph？](#部署和连接Nebula_Graph)
+
+- [如何检查Nebula Graph服务的状态和端口？](#查看Nebula_Graph服务的状态和端口)
+
+- [如何检查Nebula Graph服务的数据和日志？](#查看Nebula_Graph服务的数据和日志)
+
+- [如何停止Nebula Graph服务？](#停止Nebula_Graph服务)
+
+- [如何通过其他方式部署Nebula Graph？](#相关文档)
+
+## 前提条件
+
+- 主机上安装如下应用程序。
+
+ | 应用程序 | 推荐版本 | 官方安装参考 |
+ |:---|:---|:---|
+ |Docker|最新版本|[Install Docker Engine](https://docs.docker.com/engine/install/) |
+ |Docker Compose|最新版本|[Install Docker Compose](https://docs.docker.com/compose/install/)|
+ |Git|最新版本|[Download Git](https://git-scm.com/download/)|
+
+- 如果您使用非root用户部署Nebula Graph，请授权该用户Docker相关的权限。详细信息，请参见[Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)。
+
+- 启动主机上的Docker服务。
+
+- 如果您已经通过Docker Compose在主机上部署了另一个版本的Nebula Graph，为避免兼容性问题，需要您删除目录`nebula-docker-compose/data`。
+
+ >**说明**：如果您需要备份服务数据，请参见[使用BR备份数据](../7.data-security/2.backup-restore/3.br-backup-data.md) 。
+
+## 部署和连接Nebula Graph
+
+1. 通过Git克隆`nebula-docker-compose`仓库的`master`分支到您的主机。
+
+ >**禁止**：`master`分支包含最新的Nebula Graph开发版本的Docker Compose解决方案。请**不要**在生产环境使用此版本。
+
+ ```bash
+ $ git clone https://github.com/vesoft-inc/nebula-docker-compose.git
+ ```
+
+2. 切换至目录`nebula-docker-compose`。
+
+ ```bash
+ $ cd nebula-docker-compose/
+ ```
+
+3. 执行如下命令启动Nebula Graph服务。
+
+ >**说明**: 如果长期未更新镜像，请先更新[Nebula Graph镜像](#如何升级nebula-graph)和[Nebula Console镜像](#如何更新nebula-console)。
+
+ ```bash
+ nebula-docker-compose]$ docker-compose up -d
+ Creating nebula-docker-compose_metad0_1 ... done
+ Creating nebula-docker-compose_metad2_1 ... done
+ Creating nebula-docker-compose_metad1_1 ... done
+ Creating nebula-docker-compose_graphd2_1 ... done
+ Creating nebula-docker-compose_graphd_1 ... done
+ Creating nebula-docker-compose_graphd1_1 ... done
+ Creating nebula-docker-compose_storaged0_1 ... done
+ Creating nebula-docker-compose_storaged2_1 ... done
+ Creating nebula-docker-compose_storaged1_1 ... done
+ ```
+
+ >**说明**: 上述服务的更多信息，请参见[架构总览](../1.introduction/3.nebula-graph-architecture/1.architecture-overview.md)。
+
+4. 连接Nebula Graph。
+
+ 1. 使用Nebula Console镜像启动一个容器，并连接到Nebula Graph服务所在的网络（nebula-docker-compose_nebula-net）中。
+
+ ```bash
+ $ docker run --rm -ti --network nebula-docker-compose_nebula-net --entrypoint=/bin/sh vesoft/nebula-console:v2-nightly
+ ```
+
+ >**说明**：您的本地网络可能和示例中的`nebula-docker-compose_nebula-net`不同，请使用如下命令查看。
+
+ ```bash
+ $ docker network ls
+ NETWORK ID NAME DRIVER SCOPE
+ a74c312b1d16 bridge bridge local
+ dbfa82505f0e host host local
+ ed55ccf356ae nebula-docker-compose_nebula-net bridge local
+ 93ba48b4b288 none null local
+ ```
+
+ 1. 通过Nebula Console连接Nebula Graph。
+
+ ```bash
+ docker> nebula-console -u user -p password --address=graphd --port=9669
+ ```
+
+ >**说明**：默认情况下，身份认证功能是关闭的，可以使用任意用户名和密码登录。如果想使用身份认证，请参见[身份认证](../7.data-secrurity/1.authentication/1.authentication.md)。
+
+ 1. 执行如下命令检查`nebula-storaged`进程状态。
+
+ ```bash
+ nebula> SHOW HOSTS;
+ +-------------+------+----------+--------------+----------------------+------------------------+
+ | Host | Port | Status | Leader count | Leader distribution | Partition distribution |
+ +-------------+------+----------+--------------+----------------------+------------------------+
+ | "storaged0" | 9779 | "ONLINE" | 0 | "No valid partition" | "No valid partition" |
+ +-------------+------+----------+--------------+----------------------+------------------------+
+ | "storaged1" | 9779 | "ONLINE" | 0 | "No valid partition" | "No valid partition" |
+ +-------------+------+----------+--------------+----------------------+------------------------+
+ | "storaged2" | 9779 | "ONLINE" | 0 | "No valid partition" | "No valid partition" |
+ +-------------+------+----------+--------------+----------------------+------------------------+
+ | "Total" | | | 0 | | |
+ +-------------+------+----------+--------------+----------------------+------------------------+
+ ```
+
+5. 执行两次`exit` 可以退出容器。
+
+## 查看Nebula Graph服务的状态和端口
+
+执行命令`docker-compose ps`可以列出Nebula Graph服务的状态和端口。
+
+```bash
+$ docker-compose ps
+Name Command State Ports
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------
+nebula-docker-compose_graphd1_1 ./bin/nebula-graphd --flag ... Up (health: starting) 13000/tcp, 13002/tcp, 0.0.0.0:33295->19669/tcp, 0.0.0.0:33291->19670/tcp,
+ 3699/tcp, 0.0.0.0:33298->9669/tcp
+nebula-docker-compose_graphd2_1 ./bin/nebula-graphd --flag ... Up (health: starting) 13000/tcp, 13002/tcp, 0.0.0.0:33285->19669/tcp, 0.0.0.0:33284->19670/tcp,
+ 3699/tcp, 0.0.0.0:33286->9669/tcp
+nebula-docker-compose_graphd_1 ./bin/nebula-graphd --flag ... Up (health: starting) 13000/tcp, 13002/tcp, 0.0.0.0:33288->19669/tcp, 0.0.0.0:33287->19670/tcp,
+ 3699/tcp, 0.0.0.0:9669->9669/tcp
+nebula-docker-compose_metad0_1 ./bin/nebula-metad --flagf ... Up (health: starting) 11000/tcp, 11002/tcp, 0.0.0.0:33276->19559/tcp, 0.0.0.0:33275->19560/tcp,
+ 45500/tcp, 45501/tcp, 0.0.0.0:33278->9559/tcp
+nebula-docker-compose_metad1_1 ./bin/nebula-metad --flagf ... Up (health: starting) 11000/tcp, 11002/tcp, 0.0.0.0:33279->19559/tcp, 0.0.0.0:33277->19560/tcp,
+ 45500/tcp, 45501/tcp, 0.0.0.0:33281->9559/tcp
+nebula-docker-compose_metad2_1 ./bin/nebula-metad --flagf ... Up (health: starting) 11000/tcp, 11002/tcp, 0.0.0.0:33282->19559/tcp, 0.0.0.0:33280->19560/tcp,
+ 45500/tcp, 45501/tcp, 0.0.0.0:33283->9559/tcp
+nebula-docker-compose_storaged0_1 ./bin/nebula-storaged --fl ... Up (health: starting) 12000/tcp, 12002/tcp, 0.0.0.0:33290->19779/tcp, 0.0.0.0:33289->19780/tcp,
+ 44500/tcp, 44501/tcp, 0.0.0.0:33294->9779/tcp
+nebula-docker-compose_storaged1_1 ./bin/nebula-storaged --fl ... Up (health: starting) 12000/tcp, 12002/tcp, 0.0.0.0:33296->19779/tcp, 0.0.0.0:33292->19780/tcp,
+ 44500/tcp, 44501/tcp, 0.0.0.0:33299->9779/tcp
+nebula-docker-compose_storaged2_1 ./bin/nebula-storaged --fl ... Up (health: starting) 12000/tcp, 12002/tcp, 0.0.0.0:33297->19779/tcp, 0.0.0.0:33293->19780/tcp,
+ 44500/tcp, 44501/tcp, 0.0.0.0:33300->9779/tcp
+```
+
+Nebula Graph默认使用`9669`端口为客户端提供服务，如果需要修改端口，请修改目录`nebula-docker-compose`内的文件`docker-compose.yaml`，然后重启Nebula Graph服务。
+
+## 查看Nebula Graph服务的数据和日志
+
+Nebula Graph的所有数据和日志都持久化存储在`nebula-docker-compose/data`和`nebula-docker-compose/logs`目录中。
+
+目录的结构如下：
+
+```text
+nebula-docker-compose/
+ |-- docker-compose.yaml
+ ├── data
+ │   ├── meta0
+ │   ├── meta1
+ │   ├── meta2
+ │   ├── storage0
+ │   ├── storage1
+ │   └── storage2
+ └── logs
+ ├── graph
+ ├── graph1
+ ├── graph2
+ ├── meta0
+ ├── meta1
+ ├── meta2
+ ├── storage0
+ ├── storage1
+ └── storage2
+```
+
+## 停止Nebula Graph服务
+
+您可以执行如下命令停止Nebula Graph服务：
+
+```bash
+$ docker-compose down
+```
+
+如果返回如下信息，表示已经成功停止服务。
+
+```bash
+Stopping nebula-docker-compose_storaged0_1 ... done
+Stopping nebula-docker-compose_graphd1_1 ... done
+Stopping nebula-docker-compose_graphd_1 ... done
+Stopping nebula-docker-compose_storaged1_1 ... done
+Stopping nebula-docker-compose_graphd2_1 ... done
+Stopping nebula-docker-compose_storaged2_1 ... done
+Stopping nebula-docker-compose_metad0_1 ... done
+Stopping nebula-docker-compose_metad2_1 ... done
+Stopping nebula-docker-compose_metad1_1 ... done
+Removing nebula-docker-compose_storaged0_1 ... done
+Removing nebula-docker-compose_graphd1_1 ... done
+Removing nebula-docker-compose_graphd_1 ... done
+Removing nebula-docker-compose_storaged1_1 ... done
+Removing nebula-docker-compose_graphd2_1 ... done
+Removing nebula-docker-compose_storaged2_1 ... done
+Removing nebula-docker-compose_metad0_1 ... done
+Removing nebula-docker-compose_metad2_1 ... done
+Removing nebula-docker-compose_metad1_1 ... done
+Removing network nebula-docker-compose_nebula-net
+```
+
+>**说明**：命令`docker-compose down -v`将会**删除**所有本地Nebula Graph的数据。如果您使用的是developing或nightly版本，并且有一些兼容性问题，请尝试这个命令。
+
+## 常见问题
+
+### 如何更新Nebula Graph服务的Docker镜像？
+
+在目录`nebula-docker-compose`内执行命令`docker-compose pull`，可以更新Graph服务、Storage服务和Meta服务的镜像。
+
+### 执行命令`docker-compose pull`报错`ERROR: toomanyrequests`
+
+您可能遇到如下错误：
+
+`ERROR: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit`
+
+以上错误表示您已达到Docker Hub的速率限制。解决方案请参见[Understanding Docker Hub Rate Limiting](https://www.docker.com/increase-rate-limit)。
+
+### 如何更新Nebula Console？
+
+执行如下命令可以更新Nebula Console客户端镜像。
+
+```bash
+docker pull vesoft/nebula-console:v2-nightly
+```
+
+### 如何升级Nebula Graph？
+
+更新Nebula Graph的Docker镜像并重启服务：
+
+1. 在目录`nebula-docker-compose`内，执行命令`docker-compose pull`更新Nebula Graph的Docker镜像。
+
+2. 执行命令`docker-compose down`停止Nebula Graph服务。
+
+3. 执行命令`docker-compose up -d`启动Nebula Graph服务。
+
+
+### 为什么更新nebula-docker-compose仓库（Nebula Graph 2.0.0-RC）后，无法通过端口`3699`连接Nebula Graph？
+
+在Nebula Graph 2.0.0-RC版本，默认端口从`3699`改为`9669`。请使用`9669`端口连接，或修改配置文件`docker-compose.yaml`内的端口。
+
+### 为什么更新nebula-docker-compose仓库后，无法访问数据？（2021年01月04日）
+
+如果您在2021年01月04日后更新过nebula-docker-compose仓库，而且之前已经有数据，请修改文件`docker-compose.yaml`，将端口修改为之前使用的端口。详情请参见[修改默认端口](https://github.com/vesoft-inc/nebula-docker-compose/commit/2a612f1c4f0e2c31515e971b24b355b3be69420a)。
+
+### 为什么更新nebula-docker-compose仓库后，无法访问数据？（2021年01月27日）
+
+2021年01月27日修改了数据格式，无法兼容之前的数据，请执行命令`docker-compose down -v`删除所有本地数据。
+
+## 相关文档
+
+- [使用源码安装部署Nebula Graph](../4.deployment-and-installation/2.compile-and-install-nebula-graph/1.install-nebula-graph-by-compiling-the-source-code.md)
+- 使用容器安装部署（TODO: doc）
+- [使用RPM或DEB安装包安装Nebula Graph](../4.deployment-and-installation/2.compile-and-install-nebula-graph/2.install-nebula-graph-by-rpm-or-deb.md)
+- [多种方式连接Nebula Graph](3.connect-to-nebula-graph.md)