# Subgraphs in Pipeline Builder

The subgraph feature in Pipeline Builder lets you package one or more transforms into a reusable block. You can then apply that block anywhere in a pipeline without rebuilding the logic each time. Each place you apply a subgraph is an instance of it. Subgraphs offer several benefits:

* **Reuse logic:** Package complex logic and apply it across multiple locations in your pipeline or across branches.
* **Reduce duplication:** Update a subgraph once to affect all its instances.
* **Simplify pipelines:** Replace long chains of nodes with a single subgraph node, making graphs easier to read and maintain.

![The pipeline graph shows Classes, Grades, and Students connected to a subgraph whose outputs feed datasets for class popularity, teacher popularity, and class rank.](../../../assets/b6cc64d794a3f7ba527f499e50515fdafdb6e3ae4d900e209e80eb520fc276df.webp)

This guide covers how to:

* [Create a new subgraph from scratch](#create-a-new-subgraph-from-scratch)
* [Create a subgraph from existing nodes](#create-a-subgraph-from-existing-nodes)
* [Add a subgraph to your pipeline](#add-a-subgraph-to-your-pipeline)

## Create a new subgraph from scratch

You create and manage subgraphs from the **Reusables** menu.

1. In Pipeline Builder, open the pipeline in which you want to define the subgraph.

2. At the top of the graph, select **Reusables**, then select **Subgraphs**.

   ![The Reusables menu is expanded in Pipeline Builder with the Subgraphs option highlighted.](../../../assets/dfbaf88d5366eef5fd7686b94e570fd4524a38dad8a855f04076697073f796ac.webp)

3. In the **Subgraphs** window, select **Add custom subgraph**.

   ![The Subgraphs window lists existing subgraphs with the Add custom subgraph button highlighted.](../../../assets/92665c1a5ee304e1af11c57100ace289b052d535ac6fdc96d56951b6a5f01b65.webp)

### Configure the subgraph inputs

:::callout{theme="neutral"}
Inputs in the subgraph editor work differently from inputs in the main Pipeline Builder graph. A subgraph input defines the columns the subgraph requires. An empty subgraph input is valid and means no columns are required. If your subgraph requires columns, you must map each one to a compatible column in the main graph when you apply the subgraph to your pipeline.
:::

1. Select the **Inputs** tab in the top left to manage inputs, or select **Add input** in the center of the screen to add a node input.

   ![The empty subgraph editor shows the Inputs tab and Add input button highlighted.](../../../assets/b396b90ebe470f33c6e5d7801e20352f4c03336e3a58de5e333d547dc2fc9d29.webp)

2. To add a node input, select **+** next to **Nodes**. To add a parameter input, select **+** next to **Parameters**.

   ![The subgraph inputs panel shows the Nodes and Parameters sections highlighted.](../../../assets/298efd84bb669da1b47b5c7bd69f8393e95f6f5f1d73bbe906acb993475bc353.webp)

#### Node inputs

1. Select an input type of **Files** or **Table** from the dropdown menu.

   ![The subgraph input type dropdown menu is expanded with Files and Table options, and the input type selector is highlighted.](../../../assets/b6d9e306050fc6b19b7bf4389ec38e9dd393b79da93337de2c6414cfc8993d64.webp)

2. To add a schema, either copy required columns from an existing dataset using the **From dataset** button or manually add columns using the **Add column** button.

   ![The subgraph input schema panel shows the From dataset and Add column buttons highlighted.](../../../assets/f7b61e0b0f448afea4f54df19e3ef94d818845d32182c85f2c11823dcd66d5d5.webp)

#### Parameter inputs

Parameter inputs are defined in the reusable subgraph and let each instance supply its own configuration values. Reference a parameter in a compatible transform field inside the subgraph, then configure its value when adding or editing an instance.

To configure a parameter input, select a parameter type from the first dropdown menu. Additional fields vary by the selected parameter type but can include **Element type** and **Type**.

![The highlighted parameter input configuration shows List selected with Column as the element type and String as the data type.](../../../assets/b44f060c44949f3d669a9bb978e8b9eadca3fae3dd4331751ba7b724b63ad23b.webp)

### Build the subgraph logic

With inputs defined, you can build the subgraph logic like you would in the main graph view:

1. From the input node, add transforms, splits, joins, and other logic.
2. Create an output node at the end of your transform path using **New output**.
3. Check that all expected outputs are listed in the **Outputs** tab in the subgraph editor.

![The subgraph editor shows the input node menu expanded with options to add transforms, splits, joins, unions, LLM transforms, and outputs.](../../../assets/e90fcf3d804fbab050e7322a65157b51f6dd5ed246073fd9c02882a36c7172d4.webp)

When you are done, enter a clear name in the subgraph name field in the top left, then select **Apply all** in the top right. Select **Close** to exit the subgraph editor. Your subgraph is now available in the **Reusables** menu.

![The Demo Subgraph editor shows the Apply all button highlighted in the top right.](../../../assets/47bfff6d88e0ecfef9fecb2db841c20998836f694bd41d2b4a9302f8db2a12c4.webp)

## Create a subgraph from existing nodes

You might already have a sequence of nodes that you want to reuse. You can package those nodes into a new subgraph.

### Select the nodes to package

1. In your main pipeline, select the nodes you want to package. For example, you might select a join, sort, and aggregation sequence.

2. Right-click the selection and select **Subgraphs**.

3. To package the nodes into a new subgraph, select **Create subgraph**.

   ![The selected pipeline nodes have a context menu open with the Subgraphs menu expanded and Create subgraph highlighted.](../../../assets/fc7ccbf5bef0e1808e23c036a1b2424841f137db5652061e5af899f1af48d97e.webp)

4. A new subgraph editor opens containing the selected nodes, with input schemas already populated.

   ![The subgraph editor shows the selected transforms connected to three automatically created node inputs and three output nodes.](../../../assets/c029854e122427cafc9f2c3500073745f025bdfb624c59bd05e4c0760360d59f.webp)

5. When the subgraph is valid and no schema errors appear, select **Apply all**, then select **Close** to exit the subgraph editor.

   ![The Demo Subgraph editor shows the Apply all button highlighted in the top right.](../../../assets/47bfff6d88e0ecfef9fecb2db841c20998836f694bd41d2b4a9302f8db2a12c4.webp)

6. Next, map your inputs in the main Pipeline Builder graph view.

   ![The highlighted node input mapping section lists Classes, Grades, and Students, with node selection active for Classes.](../../../assets/162005208f09734879c9a813fd1801ee8bbe5d3b27571963763eb7914f6c94f3.webp)

7. After you map your inputs, select **Start** in the top right of the mapping view. Then select **Apply** in the configuration view. If the subgraph has no parameter inputs, the configuration view shows `No parameters to configure`.

   ![The subgraph instance shows Classes, Grades, and Students mapped to node inputs with the Apply button highlighted.](../../../assets/d33cf19642a10cf08782b6fb1ad79044368aaef50f8677fda164eb8784a2b4a2.webp)

:::callout{theme="warning"}
If any required inputs are missing, schema errors appear in the **Errors** tab and on the pipeline graph.
:::

![The Classes input has no node mapped, and the output preview shows the highlighted Missing 1 input message.](../../../assets/85976f2617ffde74da25d7b0083f1cf42bad55167f929662c2493f2d42aac68d.webp)

## Add a subgraph to your pipeline

You can add an existing subgraph to your pipeline or use it to replace selected transforms.

### Apply a subgraph to selected nodes

1. Select the source node or nodes for your subgraph.
2. In the toolbar, select the **Apply subgraph to table** icon.
3. Choose the subgraph you want to add to your pipeline.

![The Apply subgraph to table icon is highlighted in the Pipeline Builder toolbar, and the subgraph selection menu is open.](../../../assets/d33909ab3f324cff4fdc7ed48dad7ce2246a88963bed60f3b23a2ff0a2ef284c.webp)

### Replace selected transforms with a subgraph

For **Replace with subgraph** to be enabled, every selected node must be a transform.

1. Select the transforms you want to replace, then right-click the selection and select **Subgraphs** > **Replace with subgraph**.
2. Choose an existing subgraph, map its node inputs to nodes in the pipeline, and select **Start**.
3. In the configuration view, configure any parameter inputs, then select **Apply** to replace the selected transforms.

![The selected transform nodes have a context menu open with the Subgraphs menu expanded and Replace with subgraph highlighted.](../../../assets/f21f4f6b41f2bdd725ff9b6c7274bde03be4a83051355fcb01fd49f5ea17e4d2.webp)