Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

whitespace for ngql overview&datatypes&geography #1248

Merged
merged 1 commit into from
Nov 24, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 26 additions & 26 deletions docs-2.0/3.ngql-guide/1.nGQL-overview/1.overview.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# 什么是nGQL
# 什么是 nGQL

nGQL(Nebula Graph Query Language)是Nebula Graph使用的的声明式图查询语言,支持灵活高效的[图模式](3.graph-patterns.md),而且nGQL是为开发和运维人员设计的类SQL查询语言,易于学习。
nGQL(Nebula Graph Query Language)是 Nebula Graph 使用的的声明式图查询语言,支持灵活高效的 [图模式](3.graph-patterns.md),而且 nGQL 是为开发和运维人员设计的类 SQL 查询语言,易于学习。

nGQL是一个进行中的项目,会持续发布新特性和优化,因此可能会出现语法和实际操作不一致的问题,如果遇到此类问题,请提交[issue](https://github.com/vesoft-inc/nebula/issues)通知Nebula Graph团队。Nebula Graph 2.0及更新版本正在支持[openCypher 9](https://www.opencypher.org/resources)。
nGQL 是一个进行中的项目,会持续发布新特性和优化,因此可能会出现语法和实际操作不一致的问题,如果遇到此类问题,请提交 [issue](https://github.com/vesoft-inc/nebula/issues) 通知 Nebula Graph 团队。Nebula Graph 2.0 及更新版本正在支持 [openCypher 9](https://www.opencypher.org/resources)。

## nGQL可以做什么
## nGQL 可以做什么

- 支持图遍历

@@ -20,15 +20,15 @@ nGQL是一个进行中的项目,会持续发布新特性和优化,因此可

- 支持索引

- 支持大部分openCypher 9图查询语法(不支持修改和控制语法)
- 支持大部分 openCypher 9 图查询语法(不支持修改和控制语法)

## 示例数据 Basketballplayer

用户可以下载Nebula Graph示例数据[basketballplayer文件](https://docs.nebula-graph.io/2.0/basketballplayer-2.X.ngql),然后使用[Nebula Graph Console](../../2.quick-start/3.connect-to-nebula-graph.md),使用选项`-f`执行脚本。
用户可以下载 Nebula Graph 示例数据 [basketballplayer 文件](https://docs.nebula-graph.io/2.0/basketballplayer-2.X.ngql),然后使用 [Nebula Graph Console](../../2.quick-start/3.connect-to-nebula-graph.md),使用选项`-f`执行脚本。

## 占位标识符和占位符值

Nebula Graph查询语言nGQL参照以下标准设计
Nebula Graph 查询语言 nGQL 参照以下标准设计

- (Draft) ISO/IEC JTC1 N14279 SC 32 - Database_Languages - GQL

@@ -49,7 +49,7 @@ Nebula Graph查询语言nGQL参照以下标准设计:
| \| | 所有可选的元素。 |
| ... | 可以重复多次。 |

例如创建点或边的nGQL语法
例如创建点或边的 nGQL 语法

```ngql
CREATE {TAG | EDGE} {<tag_name> | <edge_type>}(<property_name> <data_type>
@@ -62,7 +62,7 @@ CREATE {TAG | EDGE} {<tag_name> | <edge_type>}(<property_name> <data_type>
nebula> CREATE TAG IF NOT EXISTS player(name string, age int);
```

## 关于openCypher兼容性
## 关于 openCypher 兼容性

### 原生 nGQL 和 openCypher 的关系

@@ -78,45 +78,45 @@ nebula> CREATE TAG IF NOT EXISTS player(name string, age int);

不要在同一个复合语句中,同时使用`原生 nGQL 语句`和`openCypher 兼容语句`,其行为是未定义的。

### nGQL 完全兼容 openCypher 9吗
### nGQL 完全兼容 openCypher 9 吗

不。

!!! compatibility "nGQL 部分兼容 openCypher 9 的 DQL"

nGQL 设计目标为兼容部分 DQL(match)。不计划兼容任何 DDL,DML,DCL。

在[Nebula Graph Issues](https://github.com/vesoft-inc/nebula/issues?q=is%3Aissue+is%3Aopen+label%3Aincompatible)中已经列出已知的多处不兼容项。如果发现这种类型的新问题,请提交问题并附带`incompatible`标签。在本文搜索"compatibility"或者“兼容性”查看具体不兼容细节。
[Nebula Graph Issues](https://github.com/vesoft-inc/nebula/issues?q=is%3Aissue+is%3Aopen+label%3Aincompatible) 中已经列出已知的多处不兼容项。如果发现这种类型的新问题,请提交问题并附带`incompatible`标签。在本文搜索"compatibility"或者“兼容性”查看具体不兼容细节。


### nGQL 和 openCypher 9的 主要差异有哪些?
### nGQL 和 openCypher 9 的 主要差异有哪些?

|类别| openCypher 9 | nGQL |
| :--- | :--- |:--- |
|Schema| 弱Schema | 强Schema |
|Schema| 弱 Schema | 强 Schema |
|相等运算符| `=` | `==` |
|数学求幂| `^` | 使用`pow(x, y)`替代`^`。 |
|边Rank| 无此概念 | 用`@rank`设置。 |
|边 Rank| 无此概念 | 用`@rank`设置。 |
|语句|-|不支持 openCypher 9 的所有 DML 语句(如`CREATE`、`MERGE`等),不支持所有的 DCL, 和支持部分 `MATCH` 语法和函数(不支持`OPTIONAL MATCH`,不支持多`MATCH`,不支持 `WHERE` 中使用图 pattern)。 |
|语句文本换行 | 换行符 | `\` + 换行符 |
|Label与Tag是不同的概念| Label用于寻找点(点的索引)。 | Tag用于定义点的一种类型及相应的属性,无索引功能。 |
|Label 与 Tag 是不同的概念| Label 用于寻找点(点的索引)。 | Tag 用于定义点的一种类型及相应的属性,无索引功能。 |
| 预编译与参数化查询 | 支持 | 不支持 |

!!! compatibility

请注意[openCypher 9](http://www.opencypher.org/)[Cypher](https://neo4j.com/developer/cypher/)在语法和许可上有不同:
请注意 [openCypher 9](http://www.opencypher.org/)[Cypher](https://neo4j.com/developer/cypher/) 在语法和许可上有不同

1. Cypher要求所有Cypher语句必须“显式地在一个事务中”执行,而openCypher没有这样的要求。另外,nGQL **没有**事务及隔离性。
1. Cypher 要求所有 Cypher 语句必须“显式地在一个事务中”执行,而 openCypher 没有这样的要求。另外,nGQL **没有**事务及隔离性。

2. Cypher 企业版功能有多种的约束(constraints),包括 Unique node property constraints、Node property existence constraints、Relationship property existence constraints、Node key constraints。 OpenCypher 标准中没有约束。 而 nGQL 是强 Schema 系统,前述的约束大多通过 Schema 定义可实现(包括 NOT NULL),唯一不能支持的功能是“属性值唯一性”(UNIQUE constraint)。

3. Cypher 有 APoC,openCypher 9 没有 APoC。Cypher 有 Blot 协议支持要求, openCypher 9 没有。

### 哪里可以找到更多nGQL的示例
### 哪里可以找到更多 nGQL 的示例

用户可以在Nebula Graph GitHub的[features](https://github.com/vesoft-inc/nebula/tree/master/tests/tck/features)目录内查看超过2500条nGQL示例
用户可以在 Nebula Graph GitHub 的 [features](https://github.com/vesoft-inc/nebula/tree/master/tests/tck/features) 目录内查看超过 2500 条 nGQL 示例

features目录内包含很多.features格式的文件,每个文件都记录了使用nGQL的场景和示例。例如:
features 目录内包含很多。features 格式的文件,每个文件都记录了使用 nGQL 的场景和示例。例如:

```text
Feature: Basic match
@@ -178,21 +178,21 @@ Feature: Comparison of where clause
|`Background`|描述当前文档的背景信息。|
|`Given`|描述执行示例语句的前提条件。|
|`Scenario`|描述具体场景。如果场景之前有`@skip`标识,表示这个场景下示例语句可能无法正常工作,请不要在生产环境中使用该示例语句。|
|`When`|描述要执行的nGQL示例语句。可以是`executing query`或`profiling query`。|
|`Then`|描述执行`When`内语句的预期返回结果。如果返回结果和文档不同,请提交[issue](https://github.com/vesoft-inc/nebula/issues)通知Nebula Graph团队。|
|`When`|描述要执行的 nGQL 示例语句。可以是`executing query`或`profiling query`。|
|`Then`|描述执行`When`内语句的预期返回结果。如果返回结果和文档不同,请提交 [issue](https://github.com/vesoft-inc/nebula/issues) 通知 Nebula Graph 团队。|
|`And`|描述执行`When`内语句的副作用或执行计划。|
| `@skip` | 跳过这个示例。通常表示测试代码还没有准备好。 |

欢迎[增加更多 tck case](https://github.com/vesoft-inc/nebula/tree/master/tests),在 CI/CD 中自动回归所使用的语句。
欢迎 [增加更多 tck case](https://github.com/vesoft-inc/nebula/tree/master/tests),在 CI/CD 中自动回归所使用的语句。

### 是否支持TinkerPop Gremlin?
### 是否支持 TinkerPop Gremlin?

不支持。也没有计划。

### 是否支持 W3C 的RDF(SPARQL) 或 GraphQL 等?
### 是否支持 W3C 的 RDF(SPARQL) 或 GraphQL 等?

不支持。也没有计划。

Nebula Graph的数据模型是属性图,是一个强Schema系统,不支持RDF标准
Nebula Graph 的数据模型是属性图,是一个强 Schema 系统,不支持 RDF 标准

nGQL 也不支持 SPARQL 和 GraphQL。
28 changes: 14 additions & 14 deletions docs-2.0/3.ngql-guide/1.nGQL-overview/3.graph-patterns.md
Original file line number Diff line number Diff line change
@@ -36,31 +36,31 @@
(a)-[]->()<-[]-(c)
```

## Tag模式
## Tag 模式

!!! Note

nGQL中的`Tag`概念与openCypher中的`Label`有一些不同。例如,必须创建一个`Tag`之后才能使用它,而且`Tag`还定义了属性的类型。
nGQL 中的`Tag`概念与 openCypher 中的`Label`有一些不同。例如,必须创建一个`Tag`之后才能使用它,而且`Tag`还定义了属性的类型。

模式除了简单地描述图中的点之外,还可以描述点的Tag。例如:
模式除了简单地描述图中的点之外,还可以描述点的 Tag。例如:

```ngql
(a:User)-[]->(b)
```

模式也可以描述有多个Tag的点,例如:
模式也可以描述有多个 Tag 的点,例如:

```ngql
(a:User:Admin)-[]->(b)
```

!!! compatibility "openCypher兼容性"
!!! compatibility "openCypher 兼容性"

nGQL中的`MATCH`语句不支持用`(a:User:Admin)`匹配多个标签。如需匹配多标签可使用过滤条件,如`WHERE "User" IN tags(n) AND "Admin" IN tags(n)`。
nGQL 中的`MATCH`语句不支持用`(a:User:Admin)`匹配多个标签。如需匹配多标签可使用过滤条件,如`WHERE "User" IN tags(n) AND "Admin" IN tags(n)`。

## 属性模式

点和边是图的基本结构。nGQL在这两种结构上都可以增加属性,方便实现更丰富的模型。
点和边是图的基本结构。nGQL 在这两种结构上都可以增加属性,方便实现更丰富的模型。

在模式中,属性的表示方式为:用花括号括起一些键值对,用英文逗号分隔。例如一个点有两个属性:

@@ -90,13 +90,13 @@
(a)-[r]->(b)
```

和点上的Tag一样,边也可以有类型。描述边的类型,例如:
和点上的 Tag 一样,边也可以有类型。描述边的类型,例如:

```ngql
(a)-[r:REL_TYPE]->(b)
```

和点上的Tag不同,一条边只能有一种Edge type。但是如果我们想描述多个可选Edge type,可以用管道符号(|)将可选值分开,例如:
和点上的 Tag 不同,一条边只能有一种 Edge type。但是如果我们想描述多个可选 Edge type,可以用管道符号(|)将可选值分开,例如:

```ngql
(a)-[r:TYPE1|TYPE2]->(b)
@@ -116,7 +116,7 @@
(a)-[*2]->(b)
```

该模式描述了3点2边组成的图,它们都在一条路径上(长度为2),等价于:
该模式描述了 3 点 2 边组成的图,它们都在一条路径上(长度为 2),等价于

```ngql
(a)-[]->()-[]->(b)
@@ -128,9 +128,9 @@
(a)-[*3..5]->(b)
```

`*3..5`表示最小长度为3,最大长度为5
`*3..5`表示最小长度为 3,最大长度为 5

该模式描述了4点3边、5点4边或6点5边组成的图
该模式描述了 4 点 3 边、5 点 4 边或 6 点 5 边组成的图

也可以忽略最小长度,只指定最大长度,例如:

@@ -144,10 +144,10 @@

## 路径变量

一系列连接的点和边称为`路径`。nGQL允许使用变量来命名路径,例如:
一系列连接的点和边称为`路径`。nGQL 允许使用变量来命名路径,例如:

```ngql
p = (a)-[*3..5]->(b)
```

可以在MATCH语句中使用路径变量
可以在 MATCH 语句中使用路径变量
18 changes: 9 additions & 9 deletions docs-2.0/3.ngql-guide/1.nGQL-overview/comments.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# 注释

本文介绍nGQL中的注释方式
本文介绍 nGQL 中的注释方式

## 历史版本兼容性

* Nebula Graph 1.0支持四种注释方式: `#`、`--`、`//`、`/* */`。
* Nebula Graph 2.0中,`--`不再是注释符,而是代表[边模式](../../3.ngql-guide/1.nGQL-overview/3.graph-patterns.md)。
* Nebula Graph 1.0 支持四种注释方式:`#`、`--`、`//`、`/* */`。
* Nebula Graph 2.0 中,`--`不再是注释符,而是代表 [边模式](../../3.ngql-guide/1.nGQL-overview/3.graph-patterns.md)。

## Examples

@@ -20,15 +20,15 @@ nebula> RETURN 11 + \
*/ 12;
```

nGQL语句中的反斜线(\)代表换行。
nGQL 语句中的反斜线(\)代表换行。

## OpenCypher兼容性
## OpenCypher 兼容性

* 在nGQL中,用户必须在行末使用反斜线(\)来换行,即使是在使用`/* */`符号的多行注释内。
* 在openCypher中不需要使用反斜线换行
* 在 nGQL 中,用户必须在行末使用反斜线(\)来换行,即使是在使用`/* */`符号的多行注释内。
* 在 openCypher 中不需要使用反斜线换行

```openCypher
/* openCypher风格
/* openCypher 风格
这条注释
延续了不止
一行 */
@@ -37,7 +37,7 @@ RETURN n;
```

```ngql
/* 原生nGQL风格: \
/* 原生 nGQL 风格: \
这条注释 \
延续了不止 \
一行 */ \
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# 关键字

关键字在nGQL中有重要意义,分为保留关键字和非保留关键字。
关键字在 nGQL 中有重要意义,分为保留关键字和非保留关键字。

非保留关键字作为标识符时可以不使用引号。保留关键字作为标识符时,需要用反引号(\`)将它们括起来,例如\`AND\`。
非保留关键字作为标识符时可以不使用引号。保留关键字作为标识符时,需要用反引号(\`)将它们括起来,例如 \`AND\`。

!!! Note

22 changes: 11 additions & 11 deletions docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# nGQL风格指南
# nGQL 风格指南

nGQL没有严格的构建格式要求,但根据恰当而统一的风格创建nGQL语句有利于提高可读性、避免歧义。在同一组织或项目中使用相同的nGQL风格有利于降低维护成本,规避因格式混乱或误解造成的问题。本文为写作nGQL语句提供了风格参考
nGQL 没有严格的构建格式要求,但根据恰当而统一的风格创建 nGQL 语句有利于提高可读性、避免歧义。在同一组织或项目中使用相同的 nGQL 风格有利于降低维护成本,规避因格式混乱或误解造成的问题。本文为写作 nGQL 语句提供了风格参考

!!! compatibility

nGQL 风格与[Cypher Style Guide](https://s3.amazonaws.com/artifacts.opencypher.org/M15/docs/style-guide.pdf)不同。
nGQL 风格与 [Cypher Style Guide](https://s3.amazonaws.com/artifacts.opencypher.org/M15/docs/style-guide.pdf) 不同。

## 换行

@@ -44,7 +44,7 @@ nGQL没有严格的构建格式要求,但根据恰当而统一的风格创建n
YIELD properties($^).name AS FriendOf, properties($$).name AS Team;
```

3. 子句长度超过80个字符时,在合适的位置换行。
3. 子句长度超过 80 个字符时,在合适的位置换行。

不推荐:

@@ -65,13 +65,13 @@ nGQL没有严格的构建格式要求,但根据恰当而统一的风格创建n

!!! note

即使子句不超过80个字符,如需换行后有助于理解,也可将子句再次分行。
即使子句不超过 80 个字符,如需换行后有助于理解,也可将子句再次分行。

## 标识符命名

在nGQL语句中,关键字、标点符号、空格以外的字符内容都是标识符。推荐的标识符命名方式如下。
在 nGQL 语句中,关键字、标点符号、空格以外的字符内容都是标识符。推荐的标识符命名方式如下。

1. 使用单数名词命名Tag,用原型动词或动词短语构成Edge type。
1. 使用单数名词命名 Tag,用原型动词或动词短语构成 Edge type。

不推荐:

@@ -111,15 +111,15 @@ nGQL没有严格的构建格式要求,但根据恰当而统一的风格创建n
go from "player100" over Follow
```

推荐:
推荐

```ngql
GO FROM "player100" OVER follow
```

## Pattern

1. 分行写Pattern时,在表示边的箭头右侧换行,而不是左侧。
1. 分行写 Pattern 时,在表示边的箭头右侧换行,而不是左侧。

不推荐:

@@ -187,7 +187,7 @@ nGQL没有严格的构建格式要求,但根据恰当而统一的风格创建n

!!! note

字符串中需要嵌套单引号或双引号时,用反斜线(\)转义。例如:
字符串中需要嵌套单引号或双引号时,用反斜线(\)转义。例如

```ngql
RETURN "\"Nebula Graph is amazing,\" the user says.";
@@ -197,7 +197,7 @@ nGQL没有严格的构建格式要求,但根据恰当而统一的风格创建n

## 结束语句

1. 用英文分号(;)结束nGQL语句
1. 用英文分号(;)结束 nGQL 语句

不推荐:

Loading