Add sample doc

docs-2.0/2.quick-start/4.nebula-graph-crud.md

@@ -272,9 +272,10 @@ Execution succeeded (time spent 5858/6870 us)
     OVER <edge_type_list> [{REVERSELY | BIDIRECT}]
     [ WHERE <conditions> ]
     [YIELD [DISTINCT] <return_list>]
+    [{SAMPLE <sample_list> | LIMIT <limit_list>}]
     [| GROUP BY {col_name | expr | position} YIELD <col_name>]
     [| ORDER BY <expression> [{ASC | DESC}]]
-    [| LIMIT [<offset_value>,] <number_rows>];
+    [| LIMIT [<offset>,] <number_rows>];
     ```
 
 - `FETCH`

docs-2.0/3.ngql-guide/7.general-query-statements/3.go.md

@@ -13,9 +13,10 @@ GO [[<M> TO] <N> STEPS ] FROM <vertex_list>
 OVER <edge_type_list> [{REVERSELY | BIDIRECT}]
 [ WHERE <conditions> ]
 [YIELD [DISTINCT] <return_list>]
+[{SAMPLE <sample_list> | LIMIT <limit_list>}]
 [| GROUP BY {col_name | expr | position} YIELD <col_name>]
 [| ORDER BY <expression> [{ASC | DESC}]]
-[| LIMIT [<offset_value>,] <number_rows>];
+[| LIMIT [<offset>,] <number_rows>];
 
 <vertex_list> ::=
     <vid> [, <vid> ...]
@@ -32,33 +33,37 @@ OVER <edge_type_list> [{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`是相同的。
 
-- `<vertex_list>`：用逗号分隔的点ID列表，或特殊的引用符`$-.id`。详情请参见[管道符](../5.operators/4.pipe.md)。
+- `<vertex_list>`：用逗号分隔的点ID列表，或特殊的引用符`$-.id`。详情参见[管道符](../5.operators/4.pipe.md)。
 
 - `<edge_type_list>`：遍历的Edge type列表。
 
 - `REVERSELY | BIDIRECT`：默认情况下检索的是`<vertex_list>`的出边（正向），`REVERSELY`表示反向，即检索入边；`BIDIRECT` 为双向，即检索正向和反向，通过返回 `<edge_type>._type` 字段判断方向，其正数为正向，负数为反向。
 
-- `WHERE <conditions>`：指定遍历的过滤条件。用户可以在起始点、目的点和边使用`WHERE`子句，还可以结合`AND`、`OR`、`NOT`、`XOR`一起使用。详情请参见[WHERE](../8.clauses-and-options/where.md)。
+- `WHERE <conditions>`：指定遍历的过滤条件。用户可以在起始点、目的点和边使用`WHERE`子句，还可以结合`AND`、`OR`、`NOT`、`XOR`一起使用。详情参见[WHERE](../8.clauses-and-options/where.md)。
 
   !!! Note
 
         遍历多个Edge type时，`WHERE`子句有一些限制。例如不支持`WHERE edge1.prop1 > edge2.prop2`。
 
-- `YIELD [DISTINCT] <return_list>`：定义需要返回的输出。` <return_list>`建议使用[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] <return_list>`：定义需要返回的输出。` <return_list>`建议使用[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_list>`：用于在结果集中取样。详情参见[SAMPLE](../8.clauses-and-options/sample.md)。
 
-- `ORDER BY`：指定输出结果的排序规则。详情请参见[ORDER BY](../8.clauses-and-options/order-by.md)。
+- `LIMIT <limit_list>`：用于在遍历过程中逐步限制输出数量。详情参见[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  [<offset>,] <number_rows>]`：限制输出结果的行数。详情参见[LIMIT](../8.clauses-and-options/limit.md)。
 
 ## 示例
 

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
+<go_statement> SAMPLE <sample_list>;
+```
+
+`sample_list`是一个列表，列表中的元素必须为自然数，且元素数量必须与`GO`语句中的`STEPS`的最大数相同。下文以`GO 1 TO 3 STEPS FROM "A" OVER * SAMPLE <sample_list>`为例详细介绍`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  |
++---------------------+-----+
+```

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