Reorg prop reference content (#240) (#2426)

* reorg-prop-reference-content * Update 3.property-reference.md * Update 3.property-reference.md * Update 3.property-reference.md * add en doc * changes * Update docs-2.0-en/3.ngql-guide/4.variable-and-composite-queries/3.property-reference.md * Update docs-2.0-en/3.ngql-guide/4.variable-and-composite-queries/3.property-reference.md * Update docs-2.0-en/3.ngql-guide/4.variable-and-composite-queries/3.property-reference.md * commentfix * Update 3.property-reference.md --------- Co-authored-by: Chris Chen <[email protected]>
vesoft-inc · Jan 12, 2024 · e9e24a8 · e9e24a8
1 parent 034f459
commit e9e24a8
Show file tree

Hide file tree

Showing 5 changed files with 154 additions and 169 deletions.
diff --git a/docs-2.0-en/3.ngql-guide/4.variable-and-composite-queries/3.property-reference.md b/docs-2.0-en/3.ngql-guide/4.variable-and-composite-queries/3.property-reference.md
@@ -1,63 +1,59 @@
-# Property reference
+# Reference to properties
 
-You can refer to the properties of a vertex or an edge in `WHERE` and `YIELD` syntax.
+nGQL provides property references to allow you to refer to the properties of the source vertex, the destination vertex, and the edge in the `GO` statement, and to refer to the output results of the statement in composite queries. This topic describes how to use these property references in nGQL.
 
 !!! note
 
      This function applies to native nGQL only.
 
-## Property reference for vertex
-
-### For source vertex
-
-```ngql
-$^.<tag_name>.<prop_name>
-```
+## Property references for vertexes
 
 | Parameter   | Description                                       |
 | :---------- | :-----------------                                |
-| `$^`        | is used to get the property of the source vertex. |
-| `tag_name`  | is the tag name of the vertex.                    |
-| `prop_name` | specifies the property name.                      |
+| `$^`        | Used to get the property of the source vertex. |
+| `$$`        | Used to get the property of the destination vertex. |
 
-### For destination vertex
+### Property reference syntax
 
 ```ngql
-$$.<tag_name>.<prop_name>
+$^.<tag_name>.<prop_name>  # Source vertex property reference
+$$.<tag_name>.<prop_name>   # Destination vertex property reference
 ```
 
-| Parameter   | Description                                            |
-| :---------- | :-----------------                                     |
-| `$$`        | is used to get the property of the destination vertex. |
-| `tag_name`  | is the tag name of the vertex.                         |
-| `prop_name` | specifies the property name.                           |
+- `tag_name`: The tag name of the vertex.
+- `prop_name`: The property name within the tag.
+
+## Property references for edges
+
+| Parameter   | Description                       |
+| :---------- | :------------------               |
+| `_src`      | The source vertex ID of the edge      |
+| `_dst`      | The destination vertex ID of the edge |
+| `_type`     | The internal encoding of edge types that uses sign to indicate direction. <br/>Positive numbers represent forward edges, while negative numbers represent backward edges.                        |
+| `_rank`     | The rank value for the edge       |
 
-## Property reference for edge
+### Property reference syntax
 
-### For user-defined edge property
+nGQL allows you to reference edge properties, including user-defined edge properties and four built-in edge properties.
 
 ```ngql
-<edge_type>.<prop_name>
+<edge_type>.<prop_name>  # User-defined edge property reference
+<edge_type>._src|_dst|_type|_rank  # Built-in edge property reference
 ```
 
-| Parameter   | Description                                   |
-| :---------- | :------------------                           |
-| `edge_type` | is the edge type of the edge.                 |
-| `prop_name` | specifies the property name of the edge type. |
+- `edge_type`: The edge type.
+- `prop_name`: The property name within the edge type.
 
-### For built-in properties
-
-Apart from the user-defined edge property, there are four built-in properties in each edge:
+## Property references for composite queries
 
 | Parameter   | Description                       |
 | :---------- | :------------------               |
-| `_src`      | source vertex ID of the edge      |
-| `_dst`      | destination vertex ID of the edge |
-| `_type`     | edge type                         |
-| `_rank`     | the rank value for the edge       |
+| `$-`        | Used to get the output results of the statement before the pipe in the composite query. For more information, see [Pipe](4.pipe.md). |
 
 ## Examples
 
+### Use property references for vertexes
+
 The following query returns the `name` property of the `player` tag on the source vertex and the `age` property of the `player` tag on the destination vertex.
 
 ```ngql
@@ -70,6 +66,19 @@ nebula> GO FROM "player100" OVER follow YIELD $^.player.name AS startName, $$.pl
 +--------------+--------+
 ```
 
+!!! compatibility "Legacy version compatibility"
+
+    Starting from {{nebula.name}} 2.6.0, [Schema-related functions](../6.functions-and-expressions/4.schema.md) are supported. The preceding example can be rewritten as follows in {{nebula.name}} {{ nebula.release}} to produce the same results: 
+
+    ```ngql
+    GO FROM "player100" OVER follow YIELD properties($^).name AS startName, properties($$).age AS endAge;
+    ```
+
+    {{nebula.name}} {{ nebula.release}} is compatible with both new and old syntax.
+
+
+### Use property references for edges
+
 The following query returns the `degree` property of the edge type `follow`.
 
 ```ngql
@@ -95,12 +104,36 @@ nebula> GO FROM "player100" OVER follow YIELD follow._src, follow._dst, follow._
 
 !!! compatibility "Legacy version compatibility"
 
-    NebulaGraph 2.6.0 and later versions support the new [Schema-related functions](../6.functions-and-expressions/4.schema.md). Similar statements as the above examples are written as follows in {{ nebula.release}}.
+    Starting from {{nebula.name}} 2.6.0, [Schema-related functions](../6.functions-and-expressions/4.schema.md) are supported. The preceding example can be rewritten as follows in {{nebula.name}} {{ nebula.release}} to produce the same results: 
 
     ```ngql
-    GO FROM "player100" OVER follow YIELD properties($^).name AS startName, properties($$).age AS endAge;
     GO FROM "player100" OVER follow YIELD properties(edge).degree;
     GO FROM "player100" OVER follow YIELD src(edge), dst(edge), type(edge), rank(edge);
     ```
 
-    In {{ nebula.release}}, NebulaGraph is still compatible with the old syntax.
+    {{nebula.name}} {{ nebula.release}} is compatible with both new and old syntax.
+
+
+### Use property references for composite queries
+
+
+The following composite query performs the following actions:
+
+1. Uses the property reference `$-.id` to get the results of the statement `GO FROM "player100" OVER follow YIELD dst(edge) AS id`, which returns the destination vertex ID of the `follow` edge type.
+2. Uses the `properties($^)` function to get the name property of the player tag on the source vertex of the `serve` edge type.
+3. Uses the `properties($$)` function to get the name property of the team tag on the destination vertex of the `serve` edge type.
+
+
+```ngql
+nebula> GO FROM "player100" OVER follow \
+        YIELD dst(edge) AS id | \
+        GO FROM $-.id OVER serve \
+        YIELD properties($^).name AS Player, properties($$).name AS Team;
++-----------------+-----------+
+| Player          | Team      |
++-----------------+-----------+
+| "Tony Parker"   | "Spurs"   |
+| "Tony Parker"   | "Hornets" |
+| "Manu Ginobili" | "Spurs"   |
++-----------------+-----------+
+```
diff --git a/docs-2.0-en/3.ngql-guide/5.operators/5.property-reference.md b/docs-2.0-en/3.ngql-guide/5.operators/5.property-reference.md
diff --git a/docs-2.0-zh/3.ngql-guide/4.variable-and-composite-queries/3.property-reference.md b/docs-2.0-zh/3.ngql-guide/4.variable-and-composite-queries/3.property-reference.md
@@ -1,63 +1,60 @@
 # 引用属性
 
-用户可以在`WHERE`和`YIELD`子句中引用点或边的属性。
+nGQL 提供属性引用符以允许用户在`GO`语句中引用起始点、目的点、边的属性，以及引用复合查询的输出结果。本文将详细介绍如何在 nGQL 中使用这些属性引用符。
 
-!!! note
+## openCypher 兼容性
 
-    本功能仅适用于原生 nGQL 的 GO 语句。
+属性引用符仅适用于原生 nGQL。
 
-## 引用点的属性
+## 点属性引用符
 
-### 起始点
+|引用符|说明|
+|:---|:---|
+|`$^`|引用起始点。|
+|`$$`|引用目的点。|
+
+### 引用语法
 
 ```ngql
-$^.<tag_name>.<prop_name>
+$^.<tag_name>.<prop_name>  # 起始点属性引用
+$$.<tag_name>.<prop_name>   # 目的点属性引用
 ```
 
-|参数|说明|
-|:----------|:-----------------|
-|`$^`       |起始点       |
-|`tag_name` |点的 Tag 名称   |
-|`prop_name`|Tag 内的属性名称|
+- `tag_name`：点的 Tag 名称。
+- `prop_name`：Tag 内的属性名称。
 
-### 目的点
+## 边属性引用符
 
-```ngql
-$$.<tag_name>.<prop_name>
-```
-
-|参数|说明|
-|:----------|:-----------------|
-|`$$`       |目的点        |
-|`tag_name` |点的 Tag 名称   |
-|`prop_name`|Tag 内的属性名称|
+|引用符|说明|
+|:---|:---|
+|`_src`|边的起始点           |
+|`_dst`|边的目的点|
+|`_type`|边的类型内部编码，正负号表示方向：正数为正向边，负数为逆向边|
+|`_rank`|边的 rank 值|
 
-## 引用边的属性
+### 引用语法
 
-### 引用自定义的边属性
+nGQL 允许用户引用边的属性，包括自定义的边属性和四种内置的边属性。
 
 ```ngql
-<edge_type>.<prop_name>
+<edge_type>.<prop_name>  # 自定义边属性引用
+<edge_type>._src|_dst|_type|_rank  # 内置边属性引用
 ```
 
-|参数|说明|
-|:----------|:------------------|
-|`edge_type`|Edge type            |
-|`prop_name` |Edge type 的属性名称|
+- `edge_type`：Edge type。
+- `prop_name`：Edge type 的属性名称。
 
-### 引用内置的边属性
+## 复合查询中的引用符
 
-除了自定义的边属性，每条边还有如下四种内置属性：
+|引用符|说明|
+|:---|:---|
+|`$-`|引用复合查询中管道符之前的语句输出结果。更多信息请参见[管道符](4.pipe.md)。|
 
-|参数|说明|
-|:----------|:------------------|
-|`_src`|边的起始点           |
-|`_dst`|边的目的点|
-|`_type`|边的类型内部编码，正负号表示方向：正数为正向边，负数为逆向边|
-|`_rank`|边的 rank 值|
 
 ## 示例
 
+### 使用点属性引用符
+
 ```ngql
 # 返回起始点的 Tag player 的 name 属性值和目的点的 Tag player 的 age 属性值。
 nebula> GO FROM "player100" OVER follow YIELD $^.player.name AS startName, $$.player.age AS endAge;
@@ -67,6 +64,21 @@ nebula> GO FROM "player100" OVER follow YIELD $^.player.name AS startName, $$.pl
 | "Tim Duncan" | 36     |
 | "Tim Duncan" | 41     |
 +--------------+--------+
+```
+
+!!! compatibility "历史版本兼容性"
+
+    从{{nebula.name}} 2.6.0 起支持了新的 [Schema 相关函数](../6.functions-and-expressions/4.schema.md)。以上示例在{{nebula.name}} {{ nebula.release}} 中的近似写法如下：
+
+    ```ngql
+    GO FROM "player100" OVER follow YIELD properties($^).name AS startName, properties($$).age AS endAge;
+    ```
+
+     {{nebula.name}} {{ nebula.release}} 兼容新旧语法。
+
+### 使用边属性引用符
+
+```ngql
 
 # 返回 Edge type follow 的 degree 属性值。
 nebula> GO FROM "player100" OVER follow YIELD follow.degree;
@@ -91,9 +103,33 @@ nebula> GO FROM "player100" OVER follow YIELD follow._src, follow._dst, follow._
     从 {{nebula.name}} 2.6.0 起支持了新的 [Schema 相关函数](../6.functions-and-expressions/4.schema.md)。以上示例在 {{nebula.name}} {{ nebula.release}} 中的近似写法如下：
 
     ```ngql
-    GO FROM "player100" OVER follow YIELD properties($^).name AS startName, properties($$).age AS endAge;
     GO FROM "player100" OVER follow YIELD properties(edge).degree;
     GO FROM "player100" OVER follow YIELD src(edge), dst(edge), type(edge), rank(edge);
     ```
 
-    {{nebula.name}} {{ nebula.release}} 兼容新旧语法。
+     {{nebula.name}} {{ nebula.release}} 兼容新旧语法。
+
+### 复合查询中使用属性引用符
+
+以下复合查询语句示例执行操作如下：
+
+1. 使用`$-.id`引用管道符前面的`GO FROM "player100" OVER follow YIELD dst(edge) AS id`语句的结果，即返回`follow`边类型的目的点 ID。
+2. 使用`properties($^)`函数获取`serve`类型边上起始点的球员的`name`属性。
+3. 使用`properties($$)`函数获取`serve`类型边上目的点的团队的`name`属性。
+
+
+```ngql
+nebula> GO FROM "player100" OVER follow \
+        YIELD dst(edge) AS id | \
+        GO FROM $-.id OVER serve \
+        YIELD properties($^).name AS Player, properties($$).name AS Team;
++-----------------+-----------+
+| Player          | Team      |
++-----------------+-----------+
+| "Tony Parker"   | "Spurs"   |
+| "Tony Parker"   | "Hornets" |
+| "Manu Ginobili" | "Spurs"   |
++-----------------+-----------+
+```
+
+
diff --git a/docs-2.0-zh/3.ngql-guide/5.operators/5.property-reference.md b/docs-2.0-zh/3.ngql-guide/5.operators/5.property-reference.md