diff --git a/docs-2.0/3.ngql-guide/8.clauses-and-options/limit.md b/docs-2.0/3.ngql-guide/8.clauses-and-options/limit.md index cb87e926de..6ba43ca33e 100644 --- a/docs-2.0/3.ngql-guide/8.clauses-and-options/limit.md +++ b/docs-2.0/3.ngql-guide/8.clauses-and-options/limit.md @@ -1,38 +1,55 @@ # LIMIT -`LIMIT`子句限制输出结果的行数。 +`LIMIT`子句限制输出结果的行数。`LIMIT`在原生nGQL语句和openCypher兼容语句中的用法有所不同。 -- 在原生nGQL中,必须使用管道符(|),可以忽略偏移量。 +- 在原生nGQL语句中,一般需要在`LIMIT`子句前使用管道符,可以直接在LIMIT语句后设置或者省略偏移量参数。 -- 在openCypher方式中,不允许使用管道符,可以使用`SKIP`指明偏移量。 +- 在openCypher兼容语句中,不允许在`LIMIT`子句前使用管道符,可以使用`SKIP`指明偏移量。 !!! Note 在原生nGQL或openCypher方式中使用`LIMIT`时,使用`ORDER BY`子句限制输出顺序非常重要,否则会输出一个不可预知的子集。 -## 原生nGQL语法 +!!! compatibility "历史版本兼容性" -在原生nGQL中,`LIMIT`的工作原理与`SQL`相同,必须和管道符一起使用。`LIMIT`子句接收一个或两个参数。参数的值必须是非负整数。 + Nebula Graph 2.6.0中,`GO`语句支持了新的`LIMIT`语法。部分`LIMIT`相关的算子支持计算下推。 + +## 原生nGQL语句中的LIMIT + +在原生nGQL中,`LIMIT`有通用语法和`GO`语句中的专属语法。 + +### 原生nGQL中的通用LIMIT语法 + +原生nGQL中的通用`LIMIT`语法与`SQL`中的`LIMIT`原理相同。`LIMIT`子句接收一个或两个参数,参数的值必须是非负整数,且必须用在管道符之后。语法和说明如下: ```ngql -YIELD -[| LIMIT [,] ]; +... | LIMIT [,] ; ``` |参数|说明| |:--|:--| -|`var`|排序的列或计算结果。| -|`offset_value`|偏移量,即定义从哪一行开始返回。索引从`0`开始。默认值为`0`,表示从第一行开始返回。| +|`offset`|偏移量,即定义从哪一行开始返回。索引从`0`开始。默认值为`0`,表示从第一行开始返回。| |`number_rows`|返回的总行数。| -### 示例 +示例: ```ngql -# 从排序结果中返回第2行开始的3行数据。 +# 从结果中返回最前面的3行数据。 +nebula> LOOKUP ON player |\ + LIMIT 3; ++-------------+ +| VertexID | ++-------------+ +| "player100" | +| "player101" | +| "player102" | ++-------------+ + +# 从排序后结果中返回第2行开始的3行数据。 nebula> GO FROM "player100" OVER follow REVERSELY \ - YIELD properties($$).name AS Friend, properties($$).age AS Age \ - | ORDER BY $-.Age, $-.Friend \ - | LIMIT 1, 3; + YIELD properties($$).name AS Friend, properties($$).age AS Age \| + ORDER BY $-.Age, $-.Friend \| + LIMIT 1, 3; +-------------------+-----+ | Friend | Age | +-------------------+-----+ @@ -44,17 +61,50 @@ nebula> GO FROM "player100" OVER follow REVERSELY \ +-------------------+-----+ ``` -## openCypher方式语法 +### GO语句中的LIMIT + +`GO`语句中的`LIMIT`除了支持原生nGQL中的通用语法外,还支持根据边限制输出结果数量。 + +语法: + +```ngql + LIMIT ; +``` + +`limit_list`是一个列表,列表中的元素必须为自然数,且元素数量必须与`GO`语句中的`STEPS`的最大数相同。下文以`GO 1 TO 3 STEPS FROM "A" OVER * LIMIT `为例详细介绍`LIMIT`的这种用法。 + +* 列表`limit_list`必须包含3个自然数元素,例如`GO 1 TO 3 STEPS FROM "A" OVER * LIMIT [1,2,4]`。 +* `LIMIT [1,2,4]`中的`1`表示系统在第一步时自动选择1条边继续遍历,`2`表示在第二步时选择2条边继续遍历,`4`表示在第三步时选择4条边继续遍历。 +* 因为`GO 1 TO 3 STEPS`表示返回第一到第三步的所有遍历结果,因此下图中所有红色边和它们的原点与目的点都会被这条`GO`语句匹配上,而黄色边表示`GO`语句遍历时没有选择的路径。如果不是`GO 1 TO 3 STEPS`而是`GO 3 STEPS`,则只会匹配上第三步的红色边和它们两端的点。 + +![LIMIT in GO](limit_in_go_1.png) + +在basketballplayer数据集中的执行示例如下: ```ngql -RETURN -[SKIP ] -[LIMIT ]; +nebula> GO 3 STEPS FROM "player100" \ + OVER * \ + YIELD properties($$).name AS NAME, properties($$).age AS Age \ + LIMIT [3,3,3]; ++-----------------+--------------+ +| NAME | Age | ++-----------------+--------------+ +| "Spurs" | UNKNOWN_PROP | +| "Tony Parker" | 36 | +| "Manu Ginobili" | 41 | ++-----------------+--------------+ +``` + +## openCypher兼容语句中的LIMIT + +在`MATCH`等openCypher兼容语句中使用LIMIT不需要加管道符。语法和说明如下: + +```ngql +... [SKIP ] [LIMIT ]; ``` |参数|说明| |:--|:--| -|`var`|排序的列或计算结果。| |`offset`|偏移量,即定义从哪一行开始返回。索引从`0`开始。默认值为`0`,表示从第一行开始返回。| |`number_rows`|返回的总行数量。| @@ -64,7 +114,9 @@ RETURN 两个整数组成的分数表达式会自动向下取整。例如`8/6`向下取整为1。 -### 示例 +### 单独使用LIMIT + +`LIMIT`可以单独使用,返回指定数量的结果。 ```ngql nebula> MATCH (v:player) RETURN v.name AS Name, v.age AS Age \ @@ -98,9 +150,9 @@ nebula> MATCH (v:player) RETURN v.name AS Name, v.age AS Age \ +-------------------------+-----+ ``` -### SKIP示例 +### 单独使用SKIP -用户可以单独使用`SKIP `设置偏移量,后面不需要添加`LIMIT `。 +`SKIP`可以单独使用,用于设置偏移量,返回指定位置之后的数据。 ```ngql nebula> MATCH (v:player{name:"Tim Duncan"}) --> (v2) \ @@ -124,7 +176,9 @@ nebula> MATCH (v:player{name:"Tim Duncan"}) --> (v2) \ +---------------+-----+ ``` -用户也可以同时使用`SKIP `和`LIMIT `,返回中间的部分数据。 +### 同时使用SKIP与LIMIT + +同时使用`SKIP`与`LIMIT`可以返回从指定位置开始的指定数量的数据。 ```ngql nebula> MATCH (v:player{name:"Tim Duncan"}) --> (v2) \ @@ -136,6 +190,7 @@ nebula> MATCH (v:player{name:"Tim Duncan"}) --> (v2) \ | "Manu Ginobili" | 41 | +-----------------+-----+ ``` +