Last update: 2025-08-06T11:23:32.000Z
Content:
---
title: "Pipe files · Tinybird Docs"
theme-color: "#171612"
description: "Pipe files describe your Tinybird pipes. Define the type, data source, and other settings."
inkeep:version: "forward"
---




# Pipe files (.pipe) [¶](https://www.tinybird.co/docs/forward/dev-reference/datafiles/pipe-files#pipe-files-pipe)

Copy as MD Pipe files describe your pipes. You can use .pipe files to define the type, starting node, data source, and other settings of your pipes.




## Nodes [¶](https://www.tinybird.co/docs/forward/dev-reference/datafiles/pipe-files#nodes)

A node is a container for a single SQL `SELECT` statement. Nodes live within pipes, and you can have many sequential nodes inside the same pipe. They allow you to break your query logic down into multiple smaller queries. You can then chain nodes together to build the logic incrementally.

A query in a node can read data from a data source, other nodes inside the same pipe, or from endpoint nodes in other pipes. Each node can be developed and tested individually. This makes it much easier to build complex query logic in Tinybird as you avoid creating large monolithic queries with many subqueries.

## Available instructions [¶](https://www.tinybird.co/docs/forward/dev-reference/datafiles/pipe-files#available-instructions)

The following instructions are available for .pipe files.

| Instruction | Required | Description |
| --- | --- | --- |
| `%` | No | Use as the first character of a node to indicate the node uses the[  templating system](/docs/forward/dev-reference/template-functions)  . |
| `DESCRIPTION <markdown_string>` | No | Sets the description for a node or the complete file. |
| `TAGS <tag_names>` | No | Comma-separated list of tags. |
| `NODE <node_name>` | Yes | Starts the definition of a new node. All the instructions until a new `NODE`   instruction or the end of the file are related to this node. |
| `SQL <sql>` | Yes | Defines a block for the SQL of a node. The block must be indented. |
| `TYPE <pipe_type>` | No | Sets the type of the pipe. Valid values are `ENDPOINT`  , `MATERIALIZED`  , `COPY`   , or `SINK`  . |
| `DATASOURCE <data_source_name>` | Yes | Required when `TYPE`   is `MATERIALIZED`   . Sets the destination data source for materialized nodes. |
| `TARGET_DATASOURCE <data_source_name>` | Yes | Required when `TYPE`   is `COPY`   . Sets the destination data source for copy nodes. |
| `TOKEN <token_name> READ` | No | Grants read access to a pipe or endpoint to the token named <token_name>. If the token isn't specified or <token_name> doesn't exist, it will be automatically created. |
| `COPY_SCHEDULE` | No | Cron expression with the frequency to run copy jobs. Must be higher than 5 minutes. For example, `*/5 * * * *`   . If undefined, it defaults to `@on-demand`  . |
| `COPY_MODE` | No | Strategy to ingest data for copy jobs. One of `append`   or `replace`   . If empty, the default strategy is `append`  . |
| `DEPLOYMENT_METHOD <method>` | No | Deployment method for materialized views. Use `alter`   to update existing materialized views using `ALTER TABLE ... MODIFY QUERY`   instead of recreating the table. Only valid for `TYPE MATERIALIZED`  . |

## Endpoint pipes [¶](https://www.tinybird.co/docs/forward/dev-reference/datafiles/pipe-files#endpoint-pipes)

In a .pipe file you can define how to export the result of a pipe as an HTTP endpoint.

The following example shows how to describe an endpoint pipe. See [Endpoints](/docs/forward/work-with-data/publish-data/endpoints).

##### tinybird/pipes/sales_by_hour_endpoint.pipe

TOKEN dashboard READ
DESCRIPTION endpoint to get sales by hour filtering by date and country

TAGS sales

NODE daily_sales
SQL >
    %
    SELECT day, country, sum(total_sales) as total_sales
    FROM sales_by_hour
    WHERE
    day BETWEEN toStartOfDay(now()) - interval 1 day AND toStartOfDay(now())
    and country = {{ String(country, 'US')}}
    GROUP BY day, country

NODE result
SQL >
    %
    SELECT * FROM daily_sales
    LIMIT {{Int32(page_size, 100)}}
    OFFSET {{Int32(page, 0) * Int32(page_size, 100)}}
TYPE ENDPOINT
## Materialized pipes [¶](https://www.tinybird.co/docs/forward/dev-reference/datafiles/pipe-files#materialized-pipes)

In a .pipe file you can define how to materialize each row ingested in the earliest data source in the pipe query to a materialized data source. Materialization happens at ingest. See [Materialized views](/docs/forward/work-with-data/optimize/materialized-views).

The following example shows how to describe a materialized pipe.

##### tinybird/pipes/sales_by_hour_mv.pipe

DESCRIPTION Materialized pipe to aggregate sales per hour in the sales_by_hour data source

NODE daily_sales
SQL >
    SELECT toStartOfDay(starting_date) day, country, sum(sales) as total_sales
    FROM teams
    GROUP BY day, country

TYPE MATERIALIZED
DATASOURCE sales_by_hour
### Using ALTER deployment method [¶](https://www.tinybird.co/docs/forward/dev-reference/datafiles/pipe-files#using-alter-deployment-method)

When updating an existing materialized view, you can use `DEPLOYMENT_METHOD alter` to modify the query without recreating the table:

##### tinybird/pipes/sales_by_hour_mv.pipe

DESCRIPTION Updated materialized pipe with additional metrics

NODE daily_sales
SQL >
    SELECT 
        toStartOfDay(starting_date) day, 
        country, 
        sum(sales) as total_sales,
        avg(sales) as avg_sales,
        count(*) as transaction_count
    FROM teams
    GROUP BY day, country

TYPE MATERIALIZED
DATASOURCE sales_by_hour
DEPLOYMENT_METHOD alter The `DEPLOYMENT_METHOD alter` directive tells Tinybird to use `ALTER TABLE ... MODIFY QUERY` instead of dropping and recreating the materialized view. This preserves existing data and reduces deployment time. See [Altering materialized views](/docs/forward/work-with-data/optimize/materialized-views#altering-materialized-views) for more details.

## Copy pipes [¶](https://www.tinybird.co/docs/forward/dev-reference/datafiles/pipe-files#copy-pipes)

In a .pipe file you can define how to export the result of a pipe to a data source, optionally with a schedule. See [Copy pipes](/docs/forward/work-with-data/optimize/copy-pipes).

The following example shows how to describe a copy pipe.

##### tinybird/pipes/sales_by_hour_cp.pipe

DESCRIPTION Copy pipe to export sales hour every hour to the sales_hour_copy data source

NODE daily_sales
SQL >
    %
    SELECT toStartOfDay(starting_date) day, country, sum(sales) as total_sales
    FROM teams
    WHERE
    day BETWEEN toStartOfDay(now()) - interval 1 day AND toStartOfDay(now())
    and country = {{ String(country, 'US')}}
    GROUP BY day, country

TYPE COPY
TARGET_DATASOURCE sales_hour_copy
COPY_SCHEDULE 0 * * * *
## Sink Pipes [¶](https://www.tinybird.co/docs/forward/dev-reference/datafiles/pipe-files#sink-pipes)

In a .pipe file you can define how to export the result of a pipe to an external source, optionally with a schedule. See [Sink pipes](/docs/forward/work-with-data/publish-data/sinks).

The following parameters are available when defining Sink Pipes:

| Instruction | Required | Description |
| --- | --- | --- |
| `EXPORT_CONNECTION_NAME` | Yes | The name of the export connection. |
| `EXPORT_SCHEDULE` | No | Cron expression, in UTC time. Must be higher than 5 minutes. For example, `*/5 * * * *`  . |

### Blob storage Sink [¶](https://www.tinybird.co/docs/forward/dev-reference/datafiles/pipe-files#blob-storage-sink)

When using a S3 or GCS connection, you can use the following instructions:

| Instruction | Required | Description |
| --- | --- | --- |
| `EXPORT_BUCKET_URI` | Yes | The desired bucket path for the exported file. Path must not include the filename and extension. |
| `EXPORT_FILE_TEMPLATE` | Yes | Template string that specifies the naming convention for exported files. The template can include dynamic attributes between curly braces based on columns' data that will be replaced with real values when exporting. For example: `export_{category}{date,'%Y'}{2}`  . |
| `EXPORT_FORMAT` | Yes | Format in which the data is exported. The default value is `csv`  . |
| `EXPORT_COMPRESSION` | No | Compression file type. Accepted values are `none`  , `gz`   for gzip, `br`   for brotli, `xz`   for LZMA, `zst`   for zstd. Default values is `none`  . |
| `EXPORT_STRATEGY` | Yes | One of the available strategies. The default is `@new`  . |

### Kafka Sink [¶](https://www.tinybird.co/docs/forward/dev-reference/datafiles/pipe-files#kafka-sink)

When using a `kafka` connection, you can use the following instructions:

| Instruction | Required | Description |
| --- | --- | --- |
| `EXPORT_KAFKA_TOPIC` | Yes | The desired topic for the export data. |


