Subgraph procedure (algo.subgraph)

algo.subgraph is a built-in named procedure provided by the official algo plugin. It extracts a subgraph from a persistent graph with multi-source BFS traversal. You can control source nodes, traversal depth, edge types, direction, and property filters on both edges and nodes.

KILL QUERY cannot promptly stop a running algo.subgraph procedure. The BFS loop continues in the background until the traversal ends naturally, either by reaching the maximum traversal depth or by having no nodes left to expand.

Use cases

• Extract a local subgraph from one or more source nodes by hop count.
• Restrict traversal to specific edge types.
• Apply edge and node property filters during traversal.

Prerequisites

• The algo plugin must be loaded into the current catalog. The plugin is not loaded automatically when the services start. Before the first use, run the following statement as a user with the ADMIN role:

  CREATE PLUGIN IF NOT EXISTS algo
  

  After loading the plugin, run SHOW PLUGIN algo to check its status. Call algo.subgraph after plugin_status is Valid on all relevant services. For details about the status fields, see SHOW PLUGIN / PLUGINS.

• The graph_name passed to algo.subgraph must be an existing persistent graph (created via CREATE GRAPH).

How it works

When steps is 0, algo.subgraph performs no expansion. It directly returns the source nodes that exist and returns no edges.

When steps is greater than 0, algo.subgraph performs at most the following BFS phases:

• The first steps phases expand normally from the source nodes, discovering new nodes and edges at each hop.
• If the steps-th phase discovers new nodes, one additional phase finds edges between already visited nodes without discovering more nodes.

The traversal ends early if no nodes remain to be expanded after a phase.

This produces a closed subgraph where every edge has both endpoints within the visited node set.

Procedure signature

algo.subgraph(
  graph_name STRING,
  src_ids LIST<INT64>,
  steps UINT64,
  edge_types LIST<STRING>,
  direction STRING,
  edge_filters LIST<STRING>,
  node_filters LIST<STRING>
)

At least 3 arguments are required. The last 4 arguments are optional.

Parameters

Parameter	Required	Description
graph_name	Yes	Existing graph name in the catalog.
src_ids	Yes	Source node element ID list (must be INT64). Must not be empty. Duplicate IDs are deduplicated automatically.
steps	Yes	Maximum traversal depth. 0 means no expansion and returns source nodes only (if they exist).
edge_types	No	Edge types allowed for traversal. Omit or pass an empty list to include all edge types.
direction	No	Traversal direction: outgoing, incoming, or bidirect. Default is bidirect.
edge_filters	No	Edge property filter expressions. Multiple filters are combined with AND logic.
node_filters	No	Node property filter expressions applied to newly discovered nodes. Multiple filters are combined with AND logic. Source nodes are not filtered. A node that does not pass the filters is not expanded further, and its incident edges are omitted from the result.

Important

src_ids expects internal node element IDs (from element_id(v)), not business property values such as v.id.

Filter expressions

Each item in edge_filters and node_filters must be a string containing a simple property-to-constant comparison. Supported operators are =, <>, >, <, >=, and <=. For example: "weight >= 2", "age <= 30".

Note

Each filter expression can only contain one comparison in the form property operator value (such as "weight >= 2"). Boolean composition (AND/OR) within a single expression and type-qualified properties (e.g., Person.age <= 30) are not supported. To apply multiple conditions, pass them as separate items in the list (such as ["weight >= 2", "age <= 30"]).

Return columns

The procedure returns two columns:

• nodes: LIST<NODE>, extracted nodes.
• edges: LIST<EDGE>, extracted edges.

Examples

The following examples are based on the example dataset.

Example 1: Minimal call (default bidirectional, all edge types)

'''
USE movie
MATCH (v@Movie) WHERE v.id = 1
RETURN [element_id(v)] AS ids
NEXT
USE movie
CALL algo.subgraph("movie", ids, CAST(1 AS UINT64))
YIELD nodes, edges
RETURN size(nodes) AS node_count, size(edges) AS edge_count
'''

Return:

+------------+------------+
| node_count | edge_count |
+------------+------------+
| 43         | 42         |
+------------+------------+

Example 2: Traverse 2 hops on outgoing WithGenre edges

'''
USE movie
MATCH (v@Movie) WHERE v.id = 1
RETURN [element_id(v)] AS ids
NEXT
USE movie
CALL algo.subgraph("movie", ids, CAST(2 AS UINT64), ["WithGenre"], "outgoing")
YIELD nodes, edges
RETURN size(nodes) AS node_count, size(edges) AS edge_count
'''

Return:

+------------+------------+
| node_count | edge_count |
+------------+------------+
| 23         | 22         |
+------------+------------+

Example 3: Edge filter + node filter

'''
USE movie
MATCH (v@Movie) WHERE v.id >= 1 AND v.id <= 10
RETURN [element_id(v)] AS ids
NEXT
USE movie
CALL algo.subgraph(
  "movie",
  ids,
  CAST(3 AS UINT64),
  ["Watch"],
  "incoming",
  ["id >= 10"],
  ["rate < 5"]
)
YIELD nodes, edges
RETURN size(nodes) AS node_count, size(edges) AS edge_count
'''

Return:

+------------+------------+
| node_count | edge_count |
+------------+------------+
| 1          | 0          |
| 1          | 0          |
| 1          | 0          |
| 1          | 0          |
| 1          | 0          |
+------------+------------+

For general CALL syntax, see CALL named procedures.