diff --git a/docs-2.0/2.quick-start/4.nebula-graph-crud.md b/docs-2.0/2.quick-start/4.nebula-graph-crud.md index 1893c094bcd..7a2e703510d 100644 --- a/docs-2.0/2.quick-start/4.nebula-graph-crud.md +++ b/docs-2.0/2.quick-start/4.nebula-graph-crud.md @@ -272,9 +272,10 @@ Execution succeeded (time spent 5858/6870 us) OVER [{REVERSELY | BIDIRECT}] [ WHERE  ] [YIELD [DISTINCT] ] + [{SAMPLE | LIMIT }] [| GROUP BY {col_name | expr | position} YIELD ] [| ORDER BY [{ASC | DESC}]] - [| LIMIT [,] ]; + [| LIMIT [,] ]; ``` - `FETCH` diff --git a/docs-2.0/3.ngql-guide/7.general-query-statements/3.go.md b/docs-2.0/3.ngql-guide/7.general-query-statements/3.go.md index 2719782a982..6287f5dbebc 100644 --- a/docs-2.0/3.ngql-guide/7.general-query-statements/3.go.md +++ b/docs-2.0/3.ngql-guide/7.general-query-statements/3.go.md @@ -13,9 +13,10 @@ GO [[ TO] STEPS ] FROM OVER [{REVERSELY | BIDIRECT}] [ WHERE  ] [YIELD [DISTINCT] ] +[{SAMPLE | LIMIT }] [| GROUP BY {col_name | expr | position} YIELD ] [| ORDER BY [{ASC | DESC}]] -[| LIMIT [,] ]; +[| LIMIT [,] ]; ::= [, ...] @@ -32,33 +33,37 @@ OVER [{REVERSELY | BIDIRECT}] !!! note - `GO`语句采用的路径类型是`walk`，即遍历时点和边可以重复。详情请参见[路径](../../1.introduction/2.1.path.md)。 + `GO`语句采用的路径类型是`walk`，即遍历时点和边可以重复。详情参见[路径](../../1.introduction/2.1.path.md)。 - `M TO N STEPS`：遍历`M~N`跳的边。如果`M`为`0`，输出结果和`M`为`1`相同，即`GO 0 TO 2`和`GO 1 TO 2`是相同的。 -- ``：用逗号分隔的点ID列表，或特殊的引用符`$-.id`。详情请参见[管道符](../5.operators/4.pipe.md)。 +- ``：用逗号分隔的点ID列表，或特殊的引用符`$-.id`。详情参见[管道符](../5.operators/4.pipe.md)。 - ``：遍历的Edge type列表。 - `REVERSELY | BIDIRECT`：默认情况下检索的是``的出边（正向），`REVERSELY`表示反向，即检索入边；`BIDIRECT` 为双向，即检索正向和反向，通过返回 `._type` 字段判断方向，其正数为正向，负数为反向。 -- `WHERE `：指定遍历的过滤条件。用户可以在起始点、目的点和边使用`WHERE`子句，还可以结合`AND`、`OR`、`NOT`、`XOR`一起使用。详情请参见[WHERE](../8.clauses-and-options/where.md)。 +- `WHERE `：指定遍历的过滤条件。用户可以在起始点、目的点和边使用`WHERE`子句，还可以结合`AND`、`OR`、`NOT`、`XOR`一起使用。详情参见[WHERE](../8.clauses-and-options/where.md)。 !!! Note 遍历多个Edge type时，`WHERE`子句有一些限制。例如不支持`WHERE edge1.prop1 > edge2.prop2`。 -- `YIELD [DISTINCT] `：定义需要返回的输出。` `建议使用[Schema函数](../6.functions-and-expressions/4.schema.md)，当前支持`src(edge)`、`dst(edge)`、`type(edge)`、`rank(edge)`、`properties(edge)`、`id(vertex)`、`properties(vertex)`，暂不支持嵌套函数。详情请参见[YIELD](../8.clauses-and-options/yield.md)。如果没有指定，默认返回目的点ID。 +- `YIELD [DISTINCT] `：定义需要返回的输出。` `建议使用[Schema函数](../6.functions-and-expressions/4.schema.md)，当前支持`src(edge)`、`dst(edge)`、`type(edge)`、`rank(edge)`、`properties(edge)`、`id(vertex)`、`properties(vertex)`，暂不支持嵌套函数。详情参见[YIELD](../8.clauses-and-options/yield.md)。如果没有指定，默认返回目的点ID。 -- `GROUP BY`：根据指定属性的值将输出分组。详情请参见[GROUP BY](../8.clauses-and-options/group-by.md)。分组后需要再次使用`YIELD`定义需要返回的输出。 +- `SAMPLE `：用于在结果集中取样。详情参见[SAMPLE](../8.clauses-and-options/sample.md)。 -- `ORDER BY`：指定输出结果的排序规则。详情请参见[ORDER BY](../8.clauses-and-options/order-by.md)。 +- `LIMIT `：用于在遍历过程中逐步限制输出数量。详情参见[LIMIT](../8.clauses-and-options/limit.md)。 + +- `GROUP BY`：根据指定属性的值将输出分组。详情参见[GROUP BY](../8.clauses-and-options/group-by.md)。分组后需要再次使用`YIELD`定义需要返回的输出。 + +- `ORDER BY`：指定输出结果的排序规则。详情参见[ORDER BY](../8.clauses-and-options/order-by.md)。 !!! Note 没有指定排序规则时，输出结果的顺序不是固定的。 -- `LIMIT`：限制输出结果的行数。详情请参见[LIMIT](../8.clauses-and-options/limit.md)。 +- `LIMIT [,] ]`：限制输出结果的行数。详情参见[LIMIT](../8.clauses-and-options/limit.md)。 ## 示例 diff --git a/docs-2.0/3.ngql-guide/8.clauses-and-options/sample.md b/docs-2.0/3.ngql-guide/8.clauses-and-options/sample.md new file mode 100644 index 00000000000..b04d0d21cb7 --- /dev/null +++ b/docs-2.0/3.ngql-guide/8.clauses-and-options/sample.md @@ -0,0 +1,52 @@ +# SAMPLE + +`SAMPLE`子句用于在结果集中均匀取样并返回指定数量的数据。 + +!!! compatibility "历史版本兼容性" + + `SAMPLE`是Nebula Graph 2.6.0 新增的子句。 + +`SAMPLE`仅能在`GO`语句中使用，语法如下： + +```ngql + SAMPLE ; +``` + +`sample_list`是一个列表，列表中的元素必须为自然数，且元素数量必须与`GO`语句中的`STEPS`的最大数相同。下文以`GO 1 TO 3 STEPS FROM "A" OVER * SAMPLE `为例详细介绍`SAMPLE`的用法。 + +* 列表`sample_list`必须包含3个自然数元素，例如`GO 1 TO 3 STEPS FROM "A" OVER * SAMPLE [1,2,4]`。 +* `SAMPLE [1,2,4]`中的`1`表示系统在第一步时自动选择1条边继续遍历，`2`表示在第二步时选择2条边继续遍历，`4`表示在第三步时选择4条边继续遍历。如果某一步没有匹配的边或者匹配到的边数量小于指定数量，则按实际数量返回。 +* 因为`GO 1 TO 3 STEPS`表示返回第一到第三步的所有遍历结果，因此下图中所有红色边和它们的原点与目的点都会被这条`GO`语句匹配上，而黄色边表示`GO`语句遍历时没有选择的路径。如果不是`GO 1 TO 3 STEPS`而是`GO 3 STEPS`，则只会匹配上第三步的红色边和它们两端的点。 + +![SAMPLE in GO](sample_in_go.png) + +在basketballplayer数据集中的执行示例如下： + +```ngql +nebula> GO 3 STEPS FROM "player100" \ + OVER * \ + YIELD properties($$).name AS NAME, properties($$).age AS Age \ + SAMPLE [1,2,3]; ++-----------------+--------------+ +| NAME | Age | ++-----------------+--------------+ +| "Spurs" | UNKNOWN_PROP | +| "Tony Parker" | 36 | +| "Manu Ginobili" | 41 | ++-----------------+--------------+ + +nebula> GO 1 TO 3 STEPS FROM "player100" \ + OVER * \ + YIELD properties($$).name AS NAME, properties($$).age AS Age \ + SAMPLE [2,2,2]; ++---------------------+-----+ +| NAME | Age | ++---------------------+-----+ +| "Manu Ginobili" | 41 | +| "Tony Parker" | 36 | +| "Tim Duncan" | 42 | +| "LaMarcus Aldridge" | 33 | +| "Tony Parker" | 36 | +| "Tim Duncan" | 42 | ++---------------------+-----+ +``` diff --git a/docs-2.0/3.ngql-guide/8.clauses-and-options/sample_in_go.png b/docs-2.0/3.ngql-guide/8.clauses-and-options/sample_in_go.png new file mode 100644 index 00000000000..fc23ccb95d7 Binary files /dev/null and b/docs-2.0/3.ngql-guide/8.clauses-and-options/sample_in_go.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 90f491f5e93..842bcbb9cc8 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -208,6 +208,7 @@ nav: - 子句和选项: - GROUP BY: 3.ngql-guide/8.clauses-and-options/group-by.md - LIMIT and SKIP: 3.ngql-guide/8.clauses-and-options/limit.md + - SAMPLE: 3.ngql-guide/8.clauses-and-options/sample.md - ORDER BY: 3.ngql-guide/8.clauses-and-options/order-by.md - RETURN: 3.ngql-guide/8.clauses-and-options/return.md - TTL: 3.ngql-guide/8.clauses-and-options/ttl-options.md