Database¶

dballe::DB is the class implementing access to a DB-All.e database. Operations are performed via a dballe::Transaction, although dballe::DB provides shortcut methods that transparently create a transaction, perform the operation and commit it.

Data is queried using a dballe::Query, and inserted using a dballe::Data.

class DB : public std::enable_shared_from_this<DB>¶

Subclassed by dballe::db::DB

Public Functions

virtual std::shared_ptr<dballe::Transaction> transaction(bool readonly = false) = 0¶: Begin a transaction on this database, and return a Transaction object that can be used to commit it.

virtual std::unique_ptr<CursorStation> query_stations(const Query &query)¶

Start a query on the station variables archive.

The cursor will iterate over unique lat, lon, ident triples, and will contain all station vars. If a station var exists twice on two different networks, only one will be present: the one of the network with the highest priority.

Return

The cursor to use to iterate over the results

Parameters

query: The Query selecting the stations to return

virtual std::unique_ptr<CursorStationData> query_station_data(const Query &query)¶

Query the station variables in the database.

When multiple values per variable are present, the results will be presented in increasing order of priority.

Return

The cursor to use to iterate over the results

Parameters

query: The Query selecting the station data to return

virtual std::unique_ptr<CursorData> query_data(const Query &query)¶

Query the database.

When multiple values per variable are present, the results will be presented in increasing order of priority.

Return

The cursor to use to iterate over the results

Parameters

query: The Query selecting the data to return

virtual std::unique_ptr<CursorSummary> query_summary(const Query &query)¶

Query a summary of what the result would be for a query.

Return

The cursor to use to iterate over the results

Parameters

query: The Query selecting the data to summarise

virtual std::unique_ptr<CursorMessage> query_messages(const Query &query)¶

Query the database returning the matching data as Message objects.

Return

The cursor to use to iterate over the results

Parameters

query: The Query selecting the data that will go into the Message objects

void remove_all()¶

Remove all data from the database.

This is faster than remove() with an empty record, and unlike reset() it preserves existing report information.

void remove_station_data(const Query &query)¶

Remove data from the database.

Parameters

query: The query selecting the data to remove

void remove_data(const Query &query)¶

Remove data from the database.

Parameters

query: The query selecting the data to remove

void import_message(const Message &message, const DBImportOptions &opts = DBImportOptions::defaults)¶

Import a Message into the DB-All.e database.

Parameters

message: The Message to import
opts: Options controlling the import process

void import_messages(const std::vector<std::shared_ptr<Message>> &messages, const DBImportOptions &opts = DBImportOptions::defaults)¶

Import Messages into the DB-All.e database.

Parameters

messages: The messages to import
opts: Options controlling the import process

void insert_station_data(Data &vals, const DBInsertOptions &opts = DBInsertOptions::defaults)¶

Insert station values into the database.

The IDs of the station andl all variables that were inserted will be stored in vals.

Parameters

vals: The values to insert.
opts: Options controlling the insert operation

void insert_data(Data &vals, const DBInsertOptions &opts = DBInsertOptions::defaults)¶

Insert data values into the database.

The IDs of the station andl all variables that were inserted will be stored in vals.

Parameters

vals: The values to insert.
opts: Options controlling the insert operation

Public Static Functions

static std::shared_ptr<DB> connect(const DBConnectOptions &opts)¶: Create a new DB.

class Transaction : public std::enable_shared_from_this<Transaction>¶

Subclassed by dballe::db::Transaction

Public Functions

virtual void commit() = 0¶: Commit this transaction.

virtual void rollback() = 0¶: Roll back this transaction.

virtual void rollback_nothrow() = 0¶: Roll back this transaction.

virtual std::unique_ptr<CursorStation> query_stations(const Query &query) = 0¶

Start a query on the station variables archive.

The cursor will iterate over unique lat, lon, ident triples, and will contain all station vars. If a station var exists twice on two different networks, only one will be present: the one of the network with the highest priority.

Return

The cursor to use to iterate over the results

Parameters

query: The Query selecting the stations to return

virtual std::unique_ptr<CursorStationData> query_station_data(const Query &query) = 0¶

Query the station variables in the database.

When multiple values per variable are present, the results will be presented in increasing order of priority.

Return

The cursor to use to iterate over the results

Parameters

query: The Query selecting the station data to return

virtual std::unique_ptr<CursorData> query_data(const Query &query) = 0¶

Query the database.

When multiple values per variable are present, the results will be presented in increasing order of priority.

Return

The cursor to use to iterate over the results

Parameters

query: The Query selecting the data to return

virtual std::unique_ptr<CursorSummary> query_summary(const Query &query) = 0¶

Query a summary of what the result would be for a query.

Return

The cursor to use to iterate over the results

Parameters

query: The Query selecting the data to summarise

virtual std::unique_ptr<CursorMessage> query_messages(const Query &query) = 0¶

Query the database returning the matching data as Message objects.

Return

The cursor to use to iterate over the results

Parameters

query: The Query selecting the data that will go into the Message objects

virtual void remove_all() = 0¶

Remove all data from the database.

This is faster than remove() with an empty record, and unlike reset() it preserves existing report information.

virtual void remove_station_data(const Query &query) = 0¶

Remove data from the database.

Parameters

query: The query selecting the data to remove

virtual void remove_data(const Query &query) = 0¶

Remove data from the database.

Parameters

query: The query selecting the data to remove

virtual void import_message(const Message &message, const DBImportOptions &opts = DBImportOptions::defaults) = 0¶

Import a Message into the DB-All.e database.

Parameters

message: The Message to import
opts: Options controlling the import process

virtual void import_messages(const std::vector<std::shared_ptr<Message>> &messages, const DBImportOptions &opts = DBImportOptions::defaults)¶

Import Messages into the DB-All.e database.

Parameters

messages: The messages to import
opts: Options controlling the import process

virtual void insert_station_data(Data &data, const DBInsertOptions &opts = DBInsertOptions::defaults) = 0¶

Insert station values into the database.

The IDs of the station and all variables that were inserted will be stored in vals.

Parameters

data: The values to insert.
opts: Options controlling the insert operation

virtual void insert_data(Data &data, const DBInsertOptions &opts = DBInsertOptions::defaults) = 0¶

Insert data values into the database.

The IDs of the station and all variables that were inserted will be stored in vals.

Parameters

data: The values to insert.
opts: Options controlling the insert operation

class Query¶

Query used to filter DB-All.e data.

Subclassed by dballe::core::Query

Public Functions

virtual DatetimeRange get_datetimerange() const = 0¶: Get the Datetime bounds set in this query.

virtual void set_datetimerange(const DatetimeRange &dt) = 0¶: Set the Datetime range for this query.

virtual LatRange get_latrange() const = 0¶: Get the range of latitudes to be matched.

virtual void set_latrange(const LatRange &latrange) = 0¶: Set the range of latitudes to be matched.

virtual LonRange get_lonrange() const = 0¶: Get the range of longitudes to be matched.

virtual void set_lonrange(const LonRange &lonrange) = 0¶: Set the range of longitudes to be matched.

virtual Level get_level() const = 0¶: Get the level to be matched.

virtual void set_level(const Level &level) = 0¶: Set the level to be matched.

virtual Trange get_trange() const = 0¶: Get the time range to be matched.

virtual void set_trange(const Trange &trange) = 0¶: Set the level to be matched.

virtual void clear() = 0¶: Clear the contents of the query, making it match all data.

virtual bool is_subquery(const Query &other) const = 0¶

Return true if this query matches a subset of the given query.

In other words, it returns true if this query is the same as other, plus zero or more extra fields set, or zero or more ranges narrowed.

virtual void print(FILE *out) const = 0¶: Print the query contents to stderr.

virtual std::unique_ptr<Query> clone() const = 0¶: Return a copy of this query.

virtual bool empty() const = 0¶: Check if the query is empty, that is, it queries everything.

Public Static Functions

static std::unique_ptr<Query> create()¶: Create a new Query.

class Data¶

Key/value store where keys are strings and values are wreport variables.

Keys are defined from a known vocabulary, where each key has an associated wreport::Varinfo structure.

Subclassed by dballe::core::Data

Public Functions

virtual void clear() = 0¶: Remove all contents from the record.

virtual void clear_ids() = 0¶: Unset all database IDs in station and values.

virtual void clear_vars() = 0¶: Remove all Bxxyyy keys from the record, leaving the rest intact.

virtual bool operator==(const Data &rec) const = 0¶: Check if two records are the same.

virtual bool operator!=(const Data &rec) const = 0¶: Check if two records differ.

virtual void print(FILE *out) const = 0¶: Print the contents of this record to the given stream.

Public Static Functions

static std::unique_ptr<Data> create()¶: Create a new Record.

class DBConnectOptions¶

Options controlling how to connect to a database.

To allow to add members this structure without breaking the ABI, creation of new instances is restricted to DBConnectOptions::create().

Public Functions

void reset_actions()¶

Disable all the one-off actions set to perform on connection.

Call this after the first connection, if you need to reuse the DBConnectOptions multiple times.

Public Members

std::string url¶

URL to use to connect to the database.

See doc/fapi_connect.md for details.

bool wipe = false¶: Wipe database on connection.

Public Static Functions

static std::unique_ptr<DBConnectOptions> create(const std::string &url)¶: Create a DBConnectOptions parsing the given URL.

static std::unique_ptr<DBConnectOptions> test_create(const char *backend = nullptr)¶

Create a DBConnectOptions for running unit tests.

Optionally allows to select a backend database.

class DBImportOptions¶

Options controlling how messages are imported in the database.

To allow to add members this structure without breaking the ABI, creation of new instances is restricted to DBImportOptions::create().

Subclassed by dballe::impl::DBImportOptions

Public Members

std::string report¶

Report name to use to import data.

If left empty (default), then it will be chosen automatically based on the message type.

bool import_attributes = false¶: Import variable attributes.

bool update_station = false¶

Update station information.

If set to true, station information is merged with existing data in the database. If false (default), station information is imported only when the station did not exist in the database.

bool overwrite = false¶

Replace existing data.

If set to true, causes existing information already in the database to be overwritten. If false (default), trying to import a message which contains data already present in the database causes the import to fail.

std::vector<wreport::Varcode> varlist¶: If not empty, import only the given data values.

class DBInsertOptions¶

Options controlling how values are inserted in the database.

To allow to add members this structure without breaking the ABI, creation of new instances is restricted to DBInsertOptions::create().

Subclassed by dballe::impl::DBInsertOptions

Public Members

bool can_replace = false¶: If true, then existing data can be rewritten, else data can only be added.

bool can_add_stations = true¶

If false, it will not create a missing station record, and only data for existing stations can be added.

If true, then if we are inserting data for a station that does not yet exists in the database, it will be created.

Database¶

dballe

Navigation

Related Topics