keboola/query-api-php-client

Keboola Query Service API PHP Client

0.2.0 2025-08-21 08:43 UTC

Requires

• php: ^8.4
• ext-json: *
• guzzlehttp/guzzle: ~7.0
• psr/log: ^1.0|^2.0|^3.0

Requires (Dev)

• keboola/coding-standard: ^16.0
• keboola/storage-api-client: ^18.0
• phpstan/phpstan: ^1.8
• phpstan/phpstan-phpunit: ^1.1
• phpunit/phpunit: ^9.5
• squizlabs/php_codesniffer: ^3
• symfony/dotenv: ^6.0

MIT

README

PHP client for Keboola Query Service API.

Installation

composer require keboola/query-api-php-client

Usage

<?php

use Keboola\QueryApi\Client;

$client = new Client([
    'url' => 'https://query.keboola.com',
    'token' => 'your-storage-api-token'
]);

// Submit a query job
$response = $client->submitQueryJob('main', 'workspace-123', [
    'statements' => ['SELECT * FROM table1'],
    'transactional' => true
]);

$queryJobId = $response['queryJobId'];

// Get job status
$status = $client->getJobStatus($queryJobId);

// Get job results
$results = $client->getJobResults($queryJobId, $statementId);

// Cancel job
$client->cancelJob($queryJobId, ['reason' => 'User requested cancellation']);

// Health check
$health = $client->healthCheck();

Configuration Options

The client constructor accepts the following configuration options:

• url (required): Query Service API URL (e.g., https://query.keboola.com)
• token (required): Storage API token
• backoffMaxTries (optional): Number of retry attempts for failed requests (default: 3)
• userAgent (optional): Additional user agent string to append
• handler (optional): Custom Guzzle handler stack

Note: The healthCheck() endpoint does not require authentication and will work without a valid token.

API Methods

• submitQueryJob(string $branchId, string $workspaceId, array $requestBody): array
• getJobStatus(string $queryJobId): array
• getJobResults(string $queryJobId, string $statementId): array
• cancelJob(string $queryJobId, array $requestBody = []): array
• healthCheck(): array

Development

Running Tests

Unit Tests

Run unit tests:

vendor/bin/phpunit tests/ClientTest.php

Functional Tests

Functional tests require environment variables to be set:

• TESTS_STORAGE_API_TOKEN - Storage API authentication token
• TESTS_QUERY_API_URL - Query Service API endpoint URL
• TESTS_STORAGE_API_URL - Storage API endpoint URL

Run functional tests:

vendor/bin/phpunit tests/Functional/

All Tests

Run all tests:

composer run tests

Code Quality

Run code style check:

composer run phpcs

Fix code style issues:

composer run phpcbf

Run static analysis:

composer run phpstan

Run all CI checks. Check Github Workflows for more details

composer run ci