README

这是一个用于在关系数据库中存储时间序列数据的简单PHP包。

"如果所有你拥有的只是一个MySQL实例，一切看起来都像是关系数据。"

概述

此库用于存储在气象站测量的气象时间序列数据，用于api.existenz.ch项目。它是存储时间序列数据在关系数据库中的简单且轻量级解决方案。

首先使用createLocation('locationname')创建一些位置，然后使用createParameter('parametername', 'unit')创建一些参数。

使用insertValue('locationname', 'parametername', $timestamp, $value)插入值。

使用getValues()或getLatestValues()检索值，并将获得一个填充了\cstuder\ParseValueholder\Value对象的\cstuder\ParseValueholder\Row。

$row->getValues();

->

[
    Value {
        location => 'locationname',
        parameter => 'parametername',
        timestamp => 1234567890,
        value => '1.23'
    }
]

数据库设置

该包使用到MySQL兼容数据库的连接（使用MyTS::MyTSMySQLFactory或MyTS::MyTSFromDSNFactory）和一个时间序列名称来创建四个表

• myts_timeseriesname_loc用于位置及其元数据
• myts_timeseriesname_par用于参数、它们的单位和元数据
• myts_timeseriesname_val用于值
• myts_timeseriesname_latest用于最新值
• 可选：带有聚合视图的myts_timeseriesname_view

值默认为FLOAT类型，但在创建时可以使用createDatabaseTables()更改到任何其他类型。

首先使用createLocation('locationname')创建一些位置，然后使用createParameter('parametername', 'unit')创建一些参数。这两种方法都接受一个可选的键值数组，该数组将被序列化到数据库中。

要更新位置或参数，只需再次以相同的名称和更新后的元数据调用createLocation()或createParameter()即可。您不能更改位置或参数的名称。

插入值

使用insertValue('locationname', 'parametername', $timestamp, $value)插入值。时间戳是Unix时间戳。位置和参数名称是区分大小写的。如果成功，该方法将返回true。如果插入失败（即位置或参数不存在），则将抛出异常。将最后一个参数设置为true将静默失败并仅返回false。

要更新以前的值，可以使用相同的insertValue()方法。

可以使用方便的方法insertValueObject()和insertValueRow()分别从Value对象或Row对象中插入值。

检索值

使用getValues()从时间序列中检索值。该方法接受可选的起始和结束时间。也可以通过位置和参数进行过滤（默认情况下，将忽略未知的位置或参数名称，但可以通过设置参数$failSilenty为false来更改）。

如果没有提供位置和/或参数名称，将返回所有位置和/或参数。

要快速检索最新值，请使用getLatestValues()。它接受可选的位置和参数名称。

数据以\cstuder\ParseValueholder\Row的形式返回，它被一个\cstuder\ParseValueholder\Value对象的数组填充。

$row->getValues();

->

[
    Value {
        location => 'locationname',
        parameter => 'parametername',
        timestamp => 1234567890,
        value => '1.23'
    }
]

维护

deleteValuesOlderThan()方法将无条件删除所有早于给定时间戳的值。请谨慎使用。

限制

• 位置和参数名称是区分大小写的，并且只能为128个字符长。
• 没有批量插入（当导入大量数据集时，这会更快）。
• 它也可以与其他数据库引擎（MariaDB等）一起工作，但尚未测试。（使用PDO库内部。）
• 在PHP中，数据库通常将所有字段作为字符串返回。

使用方法

示例使用代码（可在sample_usage.php中找到可运行的版本）

// Connection: Timeseries name, server, user, password, database
$myTS = MyTS::MyTSMySQLFactory('test', 'localhost', 'testuser', 'testpassword', 'testdb');

// Create database tables (Only if they don't exist yet), plus an additional info view
$myTS->createDatabaseTables('DECIMAL(8,2)', true);

// Create locations with optional metadata
$myTS->createLocation('here');
$myTS->createLocation('there', ['where' => 'exactly there']);

// Update locations with metadata
$myTS->createLocation('here', ['where' => 'not there']);

// Show locations
var_dump($myTS->getAllLocations());

// Create parameters with optional units and optional metadata
$myTS->createParameter('aaa');
$myTS->createParameter('bbb', 'potatoes');
$myTS->createParameter('ccc', NULL, ['si' => FALSE]);

// Update parameter
$myTS->createParameter('ccc', 'kg', ['si' => TRUE]);

// Show parameters
var_dump($myTS->getAllParameters());

// Insert values (Location and parameters are case sensitive)
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:00:00'), 1);
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:04:00'), -3);
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:02:00'), 1.567);
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:03:00'), 1.56789);
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:01:00'), 1.5);
$myTS->insertValue('there', 'bbb', strtotime('2018-01-01 00:01:00'), 1.51);
$myTS->insertValue('there', 'aaa', strtotime('2018-01-01 00:01:00'), 1.49);

// Update values
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:00:00'), -1);

// Insert value in unknown location/parameter silently
var_dump($myTS->insertValue('xxyyzz', 'xxyyzz', strtotime('2018-01-01 00:00:00'), 1, true));

// Insert value in unknown location/parameter noisily
try {
    $myTS->insertValue('xxyyzz', 'xxyyzz', strtotime('2018-01-01 00:00:00'), 1, false);
} catch (Exception $e) {
    var_dump($e);
}

// Get all values in this timeseries
var_dump($myTS->getValues());

// Get subset of values
var_dump($myTS->getValues(null, null, 'here'));
var_dump($myTS->getValues(null, null, 'asbasdf')); // Unknown location, fails silently

// Get latest values
var_dump($myTS->getLatestValues());

// Get subset of latest values
var_dump($myTS->getLatestValues('there'));
var_dump($myTS->getLatestValues(null, 'bbb'));
var_dump($myTS->getLatestValues('asbasdf')); // Unknown location, fails silently

安装

composer require cstuder/myts

测试

composer run test

需要在localhost/127.0.0.1上运行一个兼容MySQL的数据库，以下凭据： testuser，testpassword，testdb。

可以被环境变量MYTS_DSN中的有效DSN覆盖，例如

mysql:host=localhost;dbname=testdb;user=testuser;password=testpassword;charset=utf8

发布

查看CHANGELOG.md以获取发布历史。

1. 将更改添加到changelog。
2. 创建一个新的标签 vX.X.X。
3. 推送。

许可证

MIT