补充实体直查功能文档

nebula-contrib · Nov 3, 2024 · b6131a4 · b6131a4
1 parent 1d4e1cb
commit b6131a4
Show file tree

Hide file tree

Showing 10 changed files with 460 additions and 8 deletions.
diff --git a/README-CN.md b/README-CN.md
@@ -337,6 +337,131 @@ public class PersonServiceImpl {
 
 ```
 
+### 使用提供的方法进行实体直查（OGM）
+
+该查询方式是从实体对象出发完成数据直查。使用前要定义实体类，作为查询参数。
+
+#### 实体类
+
+##### 点实体
+
+- 继承`GraphBaseVertex`类标识是点实体
+- `@Tag`的name属性注明点实体的Tag
+- `@GraphId`的type属性注明点实体id的类型（可选）
+
+```java
+@Tag(name = "player")
+public class Player extends GraphBaseVertex {
+
+  @GraphId(type = IdType.STRING)
+  private String id;
+
+  private String name;
+
+  private Integer age;
+
+  ...
+
+}
+```
+
+具体可参考`ye.weicheng.ngbatis.demo.pojo.edge`包下的点实体示例。
+
+##### 边实体
+
+- 继承`GraphBaseEdge`类标识是边实体
+- `@EdgeType`的name属性注明边实体的类型
+- `@Id`（可选，如果两个节点之间同一类型边的唯一性由源节点id和目标节点id共同决定，可以不加当前属性）
+- `@SrcId`（可选，如果不需要获取关系的源节点id，可以不加当前属性）
+- `@DstId`（可选，如果不需要获取关系的目标节点id，可以不加当前属性）
+
+```java
+@EdgeType(name = "serve")
+public class Serve extends GraphBaseEdge {
+
+  @Id 
+  private Long rank;
+
+  @SrcId 
+  private String srcId;
+
+  @DstId 
+  private String dstId;
+
+  @Column(name = "start_year")
+  private Integer startYear;
+  @Column(name = "end_year")
+  private Integer endYear;
+
+  ...
+}
+```
+
+具体可参考`ye.weicheng.ngbatis.demo.pojo.vertex`包下的边实体示例。
+
+#### 现提供的方法
+
+##### 关于点实体
+
+| API                                                          | 用法说明                                                     |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| queryIdsByProperties()                                       | 查询特定Tag或者属性的点Id集合                                |
+| queryVertexById()                                            | 查询特定点Id的单个点                                         |
+| queryVertexByTag()                                           | 查询特定Tag的点集合                                          |
+| queryVertexByProperties()                                    | 查询特定属性的点集合                                         |
+| queryAllAdjacentVertex(Class<?>... edgeClass)                | 查询特定点的所有邻点集合，可指定一个或多个连接两点的边类型   |
+| queryIncomingAdjacentVertex(Class<?>... edgeClass)           | 查询特定点入边方向的邻点集合，可指定一个或多个连接两点的边类型 |
+| queryOutgoingAdjacentVertex(Class<?>... edgeClass)           | 查询特定点出边方向的邻点集合，可指定一个或多个连接两点的边类型 |
+| queryNeighborIdsWithHopById(int m, int n, Class<?>... edgeClass) | 查询特定点指定跳数内的点Id集合，可指定一个或多个连接两点的边类型 |
+| queryConnectedEdgesById(Direction direction)                 | 查询特定点关联的所有边集合，可指定边的方向和类型             |
+| queryPathFromVertex(Direction direction)                     | 查询特定点关联的所有路径集合，可指定边的方向                 |
+| queryFixedLengthPathFromVertex(Integer maxHop, Direction direction, Class<?>... edgeClass) | 查询特定点出发的定长路径集合，可指定最大步数、边的方向、边的类型 |
+| queryVariableLengthPathFromVertex(Integer minHop, Integer maxHop,   Direction direction, Class<?>... edgeClass) | 查询特定点出发的变长路径集合，可指定最小步数、最大步数、边的方向、边的类型 |
+| queryShortestPathFromSrcAndDst(Integer maxHop,   Direction direction, T v2) | 查询特定点出发的任意一条最短路径，可指定步数、边的方向、终点实体 |
+| queryAllShortestPathsFromSrcAndDst(Integer maxHop,   Direction direction, T v2) | 查询从该点出发的所有最短路径集合，可指定步数、边的方向、终点实体 |
+| queryVertexCountByTag()                                      | 查询特定Tag的点的数量                                        |
+
+具体实现见`org.nebula.contrib.ngbatis.base`包下的点实体基类`GraphBaseVertex`。
+
+##### 关于边实体
+
+| API                                                          | 用法说明                   |
+| ------------------------------------------------------------ | -------------------------- |
+| queryEdgeByType(Direction direction)                         | 查询特定类型、方向的边集合 |
+| queryEdgeWithSrcAndDstByProperties(T srcVertex, Direction direction, T dstVertex) | 查询特定属性的边集合       |
+| queryEdgePropertiesBySrcAndDstId()                           | 查询特定始终点id的边集合   |
+| queryEdgeCountByType()                                       | 查询特定Type的边的数量     |
+
+具体实现见`org.nebula.contrib.ngbatis.base`包下的边实体基类`GraphBaseEdge`。
+
+#### 使用示例
+
+```java
+@Test
+public void testVertex(){
+    Player srcPlayer = new Player();
+    //查询所有符合条件 name = "Vince Carter" 的Player顶点
+    srcPlayer.setName("Vince Carter");
+    List<Player> vertices = player.queryVertexByProperties();
+}
+
+@Test
+public void testEdge(){
+    Serve serve = new Serve();
+
+    //查询起点id为player100，终点id为team204的Serve边
+    serve.setSrcId("player100");
+    serve.setDstId("team204");
+    Serve edge = serve.queryEdgeWithSrcAndDstByProperties();
+
+    //查询Serve类型、方向为”->“的边
+    List<Serve> edges = serve.queryEdgeByType(Direction.NULL);
+
+}
+```
+
+具体每个直查方法的使用示例可参考ngbatis-demo里的NebulaGraphBasicTests测试类。
+
 ## 特别声明的上游项目
 
 - [beetl](https://gitee.com/xiandafu/beetl), BSD-3, Beetl模板引擎是项目很重要的组成部分(as is).

diff --git a/README.md b/README.md
@@ -339,6 +339,128 @@ public class PersonServiceImpl {
 
 ```
 
+### c. Entity Direct Search
+
+#### c.1 Entity class
+
+##### c.1.1 Vertex Entity 
+
+- Extends the `GraphBaseVertex` class identifier as a vertex entity
+- The name attribute of `@Tag` indicates the Tag of the vertex entity
+- The type attribute of `@GraphId` indicates the type of the point entity id (optional)
+
+```java
+@Tag(name = "player")
+public class Player extends GraphBaseVertex {
+
+  @GraphId(type = IdType.STRING)
+  private String id;
+
+  private String name;
+
+  private Integer age;
+
+  ...
+
+}
+```
+
+Specific reference `ye.weicheng.ngbatis.demo.pojo.vertex` vertex entities under the package sample.
+
+##### c.1.2 Edge Entity 
+
+- Extends the `GraphBaseEdge` class to identify edge entities
+
+- The name attribute of `@EdgeType` indicates the type of the edge entity
+
+- `@Id` (Optional, if the uniqueness of an edge of the same type between two nodes is determined by the source node id and the destination node id, the current attribute can be omitted)
+- `@SrcId` (optional, if you do not need to obtain the source node id of the relationship, you can omit the current attribute)
+- `@DstId` (Optional, if you do not need to get the target node id of the relationship, you can omit the current attribute)
+
+```java
+@EdgeType(name = "serve")
+public class Serve extends GraphBaseEdge {
+
+  @Id 
+  private Long rank;
+
+  @SrcId 
+  private String srcId;
+
+  @DstId 
+  private String dstId;
+
+  @Column(name = "start_year")
+  private Integer startYear;
+  @Column(name = "end_year")
+  private Integer endYear;
+
+  ...
+}
+```
+
+Specific reference `ye.weicheng.ngbatis.demo.pojo.edge` edge entities under the package sample.
+
+#### c.2 The method is now provided
+
+##### c.2.1 About vertex entity
+
+| API                                                          | 用法说明                                                     |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| queryIdsByProperties()                                       | Query a collection of vertex ids for a particular Tag or attribute |
+| queryVertexById()                                            | Query a single vertex for a specific vertex Id               |
+| queryVertexByTag()                                           | Query a collection of vertices  for a specific Tag           |
+| queryVertexByProperties()                                    | Query a collection of vertexes for a specific property       |
+| queryAllAdjacentVertex(Class<?>... edgeClass)                | Query a collection of all neighboring vertexes of a particular vertex, specifying one or more edge types that connect the two vertexes |
+| queryIncomingAdjacentVertex(Class<?>... edgeClass)           | Query the set of adjacent vertexes in the direction of the incoming edge of a particular vertex, specifying one or more edge types that connect two vertexes |
+| queryOutgoingAdjacentVertex(Class<?>... edgeClass)           | Query the set of adjacent vertexes in the direction of the edge of a particular vertex, specifying one or more edge types that connect two vertexes |
+| queryNeighborIdsWithHopById(int m, int n, Class<?>... edgeClass) | Query a collection of vertex ids within a specified number of hops for a particular vertex, specifying one or more edge types that connect two vertexes |
+| queryConnectedEdgesById(Direction direction)                 | Query the set of all edges associated with a particular vertex, specifying the direction and type of the edge |
+| queryPathFromVertex(Direction direction)                     | Query the collection of all paths associated with a particular vertex, specifying the direction of the edge |
+| queryFixedLengthPathFromVertex(Integer maxHop, Direction direction, Class<?>... edgeClass) | Query a set of fixed-length paths from a specific vertex, specifying the maximum number of steps, the direction of the edge, and the type of the edge |
+| queryVariableLengthPathFromVertex(Integer minHop, Integer maxHop,   Direction direction, Class<?>... edgeClass) | Query a set of variable-length paths from a specific vertex, specifying the minimum number of steps, the maximum number of steps, the direction of the edge, and the type of the edge |
+| queryShortestPathFromSrcAndDst(Integer maxHop,   Direction direction, T v2) | Query any shortest path from a specific vertex, specifying the number of steps, the direction of the edge, and the end vertex entity |
+| queryAllShortestPathsFromSrcAndDst(Integer maxHop,   Direction direction, T v2) | Query the set of all shortest paths from this vertex, specifying the number of steps, the direction of the edge, and the end vertex entity |
+| queryVertexCountByTag()                                      | Query the number of vertexes for a specific Tag              |
+
+For specific implementation, see the point entity base class `GraphBaseVertex` under the `org.nebula.contrib.ngbatis.base` package.
+
+##### c.2.2 About edge entity
+
+| API                                                          | 用法说明                                              |
+| ------------------------------------------------------------ | ----------------------------------------------------- |
+| queryEdgeByType(Direction direction)                         | Query a set of edges of a specific type and direction |
+| queryEdgeWithSrcAndDstByProperties(T srcVertex, Direction direction, T dstVertex) | Query a set of edges for a particular property        |
+| queryEdgePropertiesBySrcAndDstId()                           | Query a set of edges for a specific always vertex id  |
+| queryEdgeCountByType()                                       | Query the number of edges for a specific Type         |
+
+For specific implementation, see the point entity base class `GraphBaseEdge` under the `org.nebula.contrib.ngbatis.base` package.
+
+#### c.3 test
+
+```java
+@Test
+public void testVertex(){
+    Player srcPlayer = new Player();
+    //Query all Player vertices that meet the condition name = "Vince Carter"
+    srcPlayer.setName("Vince Carter");
+    List<Player> vertices = player.queryVertexByProperties();
+}
+
+@Test
+public void testEdge(){
+    Serve serve = new Serve();
+    //Query the Server edge whose starting point ID is player100 and the end point ID is team204.
+    serve.setSrcId("player100");
+    serve.setDstId("team204");
+    Serve edge = serve.queryEdgeWithSrcAndDstByProperties();
+    //Query the edges of Serve type and direction "->"
+    List<Serve> edges = serve.queryEdgeByType(Direction.NULL);
+}
+```
+
+For specific usage examples of each direct inspection method, please refer to the `NebulaGraphBasicTests` test class in ngbatis-demo.
+
 ## Upstream projects
 
 - [beetl](https://gitee.com/xiandafu/beetl), BSD-3, we proudly use the beetl template language as our template engine, which is consumed in binary package(as is).

diff --git a/docs/en/md/dev-example/entity-query.md b/docs/en/md/dev-example/entity-query.md
@@ -0,0 +1,77 @@
+# Entity Direct Query
+Specific use NebulaGraph official [Example data Basketballplayer](https://docs.nebula-graph.io/3.8.0/3.ngql-guide/1.nGQL-overview/1.overview/#example_data_basketballplayer)
+
+## Custom vertex or edge entities
+
+### Vertex Entity
+- Extends the `GraphBaseVertex` class identifier as a vertex entity
+- The name attribute of `@Tag` indicates the Tag of the vertex entity
+- The type attribute of `@GraphId` indicates the type of the point entity id (optional)
+```java
+@Tag(name = "player")
+public class Player extends GraphBaseVertex {
+
+  @GraphId(type = IdType.STRING)
+  private String id;
+
+  private String name;
+
+  private Integer age;
+
+  ...
+
+}
+```
+### Edge Entity
+- Extends the `GraphBaseEdge` class to identify edge entities
+
+- The name attribute of `@EdgeType` indicates the type of the edge entity
+
+- `@Id` (Optional, if the uniqueness of an edge of the same type between two nodes is determined by the source node id and the destination node id, the current attribute can be omitted)
+- `@SrcId` (optional, if you do not need to obtain the source node id of the relationship, you can omit the current attribute)
+- `@DstId` (Optional, if you do not need to get the target node id of the relationship, you can omit the current attribute)
+```java
+@EdgeType(name = "serve")
+public class Serve extends GraphBaseEdge {
+
+  @Id 
+  private Long rank;
+
+  @SrcId 
+  private String srcId;
+
+  @DstId 
+  private String dstId;
+
+  @Column(name = "start_year")
+  private Integer startYear;
+
+  @Column(name = "end_year")
+  private Integer endYear;
+
+  ...
+}
+```
+
+## Usage Example
+
+```java
+@Test
+public void testVertex(){
+  Player srcPlayer = new Player();
+  //Query all Player vertices that meet the condition name = "Vince Carter"
+  srcPlayer.setName("Vince Carter");
+  List<Player> vertices = player.queryVertexByProperties();
+}
+
+@Test
+public void testEdge(){
+  Serve serve = new Serve();
+  //Query the Server edge whose starting point ID is player100 and the end point ID is team204.
+  serve.setSrcId("player100");
+  serve.setDstId("team204");
+  Serve edge = serve.queryEdgeWithSrcAndDstByProperties();
+  //Query the edges of Serve type and direction "->"
+  List<Serve> edges = serve.queryEdgeByType(Direction.NULL);
+}
+```
diff --git a/docs/en/md/dev-example/prepare.md b/docs/en/md/dev-example/prepare.md
@@ -6,7 +6,8 @@ Ngbatis provides two ways for developers to access nebula.
 
 - Close to Mybatis-plus, providing a basic `DAO` to be extends, unnecessary to write any `nGQL` to operate single table, include vertex and edge. (See [By Basic DAO](./dao-basic) for more details)
 - Close to Mybatis, supporting developers to write complex `nGQL` or `Cypher` to finish read or write data. (See [By Custom nGQL](./custom-crud) for more details)
-
+- Based on entity objects, directly call the provided query method to complete direct data inspection. (See [Entity Direct Query](./entity-query.md) for details. You can skip the following preparations using this method)
+
 Take  `Person` 与 `Like` as examples.
 
 ## Create Schema in Nebula (refer [CREATE TAG](https://docs.nebula-graph.com.cn/3.1.0/3.ngql-guide/10.tag-statements/1.create-tag/)、[CREATE EDGE](https://docs.nebula-graph.com.cn/3.1.0/3.ngql-guide/11.edge-type-statements/1.create-edge/)、[CREATE INDEX](https://docs.nebula-graph.com.cn/3.1.0/3.ngql-guide/14.native-index-statements/1.create-native-index/))

diff --git a/docs/en/md/quick-start/about.md b/docs/en/md/quick-start/about.md
@@ -5,7 +5,8 @@
 
 ## How to position ngbatis
 
-**NGBATIS**  is a database ORM framework base [Nebula Graph](https://github.com/vesoft-inc/nebula) + springboot. Take advantage of [mybatis'](https://github.com/mybatis/mybatis-3) usage habits to develop. Including some frequently-used  operation in single table and vertex-edge, like [mybatis-plus](https://github.com/baomidou/mybatis-plus).
+**NGBATIS**  is a database ORM framework base [Nebula Graph](https://github.com/vesoft-inc/nebula) + springboot. Take advantage of [mybatis'](https://github.com/mybatis/mybatis-3) usage habits to develop. Including some frequently-used  operation in single table and vertex-edge, like [mybatis-plus](https://github.com/baomidou/mybatis-plus).And also provides graph-specific entity-relationship basic query operation methods.
+
 If you prefer JPA, [graph-ocean](https://github.com/nebula-contrib/graph-ocean) is a good choice.
 
 > If you don't have your own Nebula Graph Database, please arrange it for yourself.  [Lucky Gate](https://docs.nebula-graph.com.cn/3.2.0/4.deployment-and-installation/2.compile-and-install-nebula-graph/3.deploy-nebula-graph-with-docker-compose/)