README

该包是为Clickhouse编写的客户端。

客户端使用Guzzle向Clickhouse服务器发送HTTP请求。

要求

php7.1

安装

Composer

composer require arungowda325/clickhouse-php-client

用法

客户端可与单独的服务器或集群一起工作。此外，客户端还可以执行异步选择和插入（来自本地文件）查询。

单独服务器

$server = new Wolverine\ClickhouseClient\Server('127.0.0.1', '8123', 'default', 'user', 'pass');
$serverProvider = (new Wolverine\ClickhouseClient\ServerProvider())->addServer($server);

$client = new Wolverine\ClickhouseClient\Client($serverProvider);

集群

$testCluster = new Wolverine\ClickhouseClient\Cluster('cluster-name', [
    'server-1' => [
        'host' => '127.0.0.1',
        'port' => '8123',
        'database' => 'default',
        'user' => 'user',
        'password' => 'pass'
    ],
    'server-2' => new Wolverine\ClickhouseClient\Server('127.0.0.1', '8124', 'default', 'user', 'pass')
]);

$anotherCluster = new Wolverine\ClickhouseClient\Cluster('cluster-name', [
    [
        'host' => '127.0.0.1',
        'port' => '8125',
        'database' => 'default',
        'user' => 'user',
        'password' => 'pass'
    ],
    new Wolverine\ClickhouseClient\Server('127.0.0.1', '8126', 'default', 'user', 'pass')
]);

$serverProvider = (new Wolverine\ClickhouseClient\ServerProvider())->addCluster($testCluster)->addCluster($anotherCluster);

$client = (new Wolverine\ClickhouseClient\Client($serverProvider));

在集群上执行任何查询之前，您应提供集群名称，客户端将在指定的集群上运行所有查询。

$client->onCluster('test-cluster');

默认情况下，客户端将使用给定服务器列表中的随机服务器或指定的集群。如果您想对指定的服务器执行请求，您应该在客户端上使用using($hostname)方法，然后运行查询。客户端将记住主机名以供后续查询使用。

$client->using('server-2')->select('select * from table');

服务器标签

$firstServerOptionsWithTag = (new \Wolverine\ClickhouseClient\Common\ServerOptions())->setTag('tag');
$secondServerOptionsWithAnotherTag = (new \Wolverine\ClickhouseClient\Common\ServerOptions())->setTag('another-tag');

$server = new Wolverine\ClickhouseClient\Server('127.0.0.1', '8123', 'default', 'user', 'pass', $firstServerOptionsWithTag);

$cluster = new Wolverine\ClickhouseClient\Cluster('cluster', [
    new Wolverine\ClickhouseClient\Server('127.0.0.2', '8123', 'default', 'user', 'pass', $secondServerOptionsWithAnotherTag)
]);

$serverProvider = (new Wolverine\ClickhouseClient\ServerProvider())->addServer($server)->addCluster($cluster);

$client = (new Wolverine\ClickhouseClient\Client($serverProvider));

要使用具有标签的服务器，您应在执行任何查询之前调用usingServerWithTag函数。

$client->usingServerWithTag('tag');

选择查询

任何SELECT查询都将返回Result的实例。该类实现了\ArrayAccess、\Countable和\Iterator接口，这意味着它可以用作数组。

可以通过rows属性获取结果行数组。

$rows = $result->rows;
$rows = $result->getRows();

您还可以获取查询执行的某些统计信息

读取的行数
读取的字节数
查询执行时间
至少在限制之前的行数

可以通过statistic属性获取统计信息

$statistic = $result->statistic;
$statistic = $result->getStatistic();

echo $statistic->rows;
echo $statistic->getRows();

echo $statistic->bytes;
echo $statistic->getBytes();

echo $statistic->time;
echo $statistic->getTime();

echo $statistic->rowsBeforeLimitAtLeast;
echo $statistic->getRowsBeforeLimitAtLeast();

同步

$result = $client->readOne('select number from system.numbers limit 100');

foreach ($result as $number) {
    echo $number['number'].PHP_EOL;
}

使用本地文件

您可以将本地文件用作Clickhouse中的临时表。您应传递作为第三个参数的TempTable实例数组。

在这种情况下，将从服务器发送一个文件到Clickhouse，Clickhouse将从该文件中提取数据到临时表。表的结构将是

number - UInt64

如果您以这样的数组作为结构传递

['UInt64']

那么文件中的每个列将命名为 _1, _2, _3。

$result = $client->readOne('select number from system.numbers where number in _numbers limit 100', new TempTable('_numbers', 'numbers.csv', [
    'number' => 'UInt64'
]));

foreach ($result as $number) {
    echo $number['number'].PHP_EOL;
}

您可以提供文件路径或传递FileInterface实例作为第二个参数。

可以用于发送到服务器的其他一些文件流类型

文件 - 存储在磁盘上的简单文件；
FileFromString - 从字符串创建的流。例如：new FileFromString('1'.PHP_EOL.'2'.PHP_EOL.'3'.PHP_EOL)
MergedFiles - 包含多个文件并将它们全部合并在一起的流。您应将包含应合并到一个流中的文件列表的文件路径传递给构造函数。
TempTable - 将任何FileInterface实例包装起来并包含结构。对于使用MergedFiles进行插入很有用。

异步

与返回Result的readOne方法不同，read方法为每个执行的查询返回一个Result数组。

list($clicks, $visits, $views) = $client->read([
    ['query' => "select * from clicks where date = '2017-01-01'"],
    ['query' => "select * from visits where date = '2017-01-01'"],
    ['query' => "select * from views where date = '2017-01-01'"],
]);

foreach ($clicks as $click) {
    echo $click['date'].PHP_EOL;
}

在read方法中，您可以传递参数$concurrency，该参数负责最大的并发请求数。

使用本地文件

与同步选择请求一样，您可以将文件传递到服务器

list($clicks, $visits, $views) = $client->read([
    ['query' => "select * from clicks where date = '2017-01-01' and userId in _users", new TempTable('_users', 'users.csv', ['number' => 'UInt64'])],
    ['query' => "select * from visits where date = '2017-01-01'"],
    ['query' => "select * from views where date = '2017-01-01'"],
]);

foreach ($clicks as $click) {
    echo $click['date'].PHP_EOL;
}

在异步请求中，您可以用同步请求的方式传递多个文件。

插入查询

插入查询始终返回true或在出错时抛出异常。

数据可以逐行写入，或从本地的CSV或TSV文件中写入。

$client->writeOne("insert into table (date, column) values ('2017-01-01',1), ('2017-01-02',2)");
$client->write([
    ['query' => "insert into table (date, column) values ('2017-01-01',1), ('2017-01-02',2)"],
    ['query' => "insert into table (date, column) values ('2017-01-01',1), ('2017-01-02',2)"],
    ['query' => "insert into table (date, column) values ('2017-01-01',1), ('2017-01-02',2)"]
]);

$client->writeFiles('table', ['date', 'column'], [
    new Wolverine\ClickhouseClient\Common\File('/file-1.csv'),
    new Wolverine\ClickhouseClient\Common\File('/file-2.csv')
]);

$client->insertFiles('table', ['date', 'column'], [
    new Wolverine\ClickhouseClient\Common\File('/file-1.tsv'),
    new Wolverine\ClickhouseClient\Common\File('/file-2.tsv')
], Wolverine\ClickhouseClient\Common\Format::TSV);

在执行 writeFiles 查询时，会异步执行。如果你有很多文件，并且希望在一个插入查询中插入它们，你可以使用我们的 ccat 工具和 MergedFiles 实例来代替 File。你应该将需要插入的文件列表放入一个文件中。

file-1.tsv
file-2.tsv

构建 ccat

将 ccat 源代码放在 utils/ccat 目录中。只需运行 make && make install 命令来构建并将库安装到软件包的 bin 目录中。在 bin 目录中已经预编译了 ccat 的二进制文件，但它在某些系统上可能无法工作。

在 writeFiles 方法中，你可以传递参数 $concurrency，它负责最大并发请求数量。

其他查询

除了 SELECT 和 INSERT 查询之外，你还可以执行其他查询 :) 有 statement 方法用于此目的。

$client->writeOne('DROP TABLE table');

测试

$ composer test

路线图

添加保存查询结果到本地文件的能力

贡献

请发送你的 pull-requests 并提出如何改进任何内容的建议。我们将非常感激。

谢谢！

arungowda325 / clickhouse-php-client

维护者

详细信息