view release on metacpan or  search on metacpan

lib/AnyEvent/InfluxDB.pm  view on Meta::CPAN

            {
                measurement => 'cpu_load',
                tags => {
                    host => 'server02',
                    region => 'eu-east',
                },
                fields => {
                    value => '0.64',
                    sensor => q{"top"},
                },
                time => time()
            }
        ],

        on_success => $cv,
        on_error => sub {
            $cv->croak("Failed to write data: @_");
        }
    );
    $cv->recv;

Writes time-series data C<data> to database C<database> with optional parameters:
retention policy C<rp>, time precision C<precision> and consistency C<consistency>.

The required C<on_success> code reference is executed if request was successful,
otherwise executes the required C<on_error> code reference.

The C<data> can be specified as single scalar value or hash reference with
required keys C<measurement> and C<fields> and optional C<tags> and C<time>.
Both can be also mixed and matched within an array reference.

Scalar values are expected to be formatted using InfluxDB line protocol.

All special characters need to be escaped. In that case you might want to use
L<InfluxDB::LineProtocol>:

    use InfluxDB::LineProtocol qw(dataline);

    ...
    $db->write(
        database => 'mydb',
        precision => 'n',

        data => [
            dataline('CPU Load', 0.64, { "Region of the World" => "Eastern Europe", codename => "eu-east" }, 1437868012260500137)

            # which translates to
            'CPU\ Load,Region\ of\ the\ World=Eastern\ Europe,codename=eu-east value=0.64 1437868012260500137',
        ],
        ...
    );

=head2 Querying Data

=head3 select

    $cv = AE::cv;
    $db->select(
        database => 'mydb',

        # return time in Unix epoch format
        epoch => "s",

        # raw query
        q => "SELECT count(value) FROM cpu_load"
            ." WHERE region = 'eu-east' AND time > now() - 14d"
            ." GROUP BY time(1d) fill(none)"
            ." ORDER BY time DESC"
            ." LIMIT 10 OFFSET 3",

        # or query created from arguments
        fields => 'count(value)',
        measurement => 'cpu_load',
        where => "region = 'eu-east' AND time > now() - 14d",

        group_by => 'time(1d)',
        fill => 'none',

        order_by => 'time DESC',

        limit => 10,
        offset => 3,

        # downsample result to another database, retention policy and measurement
        into => 'otherdb."default".cpu_load_per5m',

        # callbacks
        on_success => $cv,
        on_error => sub {
            $cv->croak("Failed to select data: @_");
        }
    );
    my $results = $cv->recv;
    for my $row ( @{ $results } ) {
        print "Measurement: $row->{name}\n";
        print "Values:\n";
        for my $value ( @{ $row->{values} || [] } ) {
            print " * $_ = $value->{$_}\n" for keys %{ $value || {} };
        }
    }

Executes an select query on database C<database> created from provided arguments
measurement C<measurement>, fields to select C<fields>, optional C<where>
clause, grouped by C<group_by> and empty values filled with C<fill>, ordered by
C<order_by> with number of results limited to C<limit> with offset C<offset>.
To limit number of returned series use C<slimit> with offset C<soffset>.
If C<into> parameter is provided the result of the query will be copied to specified
measurement.
If C<epoch> is provided the returned C<time> value will in Unix epoch format.
Optional C<chunk_size> can be provided to override the default value of 10,000 datapoints.

The required C<on_success> code reference is executed if request was successful,
otherwise executes the required C<on_error> code reference.

=head2 Database Management

=head3 create_database

    $cv = AE::cv;
    $db->create_database(
        # raw query
        q => "CREATE DATABASE mydb WITH DURATION 7d REPLICATION 3 SHARD DURATION 30m NAME oneweek",

        # or query created from arguments
        database => "mydb",

        # retention policy parameters
        duration => '7d',
        shard_duration => '30m',
        replication => 3,
        name => 'oneweek',

        # callbacks
        on_success => $cv,
        on_error => sub {
            $cv->croak("Failed to create database: @_");
        }
    );
    $cv->recv;

Creates database specified by C<database> argument.

If one of retention policy parameters is specified then the database will be
created with that retention policy as default - see L</"Retention Policy Management">
for more details.

The required C<on_success> code reference is executed if request was successful,
otherwise executes the required C<on_error> code reference.

=head3 drop_database

    $cv = AE::cv;
    $db->drop_database(
        # raw query
        q => "DROP DATABASE mydb",

        # or query created from arguments
        database => "mydb",

        # callbacks
        on_success => $cv,
        on_error => sub {
            $cv->croak("Failed to drop database: @_");
        }
    );
    $cv->recv;

Drops database specified by C<database> argument.