Euler OP

tf_euler定义了一系列OP来进行TensorFlow和Euler之间的桥接，用户可以通过在TensorFlow计算图中直接引入这些OP来进行图查询。所有的OP均可以在tf_euler顶层模块访问。

初始化图

在运行TensorFlow计算图之前，需要调用以下两个函数的其中之一对图进行初始化。

# 加载一份完整的图并独立使用
tf_euler.initialize_embedded_graph(
    directory, # 图数据路径，目前embedded模式仅支持unix文件系统
    graph_type # graph类型，compact / fast，默认compact
) # 返回bool，表示图是否初始化成功

# 在不同的worker之间自动的进行图数据的切分和共享
tf_euler.initialize_shared_graph(
    directory, # 图数据路径，目前shared模式仅支持HDFS
    zk_addr, # Zookeeper地址，ip:port
    zk_path, # Zookeeper根节点，用于协调各个shard
    shard_idx, # shard编号
    shard_num, # shard总数
    global_sampler_type, # 全局采样类型，all / node / edge / none，默认node
    graph_type, # graph类型，compact / fast，默认compact
    server_thread_num # euler service 线程数，默认4
) # 返回bool，表示图是否初始化成功

共享模式中，整张图被切分为多个shard，每个shard可以有多个worker / euler实例加入。

点边采样OP

tf_euler提供了按类型的点边采样操作。

tf_euler.ALL_NODE_TYPE # int，作为node_type传入tf_euler.sample_node作全类型采样

tf_euler.sample_node(
  count, # 0-D int32 tf.Tensor，采样点数
  node_type # 0-D int32 tf.Tensor，采样点类型（单值）
) # 返回 1-D int64 tf.Tensor [count]，采样结果

tf_euler.sample_edge(
  count, # 0-D int32 tf.Tensor，采样点数
  edge_type # 0-D int32 tf.Tensor，采样点类型（单值）
) # 返回 2-D int64 tf.Tensor [count, 2]，采样结果

# 可以根据src_node的type决定采样哪些type的node
tf_euler.sample_node_with_src(
  src_nodes, # 1-D int64 tf.Tensor, src node ID。用于决定采样哪些type，shape：[src_node_count]
  n, # 0-D int32 tf.Tensor, 每个src id采样的数目
  
  # bool类型，默认是False，让每个src_node都采样n个node；
  # 如果设置为True，会让同一种type的src_nodes一共只采样n个node
  share_sample 
) 
# 返回 2-D int64 tf.Tensor，采样结果shape: [src_node_count, n]

随机游走OP

tf_euler提供了metapath随机游走和点对生成操作来方便Random Walk模型的定义。具体参考Node2Vec

tf_euler.random_walk(
  nodes, # 1-D int64 tf.Tensor，游走源点
  edge_types, # Python列表，成员为int32 tf.Tensor，每步的游走边类型（多值）
  p, # float，回采参数，默认1
  q, # float，外采参数，默认1
  default_node # int，源点不存在，或没有出边时填充值，默认-1
) # 返回 2-D int64 tf.Tensor [#nodes, len(edge_types) + 1]，游走结果

tf_euler.gen_pair(
  paths, # 2-D int64 tf.Tensor，游走结果
  left_win_size, # int，左滑动窗口长度
  right_win_size # int，右滑动窗口长度
) # 返回 3-D int64 tf.Tensor [#paths, #pairs, 2]，所有路径的顶点正例对

顶点邻居访问OP

tf_euler提供两种方式访问按边类型部分邻居：

根据权重采样，单阶版本和多阶版本；
根据权重取Top K。

以及两种方式边类型访问全量邻居：

全量邻居；
全量邻居按照node id排序。

tf_euler.sample_neighbor(
  nodes, # 1-D int64 tf.Tensor，顶点集合
  edge_types, # 1-D int64 tf.Tensor，边类型集合（多值）
  count, # int 采样个数
  default_node # 顶点不存在或出边不足时填充值，默认-1
) # 返回 3值Python元组，分别为邻居、权重，与边类型
  # (2-D int64 tf.Tensor [#nodes, count],
  #  2-D float tf.Tensor [#nodes, count],
  #  2-D int32 tf.Tensor [#nodes, count])

tf_euler.sample_fanout(
  nodes, # 1-D int64 tf.Tensor，顶点集合
  edge_types, # Python列表，成员为 1-D int64 tf.Tensor，每步的边类型集合（多值）
  counts, # Python列表，成员为 int，每步的采样个数
  default_node # 顶点不存在或出边不足时填充值，默认-1
) # 返回 3值Python元组，分别为邻居列表、权重列表，与边类型列表
  # ([2-D int64 tf.Tensor [#nodes], [#nodes x count1], [#nodes x count1 x count2], ...],
  #  [2-D float tf.Tensor [#nodes x count1], [#nodes x count1 x count2], ...],
  #  [2-D int32 tf.Tensor [#nodes x count1], [#nodes x count1 x count2], ...] )

tf_euler.get_top_k_neighbor(
  nodes, # 1-D int64 tf.Tensor，顶点集合
  edge_types, # 1-D int64 tf.Tensor，边类型集合（多值）
  k, # int
  default_node # 顶点不存在或出边不足时填充值，默认-1
) # 返回 3值Python元组，分别为邻居与权重
  # (2-D int64 tf.Tensor [#nodes, k],
  #  2-D float tf.Tensor [#nodes, k],
  #  2-D int32 tf.Tensor [#nodes, k])

tf_euler.get_full_neighbor(
  nodes, # 1-D int64 tf.Tensor，顶点集合
  edge_types # 1-D int64 tf.Tensor，边类型集合（多值）
) # 返回 3值Python元组，分别为邻居与权重
  # (2-D int64 tf.SparseTensor [#nodes, max_num_neighbors],
  #  2-D float tf.SparseTensor [#nodes, max_num_neighbors],
  #  2-D int32 tf.SparseTensor [#nodes, max_num_neighbors])

tf_euler.get_sorted_full_neighbor(
  nodes, # 1-D int64 tf.Tensor，顶点集合
  edge_types # 1-D int64 tf.Tensor，边类型集合（多值）
) # 返回 3值Python元组，分别为邻居与权重
  # (2-D int64 tf.SparseTensor [#nodes, max_num_neighbors],
  #  2-D float tf.SparseTensor [#nodes, max_num_neighbors],
  #  2-D int32 tf.SparseTensor [#nodes, max_num_neighbors])

点边属性访问OP

tf_euler中特征为三种：稠密、稀疏，和二进制特征：

稠密特征对应于图中的Float32Feature，可以在模型中作为全连接或卷积层的输入；
稀疏特征对应于图中的UInt64Feature，可以在模型中作为tf.nn.embedding_lookop_sparse的输入;
二进制特征对应于图中的BinaryFeature，可以按照用户自定义的方式消费。

tf_euler对点和边都提供这三种特征的访问操作。

tf_euler.get_dense_feature(
  nodes, # 1-D int64 tf.Tensor，顶点集合
  feature_ids, # Python列表，成员为int，稠密特征列表
  dimensions # Python列表，成员为int，稠密特征维度
) # 返回 Python列表，成员为 2-D float tf.Tensor [#nodes, dimension]

tf_euler.get_sparse_feature(
  nodes, # 1-D int64 tf.Tensor，顶点集合
  feature_ids, # Python列表，成员为int，稀疏特征列表
  default_value # int，顶点不存在，或该特征为空时填充单值
) # 返回 Python列表，成员为 2-D int64 tf.SparseTensor [#nodes, max_num_features]

tf_euler.get_binary_feature(
  nodes, # 1-D int64 tf.Tensor，顶点集合
  feature_ids # Python列表，成员为int，二进制特征列表
) # 返回 Python列表，成员为 1-D string tf.Tensor [#nodes]

tf_euler.get_edge_dense_feature(
  edges, # 2-D int64 tf.Tensor [#edges, 3]，边集合
  feature_ids, # Python列表，成员为int，稠密特征列表
  dimensions # Python列表，成员为int，稠密特征维度
) # 返回 Python列表，成员为 2-D float tf.Tensor [#edges, dimension]

tf_euler.get_edge_sparse_feature(
  edges, # 2-D int64 tf.Tensor [#edges, 3]，边集合
  feature_ids, # Python列表，成员为int，稀疏特征列表
  default_value # int，顶点不存在，或该特征为空时填充单值
) # 返回 Python列表，成员为 2-D int64 tf.SparseTensor [#edges, max_num_features]

tf_euler.get_edge_binary_feature(
  edges, # 2-D int64 tf.Tensor [#edges, 3]，边集合
  feature_ids # Python列表，成员为int，二进制特征列表
) # 返回 Python列表，成员为 1-D string tf.Tensor [#edges]