Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/procedures/subgraph/
Documentation version: v5.3.2

# 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/show-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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/call/call-procedure/).