GitHub - brd6/tinybird-sdk-php: PHP SDK for the Tinybird API.

Tinybird SDK for PHP

PHP SDK for the Tinybird API — the real-time data platform for developers. Build low-latency, high-concurrency analytics APIs over any data source in minutes. Ingest millions of events per second, query with SQL, and publish endpoints instantly.

Synopsis

// Ingest → Query → Results
$tinybird = Client::create('p.your_token');
$tinybird->events()->send('clicks', ['user' => 'alice', 'page' => '/home']);
$result = $tinybird->query()->sql('SELECT count() FROM clicks');
// → {"data":[{"count()":1}],"rows":1}

Features

High-frequency ingestion — Send millions of events per second via Events API
Schema generation — Analyze files to generate Data Source schemas
Sub-second queries — Execute SQL queries with instant results
Concurrent requests — Batch multiple queries for parallel execution
Multi-region support — EU, US, AWS, GCP, and custom deployments
Built-in retry logic — Automatic retry with exponential backoff
PSR-18 compatible — Works with Symfony, Guzzle, or any HTTP client
Type-safe resources — Full PHP 8.1+ support with strict types

Installation

Install this package using Composer:

composer require brd6/tinybird-sdk-php

This package uses PSR-18 HTTP client abstraction. You can use any compatible HTTP client. For quick setup with Symfony HTTP client:

composer require brd6/tinybird-sdk-php symfony/http-client nyholm/psr7

Quick Start

use Brd6\TinybirdSdk\Client;

// Create client (uses EU region by default)
$tinybird = Client::create('p.your_token_here');

// Ingest events
$tinybird->events()->send('events', [
    ['timestamp' => '2025-01-01 00:00:00', 'event' => 'page_view', 'user_id' => 'user_123'],
    ['timestamp' => '2025-01-01 00:00:01', 'event' => 'click', 'user_id' => 'user_456'],
]);

// Query with SQL
$result = $tinybird->query()->sql('SELECT count() FROM events');

// Call a Pipe endpoint
$result = $tinybird->pipes()->query('analytics_endpoint', ['date_from' => '2025-01-01']);

Region Selection

use Brd6\TinybirdSdk\Client;
use Brd6\TinybirdSdk\Enum\Region;

// US East
$tinybird = Client::forRegion('p.your_token', Region::GCP_US_EAST4);

// AWS EU Central
$tinybird = Client::forRegion('p.your_token', Region::AWS_EU_CENTRAL_1);

// Tinybird Local
$tinybird = Client::local('your_local_token');

// Custom port
$tinybird = Client::local('your_local_token', 8080);

Custom Endpoint

For private deployments or custom domains:

use Brd6\TinybirdSdk\Client;
use Brd6\TinybirdSdk\ClientOptions;

$options = (new ClientOptions())
    ->setToken('your_token')
    ->setBaseUrl('https://your-custom-endpoint.com');

$tinybird = new Client($options);

Usage

Analyze API

Analyze files to generate Tinybird Data Source schemas. Useful before creating .datasource files.

// Analyze NDJSON records
$result = $tinybird->analyze()->analyzeRecords([
    ['timestamp' => '2025-01-01 00:00:00', 'event' => 'page_view', 'user_id' => 'user_123'],
    ['timestamp' => '2025-01-01 00:00:01', 'event' => 'click', 'user_id' => 'user_456'],
]);

// Get the generated schema (ready for .datasource files)
echo $result->getSchema();
// Output: timestamp DateTime `json:$.timestamp`, event String `json:$.event`, ...

// Inspect analyzed columns
foreach ($result->columns as $col) {
    echo "{$col->name}: {$col->recommendedType}";
    if ($col->presentPct < 1) {
        echo " (nullable)";
    }
}

// Analyze a remote file
$result = $tinybird->analyze()->analyzeUrl('https://example.com/data.ndjson');

// Analyze raw content
$result = $tinybird->analyze()->analyzeContent($csvContent);

Events API

High-frequency data ingestion optimized for real-time analytics. This is the recommended way to ingest data in Tinybird Forward workspaces.

// Send single event
$result = $tinybird->events()->send('events', [
    'timestamp' => '2025-01-01 00:00:00',
    'event' => 'page_view',
    'user_id' => 'user_123',
]);

// Send batch events
$result = $tinybird->events()->send('events', [
    ['timestamp' => '2025-01-01 00:00:00', 'event' => 'page_view', 'user_id' => 'user_123'],
    ['timestamp' => '2025-01-01 00:00:01', 'event' => 'click', 'user_id' => 'user_456'],
]);

// Check result
echo $result->successfulRows;   // Rows ingested
echo $result->quarantinedRows;  // Rows failed validation

// Send raw NDJSON
$tinybird->events()->sendRaw('events', $ndjsonString);

Data Sources

Read Data Source information and metadata.

// List all Data Sources
$datasources = $tinybird->dataSources()->list();

foreach ($datasources as $ds) {
    echo $ds->name;
    echo $ds->getRowCount();
    echo $ds->getBytes();
}

// Get Data Source details
$info = $tinybird->dataSources()->retrieve('events');

echo $info->id;
echo $info->name;
echo $info->type;
echo $info->createdAt;

// Access columns
foreach ($info->columns as $column) {
    echo $column->name;
    echo $column->type;
}

// Get quarantine data
$quarantine = $tinybird->dataSources()->quarantine('events');

Note: For schema changes, use the Tinybird CLI (tb deploy). See Tinybird Forward documentation.

Query API

Execute raw SQL queries against your Data Sources.

// Simple query
$result = $tinybird->query()->sql('SELECT count() FROM events');

echo $result->rows;
echo $result->data[0]['count()'];

// Query with parameters
$result = $tinybird->query()->sql(
    'SELECT * FROM events WHERE user_id = {user_id:String} LIMIT {limit:Int32}',
    ['user_id' => 'user_123', 'limit' => 100]
);

// Access results
foreach ($result->data as $row) {
    echo $row['event'];
}

// Query statistics
echo $result->getElapsedTime();
echo $result->getRowsRead();
echo $result->getBytesRead();

Batch Queries

Execute multiple SQL queries concurrently for better performance:

// Run multiple queries in parallel
$results = $tinybird->query()->batchSql([
    'total_users' => 'SELECT count() FROM users',
    'active_today' => 'SELECT count() FROM events WHERE date = today()',
    'revenue' => 'SELECT sum(amount) FROM orders',
]);

// Access individual results
foreach ($results as $key => $result) {
    if ($result->isSuccess()) {
        echo "{$key}: " . $result->getData()->data[0];
    } else {
        echo "{$key} failed: " . $result->getException()->getMessage();
    }
}

// Or get data directly
$totalUsers = $results['total_users']->getData()->data[0]['count()'];

Pipes API

Query published API Endpoints and list Pipes.

// List Pipes
$pipes = $tinybird->pipes()->list();

// Query a Pipe endpoint
$result = $tinybird->pipes()->query('my_analytics_endpoint', [
    'start_date' => '2025-01-01',
    'end_date' => '2025-12-31',
    'limit' => 1000,
]);

foreach ($result->data as $row) {
    // Process results
}

Batch Pipe Queries

Query multiple Pipe endpoints concurrently:

// Simple: key is pipe name
$results = $tinybird->pipes()->batchQuery([
    'user_stats' => ['date' => '2025-01-01'],
    'event_counts' => ['type' => 'click'],
]);

// Query same pipe multiple times using # alias
$results = $tinybird->pipes()->batchQuery([
    'user_stats#jan' => ['date' => '2025-01-01'],
    'user_stats#feb' => ['date' => '2025-02-01'],
    'user_stats#mar' => ['date' => '2025-03-01'],
]);

// Handle results with error isolation
foreach ($results as $key => $result) {
    if ($result->isSuccess()) {
        $data = $result->getData();
        echo "{$key}: {$data->rows} rows";
    } else {
        // Individual failures don't affect other queries
        echo "{$key} failed: " . $result->getException()->getMessage();
    }
}

Jobs API

Monitor and manage background jobs (imports, populates, copies).

use Brd6\TinybirdSdk\RequestParameters\ListJobsParams;
use Brd6\TinybirdSdk\Enum\JobStatus;

// List recent jobs
$jobs = $tinybird->jobs()->list();

// Filter by status
$jobs = $tinybird->jobs()->list(new ListJobsParams(status: JobStatus::DONE));

// Get job details
$job = $tinybird->jobs()->retrieve($jobId);
echo $job->status; // waiting, working, done, error

// Cancel a running job
$tinybird->jobs()->cancel($jobId);

Environment Variables API

Manage workspace variables for use in Pipes.

// List all variables
$vars = $tinybird->variables()->list();

// Create a variable
$var = $tinybird->variables()->create('API_KEY', 'secret_value');

// Update a variable
$tinybird->variables()->update('API_KEY', 'new_value');

// Delete a variable
$tinybird->variables()->remove('API_KEY');

Tokens API

Manage workspace tokens for authentication.

use Brd6\TinybirdSdk\RequestParameters\CreateTokenParams;

// List all tokens
$tokens = $tinybird->tokens()->list();

// Create a token with scopes
$token = $tinybird->tokens()->create(new CreateTokenParams(
    name: 'my_token',
    scopes: ['PIPES:READ', 'DATASOURCES:READ'],
));

// Refresh (rotate) a token
$newToken = $tinybird->tokens()->refresh('my_token');

// Delete a token
$tinybird->tokens()->remove('my_token');

Sink Pipes API

Export data to object stores (S3, GCS).

use Brd6\TinybirdSdk\RequestParameters\CreateSinkParams;

// Create a sink pipe
$pipe = $tinybird->sinkPipes()->create($pipeId, $nodeId, new CreateSinkParams(
    connection: 's3://bucket/path',
    path: 'exports/',
));

// Trigger a sink export
$result = $tinybird->sinkPipes()->trigger($pipeId);

// Get S3 integration settings
$settings = $tinybird->sinkPipes()->getS3Settings();

Error Handling

use Brd6\TinybirdSdk\Exception\ApiException;
use Brd6\TinybirdSdk\Exception\AuthenticationException;
use Brd6\TinybirdSdk\Exception\RateLimitException;
use Brd6\TinybirdSdk\Exception\RequestTimeoutException;

try {
    $result = $tinybird->pipes()->query('my_endpoint');
} catch (AuthenticationException $e) {
    // Invalid or expired token (401/403)
    // Includes helpful suggestions for region mismatches
} catch (RateLimitException $e) {
    // Too many requests (429)
    $retryAfter = $e->getRetryAfter();
    $limit = $e->getRateLimitLimit();
    $remaining = $e->getRateLimitRemaining();
} catch (RequestTimeoutException $e) {
    // Request timed out
} catch (ApiException $e) {
    // Other API errors
    $code = $e->getCode();
    $message = $e->getMessage();
    $response = $e->getResponse();
}

Regions

Region	Enum	API Base URL
GCP Europe West 3 (default)	`Region::GCP_EUROPE_WEST3`	`https://api.tinybird.co`
GCP Europe West 2	`Region::GCP_EUROPE_WEST2`	`https://api.europe-west2.gcp.tinybird.co`
GCP US East 4	`Region::GCP_US_EAST4`	`https://api.us-east.tinybird.co`
GCP North America	`Region::GCP_NORTHAMERICA_NORTHEAST2`	`https://api.northamerica-northeast2.gcp.tinybird.co`
AWS EU Central 1	`Region::AWS_EU_CENTRAL_1`	`https://api.eu-central-1.aws.tinybird.co`
AWS EU West 1	`Region::AWS_EU_WEST_1`	`https://api.eu-west-1.aws.tinybird.co`
AWS US East 1	`Region::AWS_US_EAST_1`	`https://api.us-east.aws.tinybird.co`
AWS US West 2	`Region::AWS_US_WEST_2`	`https://api.us-west-2.aws.tinybird.co`
Local	`Region::LOCAL`	`http://localhost:7181`

Configuration

use Brd6\TinybirdSdk\Client;
use Brd6\TinybirdSdk\ClientOptions;
use Brd6\TinybirdSdk\Enum\Region;

$options = (new ClientOptions())
    ->setToken(getenv('TINYBIRD_TOKEN'))
    ->setRegion(Region::AWS_EU_CENTRAL_1)
    ->setTimeout(120)
    ->setCompression(true)
    ->setRetryMaxRetries(5)
    ->setRetryDelayMs(1000)
    ->setRetryBackoffMultiplier(3);

$tinybird = new Client($options);

Option	Default	Description
`token`	`''`	Tinybird API token
`region`	`Region::GCP_EUROPE_WEST3`	API region
`baseUrl`	`https://api.tinybird.co`	Custom API endpoint
`timeout`	`60`	Request timeout in seconds
`compression`	`false`	Enable gzip compression
`apiVersion`	`v0`	API version
`httpClient`	auto-discovered	Custom PSR-18 HTTP client
`retryMaxRetries`	`3`	Maximum retry attempts
`retryDelayMs`	`2000`	Initial retry delay (ms)
`retryBackoffMultiplier`	`2`	Backoff multiplier

API Reference

Endpoint	Methods
`analyze()`	`analyzeContent()`, `analyzeRecords()`, `analyzeUrl()`
`events()`	`send()`, `sendRaw()`, `sendJson()`
`dataSources()`	`list()`, `retrieve()`, `quarantine()`
`query()`	`sql()`, `batchSql()`
`pipes()`	`list()`, `retrieve()`, `query()`, `batchQuery()`, `getData()`, `explain()`
`jobs()`	`list()`, `retrieve()`, `cancel()`
`variables()`	`list()`, `retrieve()`, `create()`, `update()`, `remove()`
`tokens()`	`list()`, `retrieve()`, `create()`, `createJwt()`, `update()`, `refresh()`, `remove()`
`sinkPipes()`	`create()`, `remove()`, `trigger()`, `getS3Settings()`, `getGcsCredentials()`

Examples

See the examples directory for complete working examples:

Quick Start — Basic SDK usage
Analyze API — Schema inference
Batch Queries — Concurrent query execution
Data Sources — List and inspect Data Sources
Events API — High-frequency ingestion
Jobs API — Monitor background jobs
Pipes API — Query API Endpoints
Tokens API — Token management
Variables API — Environment variables

Documentation

Contributing

Contributions are welcome! See CONTRIBUTING.md.

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github		.github
build		build
examples		examples
src		src
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
captainhook.json		captainhook.json
codecov.yml		codecov.yml
composer.json		composer.json
conventional-commits.json		conventional-commits.json
phpcs.xml copy.dist		phpcs.xml copy.dist
phpcs.xml.dist		phpcs.xml.dist
phpstan.neon.dist		phpstan.neon.dist
phpunit.xml.dist		phpunit.xml.dist
psalm-baseline.xml		psalm-baseline.xml
psalm.xml		psalm.xml
sailr.json		sailr.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Synopsis

Features

Installation

Quick Start

Region Selection

Custom Endpoint

Usage

Analyze API

Events API

Data Sources

Query API

Batch Queries

Pipes API

Batch Pipe Queries

Jobs API

Environment Variables API

Tokens API

Sink Pipes API

Error Handling

Regions

Configuration

API Reference

Examples

Documentation

Contributing

About

Uh oh!

Releases 3

Packages

Languages

License

brd6/tinybird-sdk-php

Folders and files

Latest commit

History

Repository files navigation

Synopsis

Features

Installation

Quick Start

Region Selection

Custom Endpoint

Usage

Analyze API

Events API

Data Sources

Query API

Batch Queries

Pipes API

Batch Pipe Queries

Jobs API

Environment Variables API

Tokens API

Sink Pipes API

Error Handling

Regions

Configuration

API Reference

Examples

Documentation

Contributing

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

Packages