CatalogsDB::DBManager

CatalogsDB
DBManager

#include <catalogsdb.h>

Public Member Functions
	DBManager (const DBManager &other)

	DBManager (const QString &filename)

std::pair< bool, QString >	add_object (const int catalog_id, const CatalogObject &obj)

std::pair< bool, QString >	add_object (const int catalog_id, const SkyObject::TYPE t, const CachingDms &r, const CachingDms &d, const QString &n, const float m=NaN::f, const QString &lname=QString(), const QString &catalog_identifier=QString(), const float a=0.0, const float b=0.0, const double pa=0.0, const float flux=0)

std::pair< bool, QString >	add_objects (const int catalog_id, const CatalogObjectVector &objects)

bool	catalog_exists (const int id)

bool	compile_master_catalog ()

std::pair< bool, QString >	copy_objects (const int id_1, const int id_2)

const QString &	db_file_name () const

std::pair< bool, QString >	dump_catalog (int catalog_id, QString file_path)

CatalogObjectList	find_objects_by_name (const int catalog_id, const QString &name, const int limit=-1)

CatalogObjectList	find_objects_by_name (const QString &name, const int limit=-1, const bool exactMatchOnly=false)

CatalogObjectList	find_objects_by_wildcard (const QString &wildcard, const int limit=-1)

int	find_suitable_catalog_id ()

std::tuple< bool, const QString, CatalogObjectList >	general_master_query (const QString &where, const QString &order_by="", const int limit=-1)

const std::pair< bool, Catalog >	get_catalog (const int id)

ColorMap	get_catalog_colors ()

CatalogColorMap	get_catalog_colors (const int id)

const std::pair< bool, CatalogStatistics >	get_catalog_statistics (const int catalog_id)

const std::vector< Catalog >	get_catalogs (bool include_disabled=false)

const std::pair< bool, CatalogStatistics >	get_master_statistics ()

std::pair< bool, CatalogObject >	get_object (const CatalogObject::oid &oid)

std::pair< bool, CatalogObject >	get_object (const CatalogObject::oid &oid, const int catalog_id)

CatalogObjectList	get_objects (float maglim=default_maglim, int limit=-1)

CatalogObjectList	get_objects (SkyObject::TYPE type, float maglim=default_maglim, int limit=-1)

CatalogObjectList	get_objects_all ()

CatalogObjectList	get_objects_in_catalog (SkyObject::TYPE type, const int catalog_id, float maglim=default_maglim, int limit=-1)

CatalogObjectVector	get_objects_in_trixel (const int trixel)

CatalogObjectVector	get_objects_in_trixel_no_nulls (const int trixel)

CatalogObjectVector	get_objects_in_trixel_null_mag (const int trixel)

int	htmesh_level () const

std::pair< bool, QString >	import_catalog (const QString &file_path, const bool overwrite=false)

std::pair< bool, QString >	insert_catalog_colors (const int id, const CatalogColorMap &colors)

DBManager &	operator= (DBManager other)

std::pair< bool, QString >	register_catalog (const Catalog &cat)

std::pair< bool, QString >	register_catalog (const int id, const QString &name, const bool mut, const bool enabled, const double precedence, const QString &author=cat_defaults.author, const QString &source=cat_defaults.source, const QString &description=cat_defaults.description, const int version=cat_defaults.version, const QString &color=cat_defaults.color, const QString &license=cat_defaults.license, const QString &maintainer=cat_defaults.maintainer, const QDateTime &timestamp=cat_defaults.timestamp)

std::pair< bool, QString >	remove_catalog (const int id)

std::pair< bool, QString >	remove_object (const int catalog_id, const CatalogObject::oid &id)

std::pair< bool, QString >	set_catalog_enabled (const int id, const bool enabled)

std::pair< bool, QString >	update_catalog_meta (const Catalog &cat)

bool	update_catalog_views ()

Detailed Description

Manages the catalog database and provides an interface to provide an interface to query and modify the database.

For more information on how the catalog database system works see the KStars Handbook.

The class manages a database connection which is assumed to be working (invariant). If the database can't be accessed a DatabaseError is thrown upon construction. The manager is designed to hold as little state as possible because the database should be the single source of truth. Prepared statements are made class members, only if they are performance critical.

Most methods in this class are thread safe.

The intention is that you access a/the catalogs database directly locally in the code where objects from the database are required and not through layers of references and pointers.

The main DSO database can be accessed as follows:

CatalogsDB::DBManager manager{ CatalogsDB::dso_db_path() };
for(auto& o : manager.get_objects(10)) {
    // do something
}

To query the database, first check if the required query is already hardcoded into the DBManager. If this is not the case you can either add it (if it is performance critical and executed frequently) or use DBManager::general_master_query to construct a custom SQL query.

Definition at line 182 of file catalogsdb.h.

Constructor & Destructor Documentation

◆ DBManager()

DBManager::DBManager ( const QString & filename )

Constructs a database manager from the filename which is resolved to a path in the kstars data directory.

The constructor resolves the path to the database, opens it (throws if that does not work), checks the database version (throws if that does not match), initializes the database, registers the user catalog and updates the all_catalog_view.

Definition at line 81 of file catalogsdb.cpp.

Member Function Documentation

◆ add_object() [1/2]

std::pair< bool, QString > DBManager::add_object	(	const int	catalog_id,
		const CatalogObject &	obj
	)

Add the object to a table with catalog_id.

For the rest of the arguments see CatalogObject::CatalogObject.

Returns: wether the operation was successful and if not, an error message

Definition at line 678 of file catalogsdb.cpp.

◆ add_object() [2/2]

std::pair< bool, QString > DBManager::add_object	(	const int	catalog_id,
		const SkyObject::TYPE	t,
		const CachingDms &	r,
		const CachingDms &	d,
		const QString &	n,
		const float	m = `NaN::f`,
		const QString &	lname = `QString()`,
		const QString &	catalog_identifier = `QString()`,
		const float	a = `0.0`,
		const float	b = `0.0`,
		const double	pa = `0.0`,
		const float	flux = `0`
	)

Add a CatalogObject to a table with catalog_id.

For the rest of the arguments see CatalogObject::CatalogObject.

Returns: wether the operation was successful and if not, an error message

Definition at line 687 of file catalogsdb.cpp.

◆ add_objects()

std::pair< bool, QString > CatalogsDB::DBManager::add_objects	(	const int	catalog_id,
		const CatalogObjectVector &	objects
	)

Add the objects to a table with catalog_id.

For the rest of the arguments see CatalogObject::CatalogObject.

Returns: wether the operation was successful and if not, an error message

Definition at line 1042 of file catalogsdb.cpp.

◆ catalog_exists()

bool DBManager::catalog_exists ( const int id )

Returns: true if the catalog with id exists

Todo:: use std::optional when transitioning to c++17

Definition at line 395 of file catalogsdb.cpp.

◆ compile_master_catalog()

bool DBManager::compile_master_catalog ( )

Compiles the master catalog by merging the individual catalogs based on oid and precedence and creates an index by (trixel, magnitude) on the master table.

Caution you may want to call update_catalog_views beforhand.

Returns: true in case of success, false in case of an error

Definition at line 337 of file catalogsdb.cpp.

◆ copy_objects()

std::pair< bool, QString > DBManager::copy_objects	(	const int	id_1,
		const int	id_2
	)

Clone objects from the catalog with id_1 to another with id_2.

Useful to create a custom catalog from an immutable one.

Definition at line 913 of file catalogsdb.cpp.

◆ db_file_name()

const QString& CatalogsDB::DBManager::db_file_name ( ) const

inline

Returns: the filename of the database

Definition at line 227 of file catalogsdb.h.

◆ dump_catalog()

std::pair< bool, QString > DBManager::dump_catalog	(	int	catalog_id,
		QString	file_path
	)

Dumps the catalog with id into the file under the path file_path.

This file can then be imported with import_catalog. If the file already exists, it will be overwritten.

The user_version and application_id pragmas are set to special values, but otherwise the dump format is equal to the internal database format.

Returns: wether the operation was successful and if not, an error message

Definition at line 738 of file catalogsdb.cpp.

◆ find_objects_by_name() [1/2]

CatalogObjectList DBManager::find_objects_by_name	(	const int	catalog_id,
		const QString &	name,
		const int	limit = `-1`
	)

Find an objects by name in the catalog with catalog_id.

Returns: a list of matching objects

Definition at line 517 of file catalogsdb.cpp.

◆ find_objects_by_name() [2/2]

CatalogObjectList DBManager::find_objects_by_name	(	const QString &	name,
		const int	limit = `-1`,
		const bool	exactMatchOnly = `false`
	)

Find an objects by name.

This will search the name, long_name and catalog_identifier fields in all enabled catalogs for name and then return a new instance of CatalogObject sourced from the master catalog.

Parameters

limit	Upper limit to the quanitity of results. `-1` means "no limit"
exactMatchOnly	If true, the supplied name must match exactly

Returns: a list of matching objects

Definition at line 490 of file catalogsdb.cpp.

◆ find_objects_by_wildcard()

CatalogObjectList CatalogsDB::DBManager::find_objects_by_wildcard	(	const QString &	wildcard,
		const int	limit = `-1`
	)

Find an objects by searching the name four wildcard.

See the LIKE sqlite statement.

Returns: a list of matching objects

Definition at line 1077 of file catalogsdb.cpp.

◆ find_suitable_catalog_id()

int DBManager::find_suitable_catalog_id ( )

Finds the smallest free id for a catalog.

Definition at line 953 of file catalogsdb.cpp.

◆ general_master_query()

std::tuple< bool, const QString, CatalogObjectList > CatalogsDB::DBManager::general_master_query	(	const QString &	where,
		const QString &	order_by = `""`,
		const int	limit = `-1`
	)

Find an objects by searching the master catlog with a query like SELECT ...

FROM master WHERE \p where ORDER BY \p order_by ....

To be used if performance does not matter (much). order_by can be ommitted.

Returns: wether the query was successful, an error message if any and a list of matching objects

Definition at line 1094 of file catalogsdb.cpp.

◆ get_catalog()

const std::pair< bool, Catalog > DBManager::get_catalog ( const int id )

Returns: wether the catalog with the id has been found and the catalog.

Todo:: use std::optional when transitioning to c++17

Definition at line 378 of file catalogsdb.cpp.

◆ get_catalog_colors() [1/2]

ColorMap CatalogsDB::DBManager::get_catalog_colors ( )

Returns: the catalog colors as a hash table of the form catalog id: scheme: color.

The colors are loaded from the Catalog::color field and the SqlStatements::color_table in that order.

Definition at line 1163 of file catalogsdb.cpp.

◆ get_catalog_colors() [2/2]

CatalogsDB::CatalogColorMap CatalogsDB::DBManager::get_catalog_colors ( const int id )

Returns: the catalog colors as a hash table of for the catalog with id in the form scheme: color.

The colors are loaded from the Catalog::color field and the SqlStatements::color_table in that order.

Definition at line 1189 of file catalogsdb.cpp.

◆ get_catalog_statistics()

const std::pair< bool, CatalogStatistics > DBManager::get_catalog_statistics ( const int catalog_id )

Returns: statistics about the catalog with catalog_id.

Definition at line 1032 of file catalogsdb.cpp.

◆ get_catalogs()

const std::vector< Catalog > DBManager::get_catalogs ( bool include_disabled = false )

Returns: a vector with all catalogs from the database. If include_disabled is true, disabled catalogs will be included.

Definition at line 621 of file catalogsdb.cpp.

◆ get_master_statistics()

const std::pair< bool, CatalogStatistics > DBManager::get_master_statistics ( )

Returns: statistics about the master catalog.

Definition at line 1022 of file catalogsdb.cpp.

◆ get_object()

std::pair< bool, CatalogObject > DBManager::get_object ( const CatalogObject::oid & oid )

Get an object by oid.

Optinally a catalog_id can be speicfied.

Returns: if the object was found and the object itself

Definition at line 538 of file catalogsdb.cpp.

◆ get_objects() [1/2]

CatalogObjectList DBManager::get_objects	(	float	maglim = `default_maglim`,
		int	limit = `-1`
	)

Get limit objects with magnitude smaller than maglim (smaller = brighter) from the database.

Definition at line 562 of file catalogsdb.cpp.

◆ get_objects() [2/2]

CatalogObjectList DBManager::get_objects	(	SkyObject::TYPE	type,
		float	maglim = `default_maglim`,
		int	limit = `-1`
	)

Get limit objects of type with magnitude smaller than maglim (smaller = brighter) from the database.

Optionally one can filter by catalog_id.

Definition at line 579 of file catalogsdb.cpp.

◆ get_objects_all()

CatalogObjectList DBManager::get_objects_all ( )

Get all objects from the database.

Definition at line 571 of file catalogsdb.cpp.

◆ get_objects_in_catalog()

CatalogObjectList DBManager::get_objects_in_catalog	(	SkyObject::TYPE	type,
		const int	catalog_id,
		float	maglim = `default_maglim`,
		int	limit = `-1`
	)

Get limit objects from the catalog with catalog_id of type with magnitude smaller than maglim (smaller = brighter) from the database.

Optionally one can filter by catalog_id.

Definition at line 589 of file catalogsdb.cpp.

◆ get_objects_in_trixel()

CatalogObjectVector CatalogsDB::DBManager::get_objects_in_trixel ( const int trixel )

inline

Returns: return a vector of objects in the trixel with id.

Definition at line 253 of file catalogsdb.h.

◆ get_objects_in_trixel_no_nulls()

CatalogObjectVector CatalogsDB::DBManager::get_objects_in_trixel_no_nulls ( const int trixel )

inline

Returns: return a vector of objects of known mag in the trixel with id.

Definition at line 260 of file catalogsdb.h.

◆ get_objects_in_trixel_null_mag()

CatalogObjectVector CatalogsDB::DBManager::get_objects_in_trixel_null_mag ( const int trixel )

inline

Returns: return a vector of objects of unknown mag in the trixel with id.

Definition at line 267 of file catalogsdb.h.

◆ htmesh_level()

int CatalogsDB::DBManager::htmesh_level ( ) const

inline

Returns: return the htmesh level used by the catalog db

Definition at line 358 of file catalogsdb.h.

◆ import_catalog()

std::pair< bool, QString > DBManager::import_catalog	(	const QString &	file_path,
		const bool	overwrite = `false`
	)

Loads a dumped catalog from path file_path.

Will overwrite an existing catalog if overwrite is set to true. Immutable catalogs are overwritten by default.

Checks if the pragma application_id matches CatalogsDB::application_id and the pragma user_version to match the database format version.

Returns: wether the operation was successful and if not, an error message

Definition at line 800 of file catalogsdb.cpp.

◆ insert_catalog_colors()

std::pair< bool, QString > CatalogsDB::DBManager::insert_catalog_colors	(	const int	id,
		const CatalogColorMap &	colors
	)

Saves the configures colors of the catalog with id id in colors into the database.

Returns: wether the insertion was possible and an error message if not.

Definition at line 1195 of file catalogsdb.cpp.

◆ register_catalog()

std::pair< bool, QString > DBManager::register_catalog	(	const int	id,
		const QString &	name,
		const bool	mut,
		const bool	enabled,
		const double	precedence,
		const QString &	author = `cat_defaults.author`,
		const QString &	source = `cat_defaults.source`,
		const QString &	description = `cat_defaults.description`,
		const int	version = `cat_defaults.version`,
		const QString &	color = `cat_defaults.color`,
		const QString &	license = `cat_defaults.license`,
		const QString &	maintainer = `cat_defaults.maintainer`,
		const QDateTime &	timestamp = `cat_defaults.timestamp`
	)

Registers a new catalog in the database.

For the parameters

See also: Catalog. The catalog gets inserted into m_catalogs. The all_catalog_view is updated.

Returns: true in case of success, false in case of an error (along with the error)

Definition at line 309 of file catalogsdb.cpp.

◆ remove_catalog()

std::pair< bool, QString > DBManager::remove_catalog ( const int id )

remove a catalog

Returns: true in case of succes, false and an error message in case of an error

This will recreate the master table.

Definition at line 879 of file catalogsdb.cpp.

◆ remove_object()

std::pair< bool, QString > DBManager::remove_object	(	const int	catalog_id,
		const CatalogObject::oid &	id
	)

Remove the catalog object with the oid from the catalog with the catalog_id.

Refreshes the master catalog.

Returns: wether the operation was successful and if not, an error message

Definition at line 723 of file catalogsdb.cpp.

◆ set_catalog_enabled()

std::pair< bool, QString > DBManager::set_catalog_enabled	(	const int	id,
		const bool	enabled
	)

Enable or disable a catalog.

Returns: true in case of succes, false and an error message in case of an error

This will recreate the master table.

Definition at line 602 of file catalogsdb.cpp.

◆ update_catalog_meta()

std::pair< bool, QString > DBManager::update_catalog_meta ( const Catalog & cat )

Update the metatadata catalog.

The updated fields are: title, author, source, description.

Returns: true in case of success, false in case of an error (along with the error).

Definition at line 932 of file catalogsdb.cpp.

◆ update_catalog_views()

bool DBManager::update_catalog_views ( )

Updates the all_catalog_view so that it includes all known catalogs.

Returns: true in case of success, false in case of an error

Definition at line 242 of file catalogsdb.cpp.

The documentation for this class was generated from the following files:

CatalogsDB::DBManager

Manages the catalog database and provides an interface to provide an interface to query and modify th...

Definition: catalogsdb.h:182

KDE's Doxygen guidelines are available online.

Class Picker

Quick Links

About Kstars

CatalogsDB::DBManager

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ DBManager()

Member Function Documentation

◆ add_object() [1/2]

◆ add_object() [2/2]

◆ add_objects()

◆ catalog_exists()

◆ compile_master_catalog()

◆ copy_objects()

◆ db_file_name()

◆ dump_catalog()

◆ find_objects_by_name() [1/2]

◆ find_objects_by_name() [2/2]

◆ find_objects_by_wildcard()

◆ find_suitable_catalog_id()

◆ general_master_query()

◆ get_catalog()

◆ get_catalog_colors() [1/2]

◆ get_catalog_colors() [2/2]

◆ get_catalog_statistics()

◆ get_catalogs()

◆ get_master_statistics()

◆ get_object()

◆ get_objects() [1/2]

◆ get_objects() [2/2]

◆ get_objects_all()

◆ get_objects_in_catalog()

◆ get_objects_in_trixel()

◆ get_objects_in_trixel_no_nulls()

◆ get_objects_in_trixel_null_mag()

◆ htmesh_level()

◆ import_catalog()

◆ insert_catalog_colors()

◆ register_catalog()

◆ remove_catalog()

◆ remove_object()

◆ set_catalog_enabled()

◆ update_catalog_meta()

◆ update_catalog_views()