2.12.2021, 9:00 - 11:00: Due to updates GitLab may be unavailable for some minutes between 09:00 and 11:00.

sensordatastore.h 8.69 KB
Newer Older
1
2
3
//================================================================================
// Name        : sensordatastore.h
// Author      : Axel Auweter
Micha Müller's avatar
Micha Müller committed
4
// Contact     : info@dcdb.it
5
6
7
8
9
10
// Copyright   : Leibniz Supercomputing Centre
// Description : C++ API for inserting and querying DCDB sensor data.
//================================================================================

//================================================================================
// This file is part of DCDB (DataCenter DataBase)
11
// Copyright (C) 2011-2019 Leibniz Supercomputing Centre
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
//================================================================================

28
29
30
31
32
33
34
35
36
37
/**
 * @defgroup libdcdb libdcdb
 *
 * @brief Library to access DCDB's storage backend.
 *
 * @details The libdcdb library is a dynamic runtime library providing
 * 	        functions to initialize and access the DCDB data store. It
 * 	        is being used by the CollectAgent to handle insertion of
 * 	        data and can be used by tools responsible for data analysis.
 */
38

39
/**
40
41
 * @file sensordatastore.h
 *
Michael Ott's avatar
Michael Ott committed
42
 * @brief This file contains the public API for the libdcdb library.
43
44
45
 * It contains the class definition of the library's main class
 * SensorDataStore as well as the helper struct typedefs SensorId,
 * DeviceLocation, and DeviceSensorId.
46
47
 *
 * @ingroup libdcdb
48
49
 */

50
#include <string>
Axel Auweter's avatar
Axel Auweter committed
51
52
#include <list>
#include <cstdint>
53

Axel Auweter's avatar
Axel Auweter committed
54
#include "sensorid.h"
Axel Auweter's avatar
Axel Auweter committed
55
#include "timestamp.h"
56
57
#include "connection.h"

58
59
60
61
#ifndef DCDB_SENSORDATASTORE_H
#define DCDB_SENSORDATASTORE_H

namespace DCDB {
62

Axel Auweter's avatar
Axel Auweter committed
63
64
65
66
typedef enum {
  SDS_OK,
  SDS_EMPTYSET
} SDSQueryResult;
67
68
69
70
71
72
73
74
75
  
typedef enum {
  AGGREGATE_NONE = 0,
  AGGREGATE_MIN,
  AGGREGATE_MAX,
  AGGREGATE_AVG,
  AGGREGATE_SUM,
  AGGREGATE_COUNT
} QueryAggregate;
Axel Auweter's avatar
Axel Auweter committed
76

77
/* Forward-declaration of the implementation-internal classes */
78
class SensorDataStoreImpl;
79

Axel Auweter's avatar
Axel Auweter committed
80
/**
81
 * @brief %SensorDataStoreReading is the class for a single
Axel Auweter's avatar
Axel Auweter committed
82
83
84
85
86
87
 * sensor-timestamp-value entry in the database.
 */
class SensorDataStoreReading
{
public:
  SensorId sensorId;
88
  TimeStamp timeStamp;
89
  int64_t value;
90
91
92
93
94
95
96
97

#if 0
  inline bool operator == (const SensorDataStoreReading& rhs) const {
    return (sensorId == rhs.sensorId) &&
        (timeStamp == rhs.timeStamp) &&
        (value == rhs.value);}
#endif

98
99
100
101
  inline bool operator < (const SensorDataStoreReading& rhs) const {
    return (value < rhs.value);
  }

102
  SensorDataStoreReading();
103
  SensorDataStoreReading(const SensorId& sid, const uint64_t ts, const int64_t value);
104
  virtual ~SensorDataStoreReading();
Axel Auweter's avatar
Axel Auweter committed
105
106
};

107
/**
108
 * @brief %SensorDataStore is the class of the libdcdb library
Axel Auweter's avatar
Axel Auweter committed
109
 * to write and read sensor data.
110
 */
111
112
113
114
115
116
class SensorDataStore
{
private:
    SensorDataStoreImpl* impl;
    
public:
117
118
119
    /**
     * @brief This function inserts a single sensor reading into
     *        the database.
120
121
122
123
     * @param sid      A SensorId object
     * @param ts       The timestamp of the sensor reading
     * @param value    The value of the sensor reading
     * @param ttl      Time to live (in seconds) for the inserted reading
124
     */
125
    void insert(const SensorId& sid, const uint64_t ts, const int64_t value, const int64_t ttl=-1);
126
127
128
129

    /**
     * @brief This function inserts a single sensor reading into
     *        the database.
130
131
     * @param reading  A SensorDataStoreReading object
     * @param ttl      Time to live (in seconds) for the inserted reading
132
     */
133
    void insert(const SensorDataStoreReading& reading, const int64_t ttl=-1);
134
    
135
136
137
    /**
     * @brief This function inserts a single sensor reading into
     *        the database.
138
139
     * @param readings  A list of SensorDataStoreReading object
     * @param ttl       Time to live (in seconds) for the inserted readings
140
     */
141
    void insertBatch(const std::list<SensorDataStoreReading>& readings, const int64_t ttl=-1);
142
    
143
    /**
144
145
     * @brief Set the TTL for newly inserted sensor data.
     * @param ttl      The TTL for the sensor data in seconds.
146
     */
147
    void setTTL(const uint64_t ttl);
148

Alessio Netti's avatar
Alessio Netti committed
149
150
151
152
    /**
     * @brief Enables or disables logging of Cassandra insert errors
     * @param dl        true to enable logging, false otherwise
     */
153
    void setDebugLog(const bool dl);
Alessio Netti's avatar
Alessio Netti committed
154

Axel Auweter's avatar
Axel Auweter committed
155
    /**
156
     * @brief This function queries a sensor's values in
Axel Auweter's avatar
Axel Auweter committed
157
158
159
160
161
162
     *        the given time range.
     * @param result   The list where the results will be stored.
     * @param sid      The SensorId to query.
     * @param start    Start of the time series.
     * @param end      End of the time series.
     */
163
    void query(std::list<SensorDataStoreReading>& result, const SensorId& sid, const TimeStamp& start, const TimeStamp& end, const QueryAggregate aggregate=AGGREGATE_NONE);
Axel Auweter's avatar
Axel Auweter committed
164

165
166
167
168
169
170
171
172
173
    /**
     * @brief This function queries a the values of
     *        a set of sensors in the given time range.
     *        The weekstamp being used is in this case that of the sensor ID 
     *        at the front of the input list.
     * @param result   The list where the results will be stored.
     * @param sids     The list of SensorIds to query.
     * @param start    Start of the time series.
     * @param end      End of the time series.
174
     * @param storeSid If true, Sensor IDs will be retrieved for each reading.
175
     */
176
    void query(std::list<SensorDataStoreReading>& result, const std::list<SensorId>& sids, const TimeStamp& start, const TimeStamp& end, const QueryAggregate aggregate=AGGREGATE_NONE, const bool storeSids=true);
177
    
178
179
180
181
182
183
184
185
    /**
     * @brief This function performs a fuzzy query and returns the 
     *        closest sensor reading to the input timestamp.
     * @param result   The list where the results will be stored.
     * @param sid      The SensorId to query.
     * @param ts       The target timestamp.
     * @param tol_ns   Tolerance of the fuzzy query in nanoseconds.
     */
186
    void fuzzyQuery(std::list<SensorDataStoreReading>& result, const SensorId& sid, const TimeStamp& ts, const uint64_t tol_ns=3600000000000);
187

188
189
190
191
192
193
194
195
196
    /**
     * @brief This function performs a fuzzy query and returns the closest 
     *        sensor reading to the input timestamp, one per queried sensor.
     *        The weekstamp being used is in this case that of the sensor ID 
     *        at the front of the input list.
     * @param result   The list where the results will be stored.
     * @param sids     The list of SensorIds to query.
     * @param ts       The target timestamp.
     * @param tol_ns   Tolerance of the fuzzy query in nanoseconds.
197
     * @param storeSid If true, Sensor IDs will be retrieved for each reading.
198
     */
199
    void fuzzyQuery(std::list<SensorDataStoreReading>& result, const std::list<SensorId>& sids, const TimeStamp& ts, const uint64_t tol_ns=3600000000000, const bool storeSids=true);
200

201
202
203
204
205
206
207
208
209
210
    typedef void (*QueryCbFunc)(SensorDataStoreReading& reading, void* userData);
    /**
     * @brief This function queries a sensor's values in
     *        the given time range.
     * @param cbFunc   A function to called for each reading.
     * @param userData Pointer to user data that will be returned in the callback.
     * @param sid      The SensorId to query.
     * @param start    Start of the time series.
     * @param end      End of the time series.
     */
211
    void queryCB(QueryCbFunc cbFunc, void* userData, const SensorId& sid, const TimeStamp& start, const TimeStamp& end, const QueryAggregate aggregate=AGGREGATE_NONE);
212

213
214
215
216
217
    /**
     * @brief This function truncates all sensor data that is older than
     *        the specified week.
     * @param weekStamp   The 16-bit weekstamp generated from a cut-off date
     */
218
    void truncBeforeWeek(const uint16_t weekStamp);
219

220
    /**
221
222
223
     * @brief A shortcut constructor for a SensorDataStore object
     *        that allows accessing the data store through a
     *        connection that is already established.
224
     * @param conn     The Connection object of an established
Axel Auweter's avatar
Axel Auweter committed
225
     *                 connection to Cassandra.
226
     */
227
    SensorDataStore(Connection* conn);
228
229
230
231

    /**
     * @brief The standard destructor for a SensorDatStore object.
     */
232
233
234
    virtual ~SensorDataStore();
};

235
} /* End of namespace DCDB */
236

237
#endif /* DCDB_SENSORDATASTORE_H */