This is an automated email from the ASF dual-hosted git repository. jermy pushed a commit to branch client-translate in repository https://gitbox.apache.org/repos/asf/incubator-hugegraph-doc.git
commit e26f696974ac295d220e73d9fd91125bf1ba45c1 Author: Jermy Li <[email protected]> AuthorDate: Thu May 5 16:58:17 2022 +0800 translate client api to English --- content/en/docs/clients/hugegraph-client.md | 174 ++++++++++++++-------------- 1 file changed, 86 insertions(+), 88 deletions(-) diff --git a/content/en/docs/clients/hugegraph-client.md b/content/en/docs/clients/hugegraph-client.md index 83f30cc..1040e2b 100644 --- a/content/en/docs/clients/hugegraph-client.md +++ b/content/en/docs/clients/hugegraph-client.md @@ -4,64 +4,64 @@ linkTitle: "HugeGraph Java Client" weight: 2 --- -本文的代码都是`java`语言写的，但其风格与`gremlin(groovy)`是非常类似的。用户只需要把代码中的变量声明替换成`def`或直接去掉， -就能将`java`代码转变为`groovy`；另外就是每一行语句最后可以不加分号，`groovy`认为一行就是一条语句。 -用户在`HugeGraph-Studio`中编写的`gremlin(groovy)`可以参考本文的`java`代码，下面会举出几个例子。 +The code in this document is written in `java`, but its style is very similar to `gremlin(groovy)`. The user only needs to replace the variable declaration in the code with `def` or remove it directly, +You can convert `java` code into `groovy`; in addition, each line of statement can be without a semicolon at the end, `groovy` considers a line to be a statement. +The `gremlin(groovy)` written by the user in `HugeGraph-Studio` can refer to the `java` code in this document, and some examples will be given below. ### 1 HugeGraph-Client -HugeGraph-Client 是操作 graph 的总入口，用户必须先创建出 HugeGraph-Client 对象，与 HugeGraph-Server 建立连接（伪连接）后，才能获取到 schema、graph 以及 gremlin 的操作入口对象。 +HugeGraph-Client is the general entry for operating graph. Users must first create a HugeGraph-Client object and establish a connection (pseudo connection) with HugeGraph-Server before they can obtain the operation entry objects of schema, graph and gremlin. -目前 HugeGraph-Client 只允许连接服务端已存在的图，无法自定义图进行创建。其创建方法如下： +Currently, HugeGraph-Client only allows connections to existing graphs on the server, and cannot create custom graphs. Its creation method is as follows: ```java -// HugeGraphServer地址："http://localhost:8080"; -// 图的名称："hugegraph" +// HugeGraphServer address: "http://localhost:8080"; +// Graph Name: "hugegraph" HugeClient hugeClient = HugeClient.builder("http://localhost:8080";, "hugegraph") - .configTimeout(20) // 默认 20s 超时 - .configUser("**", "**") // 默认未开启用户权限 + .configTimeout(20) // 20s timeout + .configUser("**", "**") // enable auth .build(); ``` -上述创建 HugeClient 的过程如果失败会抛出异常，用户需要try-catch。如果成功则继续获取 schema、graph 以及 gremlin 的 manager。 +If the above process of creating HugeClient fails, an exception will be thrown, and the user needs to use try-catch. If successful, continue to get schema, graph and gremlin manager. -在`HugeGraph - Hubble / Studio`中通过`gremlin`来操作时，不需要使用`HugeClient`，可以忽略。 +When operating through `gremlin` in `HugeGraph-Hubble`(or `HugeGraph-Studio`), `HugeClient` is not required and can be ignored. -### 2 元数据 +### 2 Schema #### 2.1 SchemaManager -SchemaManager 用于管理 HugeGraph 中的四种元数据，分别是PropertyKey（属性类型）、VertexLabel（顶点类型）、EdgeLabel（边类型）和 IndexLabel（索引标签）。在定义元数据信息之前必须先创建 SchemaManager 对象。 +SchemaManager is used to manage four kinds of schema in HugeGraph, namely PropertyKey (property type), VertexLabel (vertex type), EdgeLabel (edge type) and IndexLabel (index label). A SchemaManager object can be created for schema information definition. -用户可使用如下方法获得SchemaManager对象： +The user can obtain the SchemaManager object using the following methods: ```java SchemaManager schema = hugeClient.schema() ``` -在`HugeGraph-Studio`中通过`gremlin`创建`schema`对象： +Create a `schema` object via `gremlin` in `HugeGraph-Hubble`: ```groovy schema = graph.schema() ``` -下面分别对三种元数据的定义过程进行介绍。 +The definition process of the 4 kinds of schema is described below. #### 2.2 PropertyKey -##### 2.2.1 接口及参数介绍 +##### 2.2.1 Interface and parameter introduction -PropertyKey 用来规范顶点和边的属性的约束，暂不支持定义属性的属性。 +PropertyKey is used to standardize the property constraints of vertices and edges, and properties of properties are not currently supported. -PropertyKey 允许定义的约束信息包括：name、datatype、cardinality、userdata，下面逐一介绍。 +The constraint information that PropertyKey allows to define includes: name, datatype, cardinality, and userdata, which are introduced one by one below. -- name: 属性的名字，用来区分不同的 PropertyKey，不允许有同名的属性； +- name: The name of the property, used to distinguish different PropertyKeys, PropertyKeys with the same name are not allowed. interface | param | must set ------------------------ | ----- | -------- propertyKey(String name) | name | y -- datatype：属性值类型，必须从下表中选择符合具体业务场景的一项显式设置； +- datatype: property value type, you must select an explicit setting from the following table that conforms to the specific business scenario: interface | Java Class ------------- | ---------- @@ -76,7 +76,7 @@ asDouble() | Double asFloat() | Float asLong() | Long -- cardinality：属性值是单值还是多值，多值的情况下又分为允许有重复值和不允许有重复值，该项默认为 single，如有必要可从下表中选择一项设置； +- cardinality: Whether the property value is single-valued or multi-valued, in the case of multi-valued, it is divided into allowing-duplicate values and not-allowing-duplicate values. This item is single by default. If necessary, you can select a setting from the following table: interface | cardinality | description ------------- | ----------- | ------------------------------------------- @@ -84,42 +84,42 @@ valueSingle() | single | single value valueList() | list | multi-values that allow duplicate value valueSet() | set | multi-values that not allow duplicate value -- userdata：用户可以自己添加一些约束或额外信息，然后自行检查传入的属性是否满足约束，或者必要的时候提取出额外信息 +- userdata: Users can add some constraints or additional information by themselves, and then check whether the incoming properties satisfy the constraints, or extract additional information when necessary: interface | description ---------------------------------- | ---------------------------------------------- userdata(String key, Object value) | The same key, the latter will cover the former -##### 2.2.2 创建 PropertyKey +##### 2.2.2 Create PropertyKey ```java schema.propertyKey("name").asText().valueSet().ifNotExist().create() ``` -在`HugeGraph-Studio`中通过`gremlin`创建上述`PropertyKey`对象的语法完全一致，如果用户没有定义出`schema`变量，应该这样写： +The syntax of creating the above `PropertyKey` object through `gremlin` in `HugeGraph-Hubble` is exactly the same. If the user does not define the `schema` variable, it should be written like this: ```groovy graph.schema().propertyKey("name").asText().valueSet().ifNotExist().create() ``` -以下的示例中，`gremlin`与`java`的语法完全一致，不再赘述。 +In the following examples, the syntax of `gremlin` and `java` is exactly the same, so we won't repeat them. -- ifNotExist()：为 create 添加判断机制，若当前 PropertyKey 已经存在则不再创建，否则创建该属性。若不添加判断，在 properkey 已存在的情况下会抛出异常信息，下同，不再赘述。 +- ifNotExist(): Add a judgment mechanism for create, if the current PropertyKey already exists, it will not be created, otherwise the property will be created. If no ifNotExist() is added, an exception will be thrown if a properkey with the same name already exists. The same as below, and will not be repeated there. -##### 2.2.3 删除 PropertyKey +##### 2.2.3 Delete PropertyKey ```java schema.propertyKey("name").remove() ``` -##### 2.2.4 查询 PropertyKey +##### 2.2.4 Query PropertyKey ```java -// 获取PropertyKey对象 +// Get PropertyKey schema.getPropertyKey("name") -// 获取PropertyKey属性 +// Get attributes of PropertyKey schema.getPropertyKey("name").cardinality() schema.getPropertyKey("name").dataType() schema.getPropertyKey("name").name() @@ -128,19 +128,19 @@ schema.getPropertyKey("name").userdata() #### 2.3 VertexLabel -##### 2.3.1 接口及参数介绍 +##### 2.3.1 Interface and parameter introduction -VertexLabel 用来定义顶点类型，描述顶点的约束信息： +VertexLabel is used to define the vertex type and describe the constraint information of the vertex. -VertexLabel 允许定义的约束信息包括：name、idStrategy、properties、primaryKeys和 nullableKeys，下面逐一介绍。 +The constraint information that VertexLabel allows to define include: name, idStrategy, properties, primaryKeys and nullableKeys, which are introduced one by one below. -- name: 属性的名字，用来区分不同的 VertexLabel，不允许有同名的属性； +- name: The name of the VertexLabel, used to distinguish different VertexLabels, VertexLabels with the same name are not allowed. interface | param | must set ------------------------ | ----- | -------- vertexLabel(String name) | name | y -- idStrategy: 每一个 VertexLabel 都可以选择自己的 Id 策略，目前有三种策略供选择，即 Automatic（自动生成）、Customize（用户传入）和 PrimaryKey（主属性键）。其中 Automatic 使用 Snowflake 算法生成 Id，Customize 需要用户自行传入字符串或数字类型的 Id，PrimaryKey 则允许用户从 VertexLabel 的属性中选择若干主属性作为区分的依据，HugeGraph 内部会根据主属性的值拼接生成 Id。idStrategy 默认使用 Automatic的，但如果用户没有显式设置 idStrategy 又调用了 primaryKeys(...) 方法设置了主属性，则 idStrategy 将自动使用 PrimaryKey； +- idStrategy: Each VertexLabel can choose its own Id strategy. There are currently three strategies to choose from, namely Automatic (automatically generated), Customize (user input) and PrimaryKey (primary attribute key). Among them, Automatic uses the Snowflake algorithm to generate Id, Customize requires the user to pass in the Id of string or number type, and PrimaryKey allows the user to select several properties of VertexLabel as the basis for differentiation. HugeGraph will be spl [...] interface | idStrategy | description --------------------- | ----------------- | ------------------------------------------------------ @@ -149,85 +149,83 @@ useCustomizeStringId | CUSTOMIZE_STRING | passed id by user, must be string ty useCustomizeNumberId | CUSTOMIZE_NUMBER | passed id by user, must be number type usePrimaryKeyId | PRIMARY_KEY | choose some important prop as primary key to splice id -- properties: 定义顶点的属性，传入的参数是 PropertyKey 的 name +- properties: define the properties of the vertex, the incoming parameter is the name of the PropertyKey. interface | description -------------------------------- | ------------------------- -properties(String... properties) | allow to pass multi props +properties(String... properties) | allow to pass multi properties -- primaryKeys: 当用户选择了 PrimaryKey 的 Id 策略时，需要从 VertexLabel 的属性中选择若干主属性作为区分的依据； +- primaryKeys: When the user selects the Id strategy of PrimaryKey, several primary properties need to be selected from the properties of VertexLabel as the basis for differentiation; interface | description --------------------------- | ----------------------------------------- primaryKeys(String... keys) | allow to choose multi prop as primaryKeys -需要注意的是，Id 策略的选择与 primaryKeys 的设置有一些相互约束，不能随意调用，约束关系见下表： +Note that the selection of the Id strategy and the setting of primaryKeys have some mutual constraints, which cannot be called at will. The constraints are shown in the following table: | | useAutomaticId | useCustomizeStringId | useCustomizeNumberId | usePrimaryKeyId | ----------------- | -------------- | -------------------- | -------------------- | --------------- | unset primaryKeys | AUTOMATIC | CUSTOMIZE_STRING | CUSTOMIZE_NUMBER | ERROR | set primaryKeys | ERROR | ERROR | ERROR | PRIMARY_KEY -- nullableKeys: 对于通过 properties(...) 方法设置过的属性，默认全都是不可为空的，也就是在创建顶点时该属性必须赋值，这样可能对用户数据提出了太过严格的完整性要求。为避免这样的强约束，用户可以通过 -本方法设置若干属性为可空的，这样添加顶点时该属性可以不赋值。 +- nullableKeys: For properties set by the properties(...) method, all of them are non-nullable by default, that is, the property must be assigned a value when creating a vertex, which may impose too strict integrity requirements on user data. In order to avoid such strong constraints, the user can set some properties to be nullable through this method, so that the properties can be unassigned when adding vertices. interface | description ---------------------------------- | ------------------------- nullableKeys(String... properties) | allow to pass multi props -注意：primaryKeys 和 nullableKeys 不能有交集，因为一个属性不能既作为主属性，又是可空的。 +Note: primaryKeys and nullableKeys cannot intersect, because a property cannot be both primary and nullable. -- enableLabelIndex：用户可以指定是否需要为label创建索引。不创建则无法全局搜索指定label的顶点和边，创建则可以全局搜索，做类似于`g.V().hasLabel('person'), g.E().has('label', 'person')`这样的查询， -但是插入数据时性能上会更加慢，并且需要占用更多的存储空间。此项默认为 true。 +- enableLabelIndex: The user can specify whether to create an index for the label. If you don't create it, you can't globally search for the vertices and edges of the specified label. If you create it, you can search globally, like `g.V().hasLabel('person'), g.E().has('label', 'person')` query, but the performance will be slower when inserting data, and it will take up more storage space. This defaults to true. interface | description ---------------------------------- | ------------------------------- enableLabelIndex(boolean enable) | Whether to create a label index -- userdata：用户可以自己添加一些约束或额外信息，然后自行检查传入的属性是否满足约束，或者必要的时候提取出额外信息 +- userdata: Users can add some constraints or additional information by themselves, and then check whether the incoming properties meet the constraints, or extract additional information when necessary. interface | description ---------------------------------- | ---------------------------------------------- userdata(String key, Object value) | The same key, the latter will cover the former -##### 2.3.2 创建 VertexLabel +##### 2.3.2 Create VertexLabel ```java -// 使用 Automatic 的 Id 策略 +// Use Automatic Id strategy schema.vertexLabel("person").properties("name", "age").ifNotExist().create(); schema.vertexLabel("person").useAutomaticId().properties("name", "age").ifNotExist().create(); -// 使用 Customize_String 的 Id 策略 +// Use Customize_String Id strategy schema.vertexLabel("person").useCustomizeStringId().properties("name", "age").ifNotExist().create(); -// 使用 Customize_Number 的 Id 策略 +// Use Customize_Number Id strategy schema.vertexLabel("person").useCustomizeNumberId().properties("name", "age").ifNotExist().create(); -// 使用 PrimaryKey 的 Id 策略 +// Use PrimaryKey Id strategy schema.vertexLabel("person").properties("name", "age").primaryKeys("name").ifNotExist().create(); schema.vertexLabel("person").usePrimaryKeyId().properties("name", "age").primaryKeys("name").ifNotExist().create(); ``` -##### 2.3.3 追加 VertexLabel +##### 2.3.3 Update VertexLabel -VertexLabel 是可以追加约束的，不过仅限 properties 和 nullableKeys，而且追加的属性也必须添加到 nullableKeys 集合中。 +VertexLabel can append constraints, but only properties and nullableKeys, and the appended properties must also be added to the nullableKeys collection. ```java schema.vertexLabel("person").properties("price").nullableKeys("price").append(); ``` -##### 2.3.4 删除 VertexLabel +##### 2.3.4 Delete VertexLabel ```java schema.vertexLabel("person").remove(); ``` -##### 2.3.5 查询 VertexLabel +##### 2.3.5 Query VertexLabel ```java -// 获取VertexLabel对象 +// Get VertexLabel schema.getVertexLabel("name") -// 获取property key属性 +// Get attributes of VertexLabel schema.getVertexLabel("person").idStrategy() schema.getVertexLabel("person").primaryKeys() schema.getVertexLabel("person").name() @@ -238,84 +236,84 @@ schema.getVertexLabel("person").userdata() #### 2.4 EdgeLabel -##### 2.4.1 接口及参数介绍 +##### 2.4.1 Interface and parameter introduction -EdgeLabel 用来定义边类型，描述边的约束信息。 +EdgeLabel is used to define the edge type and describe the constraint information of the edge. -EdgeLabel 允许定义的约束信息包括：name、sourceLabel、targetLabel、frequency、properties、sortKeys 和 nullableKeys，下面逐一介绍。 +The constraint information that EdgeLabel allows to define include: name, sourceLabel, targetLabel, frequency, properties, sortKeys and nullableKeys, which are introduced one by one below. -- name: 属性的名字，用来区分不同的 EdgeLabel，不允许有同名的属性； +- name: The name of the EdgeLabel, used to distinguish different EdgeLabels, EdgeLabels with the same name are not allowed. interface | param | must set ---------------------- | ----- | -------- edgeLabel(String name) | name | y -- sourceLabel: 边连接的源顶点类型名，只允许设置一个； +- sourceLabel: The name of the source vertex type of the edge link, only one is allowed; -- targetLabel: 边连接的目标顶点类型名，只允许设置一个； +- targetLabel: The name of the target vertex type of the edge link, only one is allowed; interface | param | must set ------------------------- | ----- | -------- sourceLabel(String label) | label | y targetLabel(String label) | label | y -- frequency: 字面意思是频率，表示在两个具体的顶点间某个关系出现的次数，可以是单次（single）或多次（frequency），默认为single； +- frequency: Indicating the number of times a relationship occurs between two specific vertices, which can be single (single) or multiple (frequency), the default is single. interface | frequency | description ------------ | --------- | ----------------------------------- singleTime() | single | a relationship can only occur once multiTimes() | multiple | a relationship can occur many times -- properties: 定义边的属性 +- properties: Define the properties of the edge. interface | description -------------------------------- | ------------------------- properties(String... properties) | allow to pass multi props -- sortKeys: 当 EdgeLabel 的 frequency 为 multiple 时，需要某些属性来区分这多次的关系，故引入了 sortKeys（排序键）； +- sortKeys: When the frequency of EdgeLabel is multiple, some properties are needed to distinguish the multiple relationships, so sortKeys (sorted keys) is introduced; interface | description ------------------------ | -------------------------------------- sortKeys(String... keys) | allow to choose multi prop as sortKeys -- nullableKeys: 与顶点中的 nullableKeys 概念一致，不再赘述 +- nullableKeys: Consistent with the concept of nullableKeys in vertices. -注意：sortKeys 和 nullableKeys也不能有交集。 +Note: sortKeys and nullableKeys also cannot intersect. -- enableLabelIndex：与顶点中的 enableLabelIndex 概念一致，不再赘述 +- enableLabelIndex: It is consistent with the concept of enableLabelIndex in the vertex. -- userdata：用户可以自己添加一些约束或额外信息，然后自行检查传入的属性是否满足约束，或者必要的时候提取出额外信息 +- userdata: Users can add some constraints or additional information by themselves, and then check whether the incoming properties meet the constraints, or extract additional information when necessary. interface | description ---------------------------------- | ---------------------------------------------- userdata(String key, Object value) | The same key, the latter will cover the former -##### 2.4.2 创建 EdgeLabel +##### 2.4.2 Create EdgeLabel ```java schema.edgeLabel("knows").link("person", "person").properties("date").ifNotExist().create(); schema.edgeLabel("created").multiTimes().link("person", "software").properties("date").sortKeys("date").ifNotExist().create(); ``` -##### 2.4.3 追加 EdgeLabel +##### 2.4.3 Update EdgeLabel ```java schema.edgeLabel("knows").properties("price").nullableKeys("price").append(); ``` -##### 2.4.4 删除 EdgeLabel +##### 2.4.4 Delete EdgeLabel ```java schema.edgeLabel("knows").remove(); ``` -##### 2.4.5 查询 EdgeLabel +##### 2.4.5 Qeury EdgeLabel ```java -// 获取EdgeLabel对象 +// Get EdgeLabel schema.getEdgeLabel("knows") -// 获取property key属性 +// Get attributes of EdgeLabel schema.getEdgeLabel("knows").frequency() schema.getEdgeLabel("knows").sourceLabel() schema.getEdgeLabel("knows").targetLabel() @@ -328,28 +326,28 @@ schema.getEdgeLabel("knows").userdata() #### 2.5 IndexLabel -##### 2.5.1 接口及参数介绍 +##### 2.5.1 Interface and parameter introduction -IndexLabel 用来定义索引类型，描述索引的约束信息，主要是为了方便查询。 +IndexLabel is used to define the index type and describe the constraint information of the index, mainly for the convenience of query. -IndexLabel 允许定义的约束信息包括：name、baseType、baseValue、indexFeilds、indexType，下面逐一介绍。 +The constraint information that IndexLabel allows to define include: name, baseType, baseValue, indexFeilds, indexType, which are introduced one by one below. -- name: 属性的名字，用来区分不同的 IndexLabel，不允许有同名的属性； +- name: The name of the IndexLabel, used to distinguish different IndexLabels, IndexLabels with the same name are not allowed. interface | param | must set ----------------------- | ----- | -------- indexLabel(String name) | name | y -- baseType: 表示要为 VertexLabel 还是 EdgeLabel 建立索引, 与下面的 baseValue 配合使用； +- baseType: Indicates whether to index VertexLabel or EdgeLabel, used in conjunction with the baseValue below. -- baseValue: 指定要建立索引的 VertexLabel 或 EdgeLabel 的名称； +- baseValue: Specifies the name of the VertexLabel or EdgeLabel to be indexed. interface | param | description --------------------- | --------- | ---------------------------------------- onV(String baseValue) | baseValue | build index for VertexLabel: 'baseValue' onE(String baseValue) | baseValue | build index for EdgeLabel: 'baseValue' -- indexFeilds: 要在哪些属性上建立索引，可以是为多列建立联合索引； +- indexFields: on which fields to index, it can be a joint index for multiple columns. interface | param | description -------------------- | ----- | --------------------------------------------------------- @@ -390,7 +388,7 @@ search() | Search | support full text search shard() | Shard | support prefix + range(numeric or date type) search unique() | Unique | support unique props value, not support search -##### 2.5.2 创建 IndexLabel +##### 2.5.2 Create IndexLabel ```java schema.indexLabel("personByAge").onV("person").by("age").range().ifNotExist().create(); @@ -400,19 +398,19 @@ schema.indexLabel("personByCityAndAge").onV("person").by("city", "age").shard(). schema.indexLabel("personById").onV("person").by("id").unique().ifNotExist().create(); ``` -##### 2.5.3 删除 IndexLabel +##### 2.5.3 Delete IndexLabel ```java schema.indexLabel("personByAge").remove() ``` -##### 2.5.4 查询 IndexLabel +##### 2.5.4 Query IndexLabel ```java -// 获取IndexLabel对象 +// Get IndexLabel schema.getIndexLabel("personByAge") -// 获取property key属性 +// Get attributes of IndexLabel schema.getIndexLabel("personByAge").baseType() schema.getIndexLabel("personByAge").baseValue() schema.getIndexLabel("personByAge").indexFields()
