服务端SDK

步骤1 创建阿里云账号

具体方法请参考 账号注册（PC端）。为了更好地使用阿里云服务，建议尽快完成实名认证，否则部分阿里云服务将无法使用。

步骤2 获取iGraph访问密钥

登录阿里云控制台，在购买页面设置的用户名和密码就是访问iGraph的密钥。

如忘记密码，可参考以下说明进行密码重置。

在API信息面板中，除访问用户名和密码外，还可查看内网域名（如igraph-cn-xxx）和外网域名等连接信息。如需重置密码，单击密码旁的重置密码链接。页面底部提供修改白名单入口。

步骤3 安装 Java 开发环境

iGraph Java SDK 支持 J2SE 8.0 及以上的 Java 运行环境，您可以从 Java 官方网站 下载并按说明安装 Java 开发环境。

步骤4 安装 Java SDK

推荐使用 Apache Maven 获取最新版本的 SDK，您可以添加如下配置到您的 Maven 项目。

<dependency>
  <groupId>com.aliyun.igraph</groupId>
  <artifactId>aliyun-sdk-igraph</artifactId>
  <version>{lastest-sdk-version}</version>
</dependency>

步骤5 开始使用SDK

使用 iGraph Java SDK 的主要步骤：

1. 类似于开源Gremlin客户端，配置初始化参数并构建Client实例，除了阿里云账号密码以外，您还需要设定endpoint

2. 构建查询或更新的 Query

3. 调用submit接口发起查询、更新及删除请求并处理应答或异常

参数说明

参数	类型	描述
src	String	含义：用户自己定义的场景名称 功能：统计用户查询来源的指标标识，便于故障排查的快速定位
endpoint	String	查询、更新服务的Endpoint
userName	String	经过授权的云账号userName
userPasswd	String	经过授权的云账号userPasswd
maxConnPerRoute	int	与服务端单机 HTTP 的最大连接数，建议值8
maxConnTotal	int	与服务端 HTTP 的最大总连接数，建议值2000 如果有连接数超过最大值的报错，可再适当放大
connectionRequestTimeout	int	查询超时时间，单位毫秒
socketTimeout	int	netty 参数，与connectionRequestTimeout保持一致即可
connectTimeout	int	netty 参数，与connectionRequestTimeout保持一致即可
retryTimes	int	遇到超时或可重试异常的重试次数，建议值3。

客户端初始化

• 为了增加连接池的复用，建议不要多次创建Client，尽量使用同一个Client对象。

// 配置客户端
Cluster.Builder builder = Cluster.build();
// 必选配置，指定endpoint、用户名、密码
builder.addContactPoint("your_endpoint")
       .userName("your_user_name")
       .userPasswd("your_user_passwd");
// 可选配置，不指定则客户端按默认值配置
builder.src("your_src")
       .socketTimeout(100)
       .connectTimeout(100)
       .connectionRequestTimeout(100)
       .maxConnTotal(10000)
       .maxConnPerRoute(5000)
       .retryTimes(3);
Cluster cluster = builder.create();
Client client = cluster.connect();

查询

API查询接口

• 这里提供简单一度查询的示例代码

• 首先import static com.aliyun.iGraph.client.gremlin.gremlin_api.GraphTraversalSource.g ，iGraph可以方便地指定图名来实现多图查询。

• 客户端API会对每个单步做一些简单的语法校验

// 完成一次查询并打印结果
GraphTraversal gt = g("your_graph_name").V("your_id").hasLabel("your_label");
// 调用查询接口，获取结果集
ResultSet resultSet = client.submit(gt);
List<Result> resultList = resultSet.all().join();
resultList.forEach(p -> System.out.println(p.getObject()));
// 关闭客户端
cluster.close();

明文查询接口

• 直接使用明文构建查询Query

• 在客户端通过bind将Gremlin Query中的可变参数（如key等）替换为bind变量，使得iGraph服务端可以将Gremlin Query生成的语法树放入cache，可使客户端rt下降4%-8%

• 注意：

  • 此优化仅支持g、E、V、filter、fields、order、range、join、alias等单步组成的Query

  • 此优化仅可替换V/E后的id、filter后的表达式、range后的上下边界值

  • bind_key以$开头，如$para1、$1

• 可以通过构造RequestOption指定bind和其他个性化参数

// 调用明文查询接口获取结果
String gt = "g(\"your_graph_name\").V(\"your_id\").hasLabel(\"your_label\")";
ResultSet resultSet = client.submit(gt);
// 指定bind
String gt = "g(\"your_graph_name\").V($1).hasLabel(\"your_label\")";
Map<String, Object> bind = new HashMap<>();
bind.put("$1", "1");
ResultSet resultSet = client.submit(gt, bind);
// 通过 RequestOptions 指定个性化参数
String gt = "g(\"your_graph_name\").V($1).hasLabel(\"your_label\")";
RequestOptions requestOptions = RequestOptions.build()
        .src("your_src")
        .timeout(1000)
        .retryTimes(2)
        .addParameter("$1", "1")
        .create();
ResultSet resultSet = client.submit(gt,requestOptions);

更新与删除

• iGraph支持Gremlin语法的插入与删除操作，但不支持游走中的节点更新

• 更新时需要指定节点或边的所有属性

• 删除时只需要指定pkey

• 返回的ResultSet中保存本次请求的相关信息

// 插入一个只有一个属性值的点
GraphTraversal gt = g("your_graph_name").addV("your_label").property("pkey", "pk_value").property("value", "0.5");
ResultSet resultSet = client.submit(gt);
List<Result> resultList = resultSet.all().join();
resultList.forEach(p -> System.out.println(p.getObject()));
// 将更新的节点删除
gt = g("your_graph_name").V("pk_value").hasLabel("your_label").drop();
resultSet = client.submit(gt);
resultList = resultSet.all().join();
resultList.forEach(p -> System.out.println(p.getObject()));

更多更新和删除样例

// 插入一条有两个属性值的边
gt = g("graph_name").addE("label").property("pkey", "pk_value").property("skey","sk_value").property("value1", "abc").property("value2", "0.5");
// 删除指定pkey的边，若存在符合条件的多条边，全部删除
gt = g("graph_name").E("pk1").hasLabel("label").drop();
// 删除指定pkey、skey的边
gt = g("graph_name").E("pk1:sk1").hasLabel("label").drop();

ResultSet

• 每次查询返回一个ResultSet，结果的获取接口与TinkerPop完全相同，可以通过如下接口获取：

// 获取本次请求的所有结果。iGraph SDK不是流式的，会一次性返回所有结果，建议使用此接口。
CompletableFuture<List<Result>> futureList = resultSet.all();
// 获取本次请求的部分结果
CompletableFuture<List<Result>> futureList = resultSet.some(int i);
// 获取本次请求的单条结果
Result result = resultSet.one();

• 每个Result就是一条结果，您需要根据结果类型调用相应的接口：

接口	意义
String getString()	获取String结果
int getInt()	获取int结果
byte getByte()	获取byte结果
short getShort()	获取short结果
long getLong()	获取long结果
float getFloat()	获取float结果
double getDouble()	获取double结果
boolean getBoolean()	获取boolean结果
Vertex getVertex()	获取一个点
Edge getEdge()	获取一条边
Element getElement()	获取一个实体元素，可以是一个点也可以是一条边
Path getPath()	获取一条游走路径
<V> Property<V> getProperty()	获取一条属性
<V> VertexProperty<V> getVertexProperty()	获取一条点的属性
<T> T get(final Class<? extends T> clazz)	获取泛型结果，包含iGraph扩展的数据类型
Object getObject()	获取Object，在您不确定结果类型时可以选择这个通用接口

• 其中，<T> T get(final Class<? extends T> clazz)是可以获取多值类型、Map、Set、BulkSet等特殊数据类型，详见以下示例：

// 获取List
List<Result> vecValue = result.get(List.class);
// 获取Map.Entry
Map.Entry<Result, Result> entry = result.get(Map.Entry.class);
// 获取Set
Set<Result> setValue = result.get(Set.class);
// 获取Map
Map<Object, Result> mapValue = result.get(Map.class);
// 获取BulkSet
BulkSet bulkSet = result.get(BulkSet.class);
Map<Result, Long> value = bulkSet.getValue();
// 获取多值结果
List<Byte> multiValues = result.get(MultiByte.class).getValue();
List<Short> multiValues = result.get(MultiShort.class).getValue();
List<Integer> multiValues = result.get(MultiInt.class).getValue();
List<Long> multiValues = result.get(MultiLong.class).getValue();
List<Integer> multiValues = result.get(MultiUInt8.class).getValue();
List<Integer> multiValues = result.get(MultiUInt16.class).getValue();
List<Long> multiValues = result.get(MultiUInt32.class).getValue();
List<Long> multiValues = result.get(MultiUInt64.class).getValue();
List<Float> multiValues = result.get(MultiFloat.class).getValue();
List<Double> multiValues = result.get(MultiDouble.class).getValue();
List<String> values = result.get(MultiString.class).getValue();

Path

• Path代表的是一条或多条路径，记录了多跳查询时经过的顶点或者边信息，具体由 Query 决定。 Path 接口如下：

• 调用objects()获取路径内容

接口	意义
int size()	路径上元素的数量
boolean isEmpty()	判断路径是否为空
<A> A head()	获取路径的起点
<A> A get(String label)	获取对应label的元素或元素列表
<A> A get(Pop pop, String label)	获取部分对应label的元素或元素列表
<A> A get(int index)	获取路径上某一个元素
boolean hasLabel(String label)	判断路径中是否存在对应label的元素
List<Object> objects()	获取路径元素的列表
List<Set<String>> labels()	获取路径元素的label列表
Path clone()	克隆当前路径
boolean isSimple()	判断当前路径是不是简单路径
Iterator<Object> iterator()	获取路径的迭代器
void forEach(BiConsumer<Object, Set<String>> consumer)	通用接口
Stream<Pair<Object, Set<String>>> stream()	获取路径的stream
boolean popEquals(Pop pop, Object other)	判断两个路径是否相等
Path subPath(String fromLabel, String toLabel)	获取子路径

Vertex/Edge

• Vertex 是顶点，Edge是边，对应的是iGraph中的一条记录，接口如下：

  接口	意义
  String label()	获取元素的label
  Set<String> keys()	获取元素的属性名
  <V> Property<V> property(String key)	获取对应key值的属性
  <V> V value(String key)	获取对应key的属性值
  <V> Iterator<V> values(String... propertyKeys)	获取对应一组key的属性值
  <V> Iterator<VertexProperty<V>> properties(final String... propertyKeys)	获取对应一组key的属性

  • 调用value(String key) 获取的属性值可以是多种数据类型，具体由Query决定

Property/VertexProperty

• Property和VertexProperty都是属性，调用Vertex.property(String key)获取的顶点属性VertexProperty，接口如下：

  接口	意义
  String key()	获取属性名
  V value()	获取属性值
  boolean isPresent()	判断是否可用
  void ifPresent(final Consumer<? super V> consumer)	如果可用，将结果传入Consumer
  V orElse(final V otherValue)	如果可用，返回value，否则返回otherValue
  V orElseGet(final Supplier<? extends V> valueSupplier)	如果可用，返回value，否则从Supplier获取结果
  <E extends Throwable> V orElseThrow(final Supplier<? extends E> exceptionSupplier) throws E	如果可用，返回value，否则从Supplier获取并抛出异常
  Element element()	获取当前属性所属的元素（仅支持从元素查询得到的Property）

  • 调用value() 获取的属性值可以是多种数据类型，具体由Query决定