---
title: Core concepts of Tinybird
meta:
    description: Learn the core concepts of Tinybird, how it works, and how to use it.
---

# Core concepts of Tinybird

Tinybird gives you the tooling and infrastructure you need to ship analytics features in your application:

- An OLAP database (ClickHouse®)
- An API gateway
- A real-time ingestion system
- An auth system
- Tooling to build, iterate, and deploy data projects

Tinybird is built around several core concepts that abstract the underlying infrastructure and data storage. To make the most of Tinybird, it's important to understand these core concepts.

## Develop anywhere, deploy to Tinybird Cloud

Tinybird is a platform for building analytics features in your application. You can build with:

- Tinybird CLI (datafiles)
- TypeScript SDK (typed resources)

There are three main environments: Tinybird Cloud for production workloads, Tinybird Local for local development, and Tinybird Branches for shared preview environments.

- Tinybird Cloud is the hosted platform (see available [regions](api-reference#regions-and-endpoints)) where your production workspace lives.
- Tinybird Local is a local runtime for development and testing.
- Tinybird Branches are cloud environments for development, collaboration, and pre-production validation.

The typical workflow is as follows:

1. Define your resources using [datafiles](/forward/dev-reference/datafiles) or the TypeScript SDK.
2. Iterate and test [locally](/forward/test-and-deploy/local) or in [branches](/forward/test-and-deploy/branches).
3. [Deploy your data project](/forward/test-and-deploy/deployments) to Tinybird Cloud so your endpoints and ingest pipelines are live. Strongly recommended via [CI/CD](/forward/test-and-deploy/deployments/cicd).
4. Use [Tinybird Cloud](https://cloud.tinybird.co) to inspect data, manage deployments, and monitor usage.

The following diagram illustrates the development and usage flow, from local development or branches to deployment in Tinybird Cloud.

```mermaid
flowchart LR
    subgraph git[Git repository]
        data[Data project]
    end

    subgraph tools[Interfaces]
        cli[Tinybird CLI]
        sdk[TypeScript SDK]
    end

    subgraph dev[Development & testing]
        local[Tinybird Local]
        branch[Tinybird Branches]
    end

    subgraph cloud[Production]
        workspace[Tinybird Cloud Workspace]
    end

    data <--> tools
    tools --> local
    tools --> branch
    data -->|Deploy| workspace
```

## Your projects live in workspaces

A [workspace](/forward/administration/workspaces) contains the resources, data, and state of your Tinybird project. You can have as many workspaces as you need and invite users to collaborate.

At a minimum, a workspace contains a data source (a database table). You write data to it and read data from it. The following diagram illustrates the relationship between resources in a workspace.

```mermaid
flowchart LR
    subgraph Connect
        api[Events API]
        kafka[Kafka]
        storage[Cloud storage]
    end

    subgraph workspace[Workspace]
        direction LR
        connector[Connector]
        source[Data source]
        pipe[Pipe]

        subgraph optim[Optimizations]
            view[Materialized view]
            copy[Copy data source]
        end

        subgraph consume[Consume, query, expose]
            endpoint[API Endpoint]
            ch[ClickHouse interface]
            mcp[MCP server]
            sink[Sink]
        end
    end

    storage_out[Cloud storage]

    api --> source
    kafka --> connector --> source
    storage --> connector --> source
    source --> pipe
    pipe --> view
    pipe --> copy
    pipe --> endpoint
    pipe --> ch
    pipe --> mcp
    source --> ch
    source --> mcp
    pipe --> sink
    sink --> storage_out
    endpoint --> apps[Applications]
    mcp --> apps
    endpoint --> agents[Agents]
    mcp --> agents
    ch --> bi[BI tools]
```

## Data enters through data sources

Data sources are where you ingest and store data in Tinybird. All your data lives inside a data source, and you write SQL queries against data sources. You can bulk upload or stream data into a data source.

You can bring data in from the following sources:

- Events sent to the [Events API](/forward/get-data-in/events-api).
- Events streamed from Kafka. See [Ingest data from Kafka](/forward/get-data-in/connectors/kafka).
- Files in your local file system. See [Ingest data from files](/forward/get-data-in/local-file).
- Files in your cloud storage bucket. See [Connectors](/forward/get-data-in/connectors).

Data sources are defined in .datasource files. See [Datasource files](/forward/dev-reference/datafiles/datasource-files) for more information.

## Use pipes to process your data

Pipes are how you write SQL logic in Tinybird. They're a collection of one or more SQL queries chained together, or nodes. Pipes let you break larger queries down into smaller queries that are easier to read.

With pipes you can:

- Publish API Endpoints.
- Create optimized Data sources via Materializations or Copy Pipes.
- Send data to Cloud Storage via Sinks.
- Create Views.

[Pipes](/forward/work-with-data/pipes) are defined in .pipe files. See [Pipe files](/forward/dev-reference/datafiles/pipe-files) for more information.

## Outputs are where your data goes

When your data is ready to be consumed, you can publish it through API Endpoints, the ClickHouse interface, or the MCP server.

The following output is available:

- [API endpoints](/forward/work-with-data/publish-data/endpoints), which you can call using custom parameters from any application.
- [ClickHouse interface](/forward/work-with-data/publish-data/clickhouse-interface) for SQL clients and BI tools.
- [MCP server](/forward/analytics-agents/mcp) for agent and tool integrations.

Endpoints are defined in .pipe files. See [Pipe files](/forward/dev-reference/datafiles/pipe-files) for more information.

## Tokens protect your data

[Tokens](/forward/administration/tokens) are how you authenticate and control access to your Tinybird resources. Without tokens, nobody can send data to your data sources or query your endpoints.

There are two types of tokens:

- **[Static tokens](/forward/administration/tokens/static-tokens)**: Permanent tokens for backend integrations. Use them to send data, manage resources via CLI, or read data directly from your backend applications.
- **[JSON Web Tokens, JWTs](/forward/administration/tokens/jwt)**: Short-lived tokens. Use them to create individual tokens per user that needs to call Tinybird endpoints, with optional filtering and rate limiting per user.

When you create a workspace, Tinybird automatically creates default tokens for you, including:

- **Workspace admin token**: Full access to everything in your workspace
- **Your personal admin token**: Stored in your `.tinyb` file when you run `tb login`

For development, you can use these admin tokens. For production, create specific tokens with limited permissions (scopes) for security.

### Token workflow

1. **Development**: Use admin tokens to build and test your project locally
2. **Production**: Create resource-specific tokens with minimal required permissions
3. **Frontend access**: Generate JWTs from your backend for browser-based queries

See [Tokens](/forward/administration/tokens) for detailed token management.

## To go live, promote a deployment

After you develop your project, you can deploy it to Tinybird Cloud. This creates a deployment, which is a version of your project resources and data running on local or cloud infrastructure.

When you're ready to go live, you can promote your deployment in Tinybird Cloud. This makes your deployment available to your users. In other words, the deployment is live.

See [Deployments](/forward/test-and-deploy/deployments) for more information.

## Monitor with service data sources

Tinybird exposes built-in data sources for monitoring usage and performance:

- **`tinybird.*` service data sources** for workspace-level metrics and logs.
- **`system.*` tables** for ClickHouse system-level insights.
- **`organization.*` service data sources** for org-wide usage and billing signals.

See [Service data sources](/forward/monitoring/service-datasources) and [Organizations](/forward/administration/organizations) for details.