GFQL 快速参考

GFQL 快速参考#

本快速参考页面提供了各种参数和使用模式的简短示例。

基本用法#

链式操作

g.chain(ops=[...], engine=EngineAbstract.AUTO)

chain 序列化多个匹配器以处理更复杂的路径和子图模式

  • ops: 图形节点和边匹配器的序列 (ASTObject 实例)。

  • engine: 可选的执行引擎。通常不设置引擎，默认为‘auto’。使用‘cudf’进行GPU加速，使用‘pandas’进行CPU处理。

节点匹配器#

n(filter_dict=None, name=None, query=None)

n 根据节点的属性匹配节点。

  • 根据属性过滤节点。

  • 参数:

    • filter_dict: {attribute: value} 或 {attribute: condition_function}

    • name: 可选标签；在结果中添加一个布尔列。

    • query: 自定义查询字符串（例如，“age > 30 and country == ‘USA’”）。

示例：

  • 匹配type为‘person’的节点：

    n({"type": "person"})

  • 匹配age大于30的节点：

    n({"age": lambda x: x > 30})

  • 使用自定义查询字符串：

    n(query="age > 30 and country == 'USA'")

边缘匹配器#

e_forward(edge_match=None, hops=1, to_fixed_point=False, source_node_match=None, destination_node_match=None, source_node_query=None, destination_node_query=None, edge_query=None, name=None)
e_reverse(edge_match=None, hops=1, to_fixed_point=False, source_node_match=None, destination_node_match=None, source_node_query=None, destination_node_query=None, edge_query=None, name=None)
e_undirected(edge_match=None, hops=1, to_fixed_point=False, source_node_match=None, destination_node_match=None, source_node_query=None, destination_node_query=None, edge_query=None, name=None)

# alias for e_undirected
e(edge_match=None, hops=1, to_fixed_point=False, source_node_match=None, destination_node_match=None, source_node_query=None, destination_node_query=None, edge_query=None, name=None)

e 根据边的属性匹配边（无向）。也可以包括对边的源节点和目标节点的匹配。

  • 沿正向遍历边。

  • 参数:

    • edge_match: {attribute: value} 或 {attribute: condition_function}

    • edge_query: 用于边缘属性的自定义查询字符串。

    • hops: int, 要遍历的跳数。

    • to_fixed_point: bool, 继续遍历直到没有更多匹配。

    • source_node_match: 源节点的过滤器。

    • destination_node_match: 目标节点的过滤器。

    • source_node_query: 源节点的自定义查询字符串。

    • destination_node_query: 目标节点的自定义查询字符串。

    • name: 可选的标签。

示例：

  • 在status为‘active’的边上向前遍历2跳：

    e_forward({"status": "active"}, hops=2)

  • 使用自定义边缘查询字符串：

    e_forward(edge_query="weight > 5 and type == 'connects'")

  • 使用匹配字典过滤源节点和目标节点：

    e_forward(
    source_node_match={"status": "active"},
    destination_node_match={"age": lambda x: x < 30}
)

  • 使用查询过滤源节点和目标节点：

    e_forward(
    source_node_query="status == 'active'",
    destination_node_query="age < 30"
)

  • 匹配边的标签：

    e_forward(name="active_edges")

e_reverse, e_forward, 和 e 是别名。

谓词#

graphistry.compute.predicates.ASTPredicate.ASTPredicate

  • 使用实体属性上的谓词进行匹配。

更多信息请参见GFQL Operator Reference。

示例：

  • 匹配category为‘A’、‘B’或‘C’的节点：

    from graphistry import n, is_in

n({"category": is_in(["A", "B", "C"])})

组合示例#

  • 通过活跃关系查找与交易相关的人员：

    g.chain([
    n({"type": "person"}),
    e_forward({"status": "active"}),
    n({"type": "transaction"})
])

  • 在遍历过程中标记节点和边：

    g.chain([
    n({"id": "start_node"}, name="start"),
    e_forward(name="edge1"),
    n({"level": 2}, name="middle"),
    e_forward(name="edge2"),
    n({"type": "end_type"}, name="end")
])

  • 遍历直到没有更多匹配（固定点）：

    g.chain([
    n({"status": "infected"}),
    e_forward(to_fixed_point=True),
    n(name="reachable")
])

  • 按多个条件过滤：

    g.chain([
    n({"type": is_in(["server", "database"])}),
    e_undirected({"protocol": "TCP"}, hops=3),
    n(query="risk_level >= 8")
])

  • 在匹配器中使用自定义查询：

    g.chain([
    n(query="age > 30 and country == 'USA'"),
    e_forward(edge_query="weight > 5"),
    n(query="status == 'active'")
])

GPU加速#

  • 启用GPU模式：

    g.chain([...], engine='cudf')

  • 使用 cuDF DataFrames 的示例：

    import cudf

e_gdf = cudf.from_pandas(edge_df)
n_gdf = cudf.from_pandas(node_df)

g = graphistry.nodes(n_gdf, 'node_id').edges(e_gdf, 'src', 'dst')
g.chain([...], engine='cudf')

远程模式#

  • 查询现有的远程数据

    g = graphistry.bind(dataset_id='ds-abc-123')

nodes_df = g.chain_remote([n()])._nodes

  • 上传图表并运行GFQL

    g2 = g1.upload()

g3 = g2.chain_remote([n(), e(), n()])

  • 在远程GFQL上强制使用CPU和GPU模式

    g3a = g2.chain_remote([n(), e(), n()], engine='pandas')
g3b = g2.chain_remote([n(), e(), n()], engine='cudf')

  • 仅返回节点和特定列

    cols = ['id', 'name']
g2b = g1.chain_remote([n(), e(), n()], output_type="edges", edge_col_subset=cols)

  • 仅返回边和特定列

    cols = ['src', 'dst']
g2b = g1.chain_remote([n(), e(), n()], output_type="edges", edge_col_subset=cols)

  • 仅返回形状元数据

    shape_df = g1.chain_remote_shape([n(), e(), n()])

  • 运行远程Python并获取图表

    def my_remote_trim_graph_task(g):
    return (g
        .nodes(g._nodes[:10])
        .edges(g._edges[:10])
    )

g2 = g1.upload()
g3 = g2.python_remote_g(my_remote_trim_graph_task)

  • 运行远程Python并返回一个表格

    def first_n_edges(g):
    return g._edges[:10]

some_edges_df = g.python_remote_table(first_n_edges)

  • 运行远程Python并获取JSON返回

    def first_n_edges(g):
    return g._edges[:10].to_json()

some_edges_json = g.python_remote_json(first_n_edges)

  • 运行远程Python并确保在CPU或GPU上运行

    g3a = g2.python_remote_g(my_remote_trim_graph_task, engine='pandas')
g3b = g2.python_remote_g(my_remote_trim_graph_task, engine='cudf')

  • 运行远程Python，以字符串形式传递

    g2 = g1.upload()

# ensure method is called "task" and takes a single argument "g"
g3 = g2.chain_remote_python("""
    def task(g):
        return (g
            .nodes(g._nodes[:10])
            .edges(g._edges[:10])
        )
    my_remote_trim_graph_task(g)
""")

高级用法#

  • 使用源节点和目标节点过滤器及查询进行遍历：

    e_forward(
    edge_query="type == 'follows' and weight > 2",
    source_node_match={"status": "active"},
    destination_node_query="age < 30",
    hops=2,
    name="social_edges"
)

  • 带有所有参数的节点匹配器：

    n(
    filter_dict={"department": "sales"},
    query="age > 25 and tenure > 2",
    name="experienced_sales"
)

  • 带有所有参数的边缘匹配器：

    e_reverse(
    edge_match={"transaction_type": "refund"},
    edge_query="amount > 100",
    source_node_match={"status": "inactive"},
    destination_node_match={"region": "EMEA"},
    name="large_refunds"
)

参数摘要#

  • 常见参数：

    • filter_dict: 属性过滤器（例如，{“status”: “active”}）

    • query: 自定义查询字符串（例如，“age > 30”）

    • hops: 遍历的步数 (int, 默认 1)

    • to_fixed_point: 继续遍历直到没有更多匹配项 (bool, 默认 False)

    • name: 匹配器的标签 (str)

    • source_node_match, destination_node_match: 连接节点的过滤器

    • source_node_query, destination_node_query: 用于连接节点的查询

    • edge_match: 边的过滤器

    • edge_query: 查询边

    • engine: 执行引擎 (EngineAbstract.AUTO, ‘cudf’, 等)

遍历方向#

  • 前向遍历： e_forward(…)

  • 反向遍历： e_reverse(…)

  • 无向遍历： e_undirected(…)

提示和最佳实践#

  • 限制跳数以提升性能： 指定 hops 来控制遍历深度。

  • 使用命名进行分析： 应用 name 来标记和过滤结果。

  • 组合过滤器： 使用 filter_dict 和 query 进行精确匹配。

  • 利用GPU加速： 对于大型数据集，使用engine=’cudf’。

  • 避免无限循环：在循环图中使用to_fixed_point=True时要小心。

示例概览#

  • 查找两个节点之间的所有路径：

    g.chain([
    n({g._node: "Alice"}),
    e_undirected(hops=3),
    n({g._node: "Bob"})
])

  • 匹配ID在一定范围内的节点：

    n(query="100 <= id <= 200")

  • 遍历具有特定标签的边：

    e_forward({"label": is_in(["knows", "likes"])})

  • 基于属性识别子图：

    g.chain([
    n({"community": "A"}),
    e_undirected(hops=2),
    n({"community": "B"}, name="bridge_nodes")
])

  • 自定义边和节点查询：

    g.chain([
    n(query="age >= 18"),
    e_forward(edge_query="interaction == 'message'"),
    n(query="location == 'NYC'")
])