Tinybird Python SDK Guidelines

What Is This?

Overview

The Tinybird Python SDK is a developer-focused package that allows engineers to define, configure, and interact with Tinybird resources directly in Python code. Rather than relying solely on the Tinybird CLI or web interface, the SDK provides a programmatic approach to managing datasources, pipes, and query endpoints within Python projects. This makes it straightforward to integrate Tinybird's real-time analytics capabilities into existing Python workflows and applications.

The tinybird-sdk package follows a code-first philosophy, meaning that datasource schemas, pipe transformations, and API endpoints can all be declared as Python objects. This approach brings the benefits of version control, code review, and automated testing to Tinybird resource management. Developers can define their entire data pipeline configuration alongside their application code, keeping infrastructure and logic in one place.

The SDK also provides a client interface for executing queries and ingesting data programmatically. Whether you are building a data ingestion service, automating pipeline deployments, or running analytical queries from within a Python application, the SDK covers these interactions with a consistent and well-structured API.

Who Should Use This

• Backend engineers building data ingestion pipelines in Python who need to push events or records into Tinybird datasources
• Data engineers managing Tinybird resources programmatically and wanting to define schemas and pipes as code
• Platform teams automating Tinybird deployments as part of CI/CD pipelines
• Analytics engineers who prefer Python-based configuration over YAML or CLI-driven workflows
• Application developers embedding real-time query results from Tinybird into Python services or APIs
• Teams adopting infrastructure-as-code practices who want Tinybird resources versioned alongside application code

Why Use It?

Problems It Solves

• Manual resource creation through the Tinybird UI is error-prone and difficult to reproduce across environments, the SDK enables consistent, repeatable definitions in code
• Integrating Tinybird data ingestion into Python applications without the SDK requires raw HTTP calls and manual authentication handling, which adds unnecessary complexity
• Managing datasource schemas and pipe logic separately from application code creates drift and makes deployments harder to coordinate
• Testing and validating Tinybird configurations before deployment is difficult without a programmatic interface that can be incorporated into automated test suites

Core Highlights

• Define datasources with explicit column schemas directly in Python classes
• Create and configure pipes and endpoints as code objects
• Instantiate a Tinybird client with token-based authentication in a few lines
• Send data to datasources using the client's ingestion methods
• Execute SQL queries against Tinybird pipes and retrieve results programmatically
• Supports environment-based configuration for managing multiple Tinybird workspaces
• Integrates naturally with Python packaging, testing frameworks, and CI/CD tooling
• Reduces context switching by keeping Tinybird resource definitions inside the Python project

How to Use It?

Basic Usage

Install the package using pip:

pip install tinybird-sdk

Create a Tinybird client by providing your API token and host:

from tinybird.client import TinybirdClient

client = TinybirdClient(token="your_api_token", host="https://api.tinybird.co")

Specific Scenarios

Defining a Datasource

Declare a datasource schema as a Python object, specifying column names and types:

from tinybird.resource import Datasource, Column

events_datasource = Datasource(
    name="user_events",
    columns=[
        Column(name="event_id", type="String"),
        Column(name="user_id", type="UInt64"),
        Column(name="timestamp", type="DateTime"),
        Column(name="event_type", type="String"),
    ]
)

Ingesting Data

Send records to an existing datasource using the client:

records = [
    {"event_id": "abc123", "user_id": 42, "timestamp": "2024-01-15 10:00:00", "event_type": "click"}
]

client.datasource("user_events").append(records)

Real-World Examples

A backend service tracking user activity can call client.datasource("user_events").append(records) after each request, keeping Tinybird updated in near real time without manual HTTP construction.

A deployment script can iterate over a list of datasource and pipe definitions, calling the SDK to create or update each resource, ensuring the Tinybird workspace matches the codebase on every release.

When to Use It?

Use Cases

• Automating Tinybird datasource and pipe creation as part of application bootstrapping
• Building event tracking services that ingest data into Tinybird from Python backends
• Running scheduled analytical queries against Tinybird pipes from Python scripts or jobs
• Validating Tinybird resource configurations in automated test pipelines before deployment
• Migrating Tinybird resource definitions from manual UI setup into version-controlled Python code
• Integrating Tinybird query results into Python-based dashboards or reporting tools
• Managing multi-environment Tinybird workspaces through code-driven configuration

Important Notes

Requirements

• Python 3.8 or higher is required to install and use the tinybird-sdk package
• A valid Tinybird account and API token with appropriate workspace permissions are necessary
• Network access to the Tinybird API host must be available from the environment running the SDK