图¶

图对象¶

class graphscope.framework.graph.GraphDAGNode(session, incoming_data=None, oid_type='int64', vid_type='uint64', directed=True, generate_eid=True, retain_oid=True, vertex_map: str | int = 'global', compact_edges=False, use_perfect_hash=False)[源代码]¶

一个类，表示DAG（有向无环图）中的一个图节点。

在GraphScope中，所有生成新图的操作都会返回一个GraphDAGNode实例，该实例将在eager模式下由Session.run()自动执行。

以下示例演示了其用法：

>>> # lazy mode
>>> import graphscope as gs
>>> sess = gs.session(mode="lazy")
>>> g = sess.g()
>>> g1 = g.add_vertices("person.csv","person")
>>> print(g1) # <graphscope.framework.graph.GraphDAGNode object>
>>> g2 = sess.run(g1)
>>> print(g2) # <graphscope.framework.graph.Graph object>

>>> # eager mode
>>> import graphscope as gs
>>> sess = gs.session(mode="eager")
>>> g = sess.g()
>>> g1 = g.add_vertices("person.csv","person")
>>> print(g1) # <graphscope.framework.graph.Graph object>
>>> del g1

__init__(session, incoming_data=None, oid_type='int64', vid_type='uint64', directed=True, generate_eid=True, retain_oid=True, vertex_map: str | int = 'global', compact_edges=False, use_perfect_hash=False)[源代码]¶

构建一个GraphDAGNode对象。

Parameters:

session (Session) – 一个graphscope会话实例。
incoming_data –
图可以通过多种类型的源进行初始化，可以是以下之一：
- graphscope.framework.operation.Operation
- graphscope.nx.Graph
- graphscope.Graph
- vineyard.Object, vineyard.ObjectId 或 vineyard.ObjectName
oid_type – (str, 可选): 顶点原始ID的类型。默认为"int64"。
vid_type – (str, 可选): 顶点内部ID的类型。默认为"uint64"。
directed – (布尔值, 可选): 是否为有向图。默认为 True。
generate_eid – (bool, 可选参数): 当设置为True时为每条边生成ID。默认为True。
retain_oid – (布尔值, 可选): 当设为True时保留顶点表中的原始ID。默认为True。
vertex_map (str, optional) – 指定使用全局顶点映射还是局部顶点映射。可选值为"global"或"local"。默认为global。
compact_edges (bool, optional) – 使用变长整型和差值编码压缩边(CSR格式)。默认为False。注意压缩边可以使图数据结构中边的内存使用量减半，但可能导致某些算法性能下降最多10%~20%。默认为False。
use_perfect_hash (bool, optional) – 在顶点映射中使用完美哈希以优化内存使用。默认为 False。

add_column(results, selector)[源代码]¶

将结果作为一列添加到图中。修改规则由选择器指定。

Parameters:

results – 继承自(graphscope.framework.context.BaseContextDAGNode)的具体类实例: 通过对图执行应用查询创建的上下文，并保存相应的结果。
selector (dict) – 选择要添加为列的结果。格式类似于graphscope.framework.context.Context中的选择器

Returns:

一个带有新列的新图，以即时模式评估。

Return type:

graphscope.framework.graph.GraphDAGNode

add_edges(edges, label='_e', properties=None, src_label=None, dst_label=None, src_field: int | str = 0, dst_field: int | str = 1)[源代码]¶

向图中添加边，并返回一个新图。此处src_label和dst_label必须同时指定或同时不指定。

未指定 src_label 和 dst_label 且当前图没有顶点标签。

我们从边表推导顶点标签，并将顶点标签名称设为 '_'。
src_label和dst_label均未指定，且当前图只有一个顶点标签。

我们将src_label和dst_label设置为这个唯一的顶点标签。

src_label和dst_label均已指定，并且存在于当前图的顶点标签中。
src_label 和 dst_label 均已指定，但其中部分在当前图的顶点标签中不存在。

我们从边表中推导缺失的顶点标签。

Parameters:

edges (Union[str, Loader]) - 边数据源。
label (str, optional) – 边标签名称。默认为"_e"。
properties (list[str], optional) – 作为属性加载的列名列表。默认为None。
src_label (str, optional) – 源顶点标签。默认为 None。
dst_label (str, optional) – 目标顶点标签。默认为 None。
src_field (int, optional) – 用作源字段的列索引或名称。默认为0。
dst_field (int, optional) – 用作目标字段的列索引或名称。默认为1。

Raises:

ValueError – 如果给定值无效或与当前图冲突。

Returns:

在即时模式下评估的添加了边的新图。

Return type:

graphscope.framework.graph.GraphDAGNode

add_vertices(vertices, label='_', properties=None, vid_field: int | str = 0)[源代码]¶

向图中添加顶点，并返回一个新图。

Parameters:

vertices (Union[str, Loader]) – 顶点数据源。
label (str, optional) – 顶点标签名称。默认为"_"。
properties (list[str], optional) – 作为属性加载的列名列表。默认为None。
vid_field (int 或 str, 可选) – 用作ID字段的列索引或属性名称。默认为0。

Raises:

ValueError – 如果给定值无效或与当前图冲突。

Returns:

在即时模式下评估后新增顶点的新图。

Return type:

graphscope.framework.graph.GraphDAGNode

consolidate_columns(label: str, columns: List[str] | Tuple[str], result_column: str)[源代码]¶

将给定顶点/边的属性列（相同类型）合并为一列。

例如，如果我们有一个顶点标签为"person"、边标签为"knows"和"follows"的图，并且我们希望将顶点和两条边的"weight0"、"weight1"属性合并到一个新列"weight"中，我们可以这样做：

>>> g = ...
>>> g = g.consolidate_columns("person", ["weight0", "weight1"], "weight")
>>> g = g.consolidate_columns("knows", ["weight0", "weight1"], "weight")
>>> g = g.consolidate_columns("follows", ["weight0", "weight1"], "weight")

Parameters:

label – 顶点或边的标签。
columns (dict) – 需要合并的顶点或边的属性。
result_column – 新列的名称。

Returns:

一个经过列合并的新图，以即时模式评估。

Return type:

graphscope.framework.graph.GraphDAGNode

project(vertices: Mapping[str, List[str] | None], edges: Mapping[str, List[str] | None])[源代码]¶

从属性图中投影出一个子图，并返回一个新图。通过投影生成的图与普通属性图类似，可以进一步进行投影操作。

Parameters:

vertices (dict) – 键是顶点标签名称，值是一个字符串列表，表示属性名称。特别地，如果值为None则会选择所有属性。请注意，您想要投影的所有边中的顶点标签都应包含在内。
edges (dict) - 键是边标签名称，值是一个字符串列表，表示属性名称。特别地，如果值为None，则会选择所有属性。

Returns:

从属性图投影出的新图，以即时模式评估。

Return type:

graphscope.framework.graph.GraphDAGNode

class graphscope.framework.graph.Graph(graph_node)[源代码]¶

一个用于表示GraphScope中图元数据的类。

一个Graph对象保存了图的元数据，例如键、模式以及图是否为有向图。

值得注意的是，该图由后端（如Analytical Engine、Vineyard）存储。换句话说，图对象仅保存元数据。

以下示例演示了其用法：

>>> import graphscope as gs
>>> sess = gs.session()
>>> graph = sess.g()
>>> graph = graph.add_vertices("person.csv", "person")
>>> graph = graph.add_vertices("software.csv", "software")
>>> graph = graph.add_edges("knows.csv", "knows", src_label="person", dst_label="person")
>>> graph = graph.add_edges("created.csv", "created", src_label="person", dst_label="software")
>>> print(graph)
>>> print(graph.schema)

__init__(graph_node)[源代码]¶: 构建一个Graph对象。

add_column(results, selector)[源代码]¶

将结果作为一列添加到图中。修改规则由选择器指定。

Parameters:

results – 继承自(graphscope.framework.context.BaseContextDAGNode)的具体类实例：通过对图执行应用查询创建的上下文，并保存相应的结果。
selector (dict) – 选择要添加为列的结果。格式类似于graphscope.framework.context.Context中的选择器

Returns:

一个带有新列的新图，以即时模式评估。

Return type:

graphscope.framework.graph.GraphDAGNode

add_edges(edges, label='_', properties=None, src_label=None, dst_label=None, src_field: int | str = 0, dst_field: int | str = 1) → 图 | GraphDAGNode[源代码]¶

向图中添加边，并返回一个新图。此处src_label和dst_label必须同时指定或同时不指定。

未指定 src_label 和 dst_label 且当前图没有顶点标签。

我们从边表推导顶点标签，并将顶点标签名称设为 '_'。
src_label和dst_label均未指定，且当前图只有一个顶点标签。

我们将src_label和dst_label设置为这个唯一的顶点标签。

src_label和dst_label均已指定，并且存在于当前图的顶点标签中。
src_label 和 dst_label 均已指定，但其中部分在当前图的顶点标签中不存在。

我们从边表中推导缺失的顶点标签。

Parameters:

edges (Union[str, Loader]) - 边数据源。
label (str, optional) – 边标签名称。默认为"_e"。
properties (list[str], optional) – 作为属性加载的列名列表。默认为None。
src_label (str, optional) – 源顶点标签。默认为 None。
dst_label (str, optional) – 目标顶点标签。默认为 None。
src_field (int, optional) – 用作源字段的列索引或名称。默认为0。
dst_field (int, optional) – 用作目标字段的列索引或名称。默认为1。

Raises:

ValueError – 如果给定值无效或与当前图冲突。

Returns:

在即时模式下评估的添加了边的新图。

Return type:

graphscope.framework.graph.GraphDAGNode

add_vertices(vertices, label='_', properties=None, vid_field: int | str = 0) → 图 | GraphDAGNode[源代码]¶

向图中添加顶点，并返回一个新图。

Parameters:

vertices (Union[str, Loader]) – 顶点数据源。
label (str, optional) – 顶点标签名称。默认为"_"。
properties (list[str], optional) – 作为属性加载的列名列表。默认为None。
vid_field (int 或 str, 可选) – 用作ID字段的列索引或属性名称。默认为0。

Raises:

ValueError – 如果给定值无效或与当前图冲突。

Returns:

在即时模式下评估后新增顶点的新图。

Return type:

graphscope.framework.graph.GraphDAGNode

consolidate_columns(label: str, columns: List[str] | Tuple[str], result_column: str) → 图 | GraphDAGNode[源代码]¶

将给定顶点/边的属性列（相同类型）合并为一列。

>>> g = ...
>>> g = g.consolidate_columns("person", ["weight0", "weight1"], "weight")
>>> g = g.consolidate_columns("knows", ["weight0", "weight1"], "weight")
>>> g = g.consolidate_columns("follows", ["weight0", "weight1"], "weight")

Parameters:

label – 顶点或边的标签。
columns (dict) – 需要合并的顶点或边的属性。
result_column – 新列的名称。

Returns:

一个经过列合并的新图，以即时模式评估。

Return type:

graphscope.framework.graph.GraphDAGNode

detach()[源代码]¶

分离图可以使其保留在vineyard中，即使该Graph对象的变量离开了词法作用域。

之后可以通过图的ObjectID或其名称来访问该图。

property key¶: 引擎中对应图的关键标识。

classmethod load_from(uri, sess=None, **kwargs)[源代码]¶

从特定数据源加载ArrowProperty图。该数据源可以是vineyard序列化文件、graphar序列化文件或graphscope支持的其他数据源。

Parameters:

uri (str) – URI包含数据源的描述或路径包含序列化文件，示例："graphar+file:///tmp/graphar/xxx"
sess (graphscope.Session) – 目标会话，图将在其中构建。如果为None，则使用默认会话。
selector (dict, optional) – 用于选择要读取数据的筛选器。
graphar_store_in_local (bool, optional) – 是否在本地存储graphar格式，默认为False。

Returns:

一个新的图对象。

Return type:

图

loaded()[源代码]¶: 如果当前图已加载到会话中，则为True。

project(vertices: Mapping[str, List[str] | None], edges: Mapping[str, List[str] | None]) → 图 | GraphDAGNode[源代码]¶

从属性图中投影出一个子图，并返回一个新图。通过投影生成的图与普通属性图类似，可以进一步进行投影操作。

Parameters:

vertices (dict) - 键是顶点标签名称，值是一个字符串列表，表示属性名称。特别地，如果值为None则会选择所有属性。请注意，您想要投影的所有边中的顶点标签都应包含在内。
edges (dict) - 键是边标签名称，值是一个字符串列表，表示属性的名称。特别地，如果值为None，则会选择所有属性。

Returns:

从属性图投影出的新图，以即时模式评估。

Return type:

graphscope.framework.graph.GraphDAGNode

save_to(path, format='serialization', **kwargs)[源代码]¶

将图以指定格式保存到指定位置。

Parameters:

path (str) – 写入图的目录路径。
format (str) – 写入图的格式，默认为"serialization"。
selector (dict, optional) – 用于选择要写入数据的筛选器。
graphar_graph_name (str, optional) – graphar格式中图的名称。
graphar_file_type (str, optional) – graphar格式的文件类型，支持"parquet"、"orc"、"csv"，默认为"parquet"。
graphar_vertex_chunk_size (int, optional) – graphar格式中顶点的分块大小，默认为2^18。
graphar_edge_chunk_size (int, optional) – graphar格式中边的分块大小，默认为2^22。
graphar_store_in_local (bool, optional) – 是否在本地存储graphar格式，默认为False。

返回 (dict): 包含输出数据类型和URI字符串的字典。

property schema¶

图的模式。

Returns:: 图的模式
Return type:: GraphSchema

property schema_path¶

Coordinator将写入交互式模式路径的路径。

Returns:: 该路径包含交互式引擎的schema。
Return type:: 字符串

property session_id¶

获取当前会话ID。

Returns:: 返回该图所属的会话ID。
Return type:: 字符串

to_dataframe(selector, vertex_range=None)[源代码]¶

从图中选择部分元素并以pandas.DataFrame格式输出

Parameters:

selector (dict) – 选择图的部分内容。
vertex_range (dict, 可选) – 顶点范围切片。默认为 None。

Returns:

pandas.DataFrame

to_directed()[源代码]¶

返回图的有向表示。

Returns:

一个有向图，具有相同的名称、相同的节点，并且: 每条边(u, v, data)被替换为两条有向边(u, v, data)和(v, u, data)。

Return type:

Graph

to_numpy(selector, vertex_range=None)[源代码]¶

选择图中的部分元素并输出到numpy。

Parameters:

selector (str) – 选择图的一部分作为numpy.ndarray数组。
vertex_range (dict, optional) – 顶点范围切片。默认为None。

Returns:

numpy.ndarray

to_undirected()[源代码]¶

返回有向图的无向表示形式。

Returns:

一个具有相同名称和节点的无向图: 如果(u, v, data)或(v, u, data)存在于有向图中，则包含边(u, v, data)。如果两个边都存在于有向图中，它们都将被保留。如果需要，您必须手动检查并纠正这种情况。

Return type:

Graph

property vineyard_id¶

获取该图的vineyard object_id。

Returns:: 返回该图的vineyard ID
Return type:: 字符串

Loader 对象¶

class graphscope.framework.loader.Loader(source, delimiter=',', sep=',', header_row=True, filetype='CSV', **kwargs)[源代码]¶

通用数据源封装器。 Loader可以接收多种数据源，并将必要信息组装成AttrValue。

__init__(source, delimiter=',', sep=',', header_row=True, filetype='CSV', **kwargs)[源代码]¶

使用可配置选项初始化加载器。注意：加载器无法重复使用，因为在构建图加载信息时可能会改变其内部状态。

Parameters:

source (str 或 value) –
待加载的数据源，可以是以下类型之一：
- 本地文件：通过URL file://...指定
- oss文件：通过URL oss://...指定
- hdfs文件：通过URL hdfs://...指定
- s3文件：通过URL s3://...指定
- numpy ndarray（CSR格式）
- pandas dataframe
常规数据源也可以通过vineyard流加载，在URL中使用vineyard://前缀后，本地文件、oss对象或HDFS文件将首先加载到vineyard流中，然后GraphScope的分片将在这些vineyard流上构建。

当vineyard中的流式IO达到稳定状态后，这将成为GraphScope中加载数据源和构建分片的默认模式。
delimiter (char, optional) – 列分隔符。默认为','
header_row (bool, optional) – 数据源是否包含表头。如果为True，列名将从数据源的第一行读取；否则列名将被命名为'f0'、'f1'等。默认为True。
filetype (str, optional) – 指定要加载的文件类型，可以是"CSV"、"ORC"和"PARQUET"。默认为"CSV"。

备注

数据由vineyard中的驱动程序解析。更多详细信息请参阅文档中的加载图部分，以及vineyard中的实现。

图计算函数¶

使用顶点/边规范的列表加载Arrow属性图。

自版本起已弃用： 0.3 请改用 graphscope.Graph()。

使用元组字典来配置图

我们可以使用字典来设置顶点和边的配置，这些配置可用于构建图。

示例：

g = graphscope_session.load_from(
    edges={
        "group": [
            (
                "file:///home/admin/group.e",
                ["group_id", "member_size"],
                ("leader_student_id", "student"),
                ("member_student_id", "student"),
            ),
            (
                "file:///home/admin/group_for_teacher_student.e",
                ["group_id", "group_name", "establish_date"],
                ("teacher_in_charge_id", "teacher"),
                ("member_student_id", "student"),
            ),
        ]
    },
    vertices={
        "student": (
            "file:///home/admin/student.v",
            ["name", "lesson_nums", "avg_score"],
            "student_id",
        ),
        "teacher": (
            "file:///home/admin/teacher.v",
            ["name", "salary", "age"],
            "teacher_id",
        ),
    },
)

'e'表示边的标签，'v'表示顶点的标签，边以'both_in_out'格式存储，带有'e'标签的边连接从'v'到'v'。

使用字典嵌套字典的方式构建图。

我们还可以为元组中的每个元素赋予有意义的名称，使其更易于理解。

示例：

g = graphscope_session.load_from(
    edges={
        "group": [
            {
                "loader": "file:///home/admin/group.e",
                "properties": ["group_id", "member_size"],
                "source": ("leader_student_id", "student"),
                "destination": ("member_student_id", "student"),
            },
            {
                "loader": "file:///home/admin/group_for_teacher_student.e",
                "properties": ["group_id", "group_name", "establish_date"],
                "source": ("teacher_in_charge_id", "teacher"),
                "destination": ("member_student_id", "student"),
            },
        ]
    },
    vertices={
        "student": {
            "loader": "file:///home/admin/student.v",
            "properties": ["name", "lesson_nums", "avg_score"],
            "vid": "student_id",
        },
        "teacher": {
            "loader": "file:///home/admin/teacher.v",
            "properties": ["name", "salary", "age"],
            "vid": "teacher_id",
        },
    },
)

Parameters:

edges – 图的边配置
vertices (可选) – 图的顶点配置。默认为None。如果为None，我们假设所有边的src_label和dst_label都是可推导且明确的。
directed (bool, optional) – 指示该图应被视为有向图还是无向图。
oid_type (str, optional) – 图的ID类型。可选值为"int32_t"、"int64_t"或"string"。默认为"int64_t"。
vid_type (str, optional) – 图的内部顶点ID类型。可选值为"uint32_t"和"uint64_t"。默认为"uint64_t"。
generate_eid (bool, optional) – 是否为每条边生成唯一边ID。生成的eid将放置在第三列。此功能用于与交互式引擎配合使用。如果只需要与分析引擎配合工作，请将其设置为False。默认为True。
retain_oid (bool, optional) – 是否保留原始ID列作为顶点表的最后一列。此功能用于与交互式引擎配合使用。如果只需要使用分析引擎，请将其设置为False。默认为True。
vertex_map (str, optional) – 指定使用全局顶点映射或局部顶点映射。可选值为"global"或"local"。
compact_edges (bool, optional) – 使用变体和增量编码压缩边(CSR)。默认为False。注意压缩边可以帮助将图数据结构中边的内存使用量减半，但可能导致某些算法性能下降最多10%~20%。
use_perfect_hash (bool, optional) – 在顶点映射中使用完美哈希来优化内存使用。默认为False。