Core concepts of Tinybird

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

  • An OLAP database
  • 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 locally, deploy remotely

Tinybird is a platform for building analytics features in your application. It's comprised of the following components:

  • Tinybird CLI, a command-line tool to build, iterate, and deploy data projects.
  • Tinybird Local, a Docker container that runs a local deployment of Tinybird.
  • Tinybird Cloud, the web interface to manage your Tinybird deployment.

The typical workflow is as follows:

  1. You develop your data project locally using Tinybird Local and version control.
  2. Changes are iterated and tested locally before anything is deployed in Tinybird Cloud.
  3. When you're ready, you deploy your data project to Tinybird Cloud, which enables your resources to be used by your application. Ingestion and queries are enabled in the deployment.
  4. In Tinybird Cloud you can browse and query your data, check observability, and more.

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

Your projects live in workspaces

A workspace contains the resources, data, and state of your Tinybird project. You can have as many workspaces as you need and invite users to collaborate.

Each workspace contains, at a minimum, a source of data, a processing resource, and an output destination. The following diagram illustrates the relationship between resources in a workspace.

Data enters through data sources

Data sources are how 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:

  • Files in your local file system.
  • Files in your cloud storage bucket.
  • Events sent to the Events API.
  • Events streamed from Kafka.

Data sources are defined in .datasource files. See 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:

  • Process data in nodes.
  • Publish API endpoints.
  • Create materialized views.
  • Create copies of data.

Pipes are defined in .pipe files. See Pipe files for more information.

Outputs are where your data goes

When your processed data is ready to be consumed by your application, you can publish it through API endpoints.

The following output is available:

  • API endpoints, which you can call using custom parameters from any application.

Endpoints are defined in .pipe files. See Pipe files for more information.

Tokens protect your data

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: Permanent tokens for backend integrations. Use them to send data, manage resources via CLI, or read data directly from your backend applications.
  • JWT tokens: 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 for detailed token management.

To go live, promote a deployment

After you develop your project, you can deploy it to Tinybird Local or 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 for more information.

Updated