The catalog class gives access to the metadata of the attached databases of a connection. More...

#include <Catalog.hpp>

Public Member Functions
	Catalog (const Catalog &)=delete

Catalog &	operator= (const Catalog &)=delete

	Catalog (Catalog &&)=delete

Catalog	operator= (Catalog &&)=delete

bool	hasTable (const TableName &table) const
	Checks whether a table with the given name exists.

TableDefinition	getTableDefinition (const TableName &tableName) const
	Gets the table definition for an existing table.

void	createSchema (const SchemaName &schemaName) const
	Creates a SQL schema with the given name.

void	createSchemaIfNotExists (const SchemaName &schemaName) const
	Creates a SQL schema with the given name.

void	createTable (const hyperapi::TableDefinition &table_definition) const
	Creates a SQL table with the given table definition.

void	createTableIfNotExists (const hyperapi::TableDefinition &table_definition) const
	Creates a SQL table with the given table definition.

std::unordered_set< SchemaName >	getSchemaNames () const
	Gets the name of all schemas in the first database in the database search path.

std::unordered_set< SchemaName >	getSchemaNames (const DatabaseName &database) const
	Gets the names of all schemas in `database`.

std::unordered_set< TableName >	getTableNames (const SchemaName &schema) const
	Gets the names of all tables in the given schema.

void	createDatabase (const std::string &databasePath)
	Creates a database file with the given path.

void	createDatabaseIfNotExists (const std::string &databasePath)
	Creates a database file with the given path if it doesn't exist yet.

void	detachDatabase (const DatabaseName &databaseName)
	Detaches a database from the underlying connection.

void	attachDatabase (const std::string &databasePath, const DatabaseName &databaseName)
	Attaches a database file `databasePath` to the underlying connection under the name `databaseName`.

void	attachDatabase (const std::string &databasePath)
	Attaches a database file `databasePath` to the underlying connection.

void	detachAllDatabases ()
	Detaches all databases from the underlying connection.

void	dropDatabase (const std::string &databasePath)
	Drops the database with the given path.

void	dropDatabaseIfExists (const std::string &databasePath)
	Drops the database with the given path.

Connection &	getConnection () const noexcept
	Returns the underlying connection.

Detailed Description

The catalog class gives access to the metadata of the attached databases of a connection.

It can be used to obtain information about certain schema objects, such as tables, to query the set of existing schema objects, and to manipulate those objects.

All manipulations and queries of this class could also be written in raw SQL. The catalog class is merely a convenience wrapper.

Examples: create_hyper_file_from_csv.cpp, insert_data_into_multiple_tables.cpp, insert_data_into_single_table.cpp, insert_data_with_expressions.cpp, insert_spatial_data_to_a_hyper_file.cpp, and read_and_print_data_from_existing_hyper_file.cpp.

Definition at line 31 of file Catalog.hpp.

Member Function Documentation

◆ attachDatabase() [1/2]

void hyperapi::Catalog::attachDatabase ( const std::string & databasePath )

Attaches a database file databasePath to the underlying connection.

Use the stem of the databasePath as name. E.g., "foo/bar.hyper" will use the name "bar"

Parameters

databasePath The path to the database file

Precondition: getConnection().isOpen()

Exceptions

HyperException

◆ attachDatabase() [2/2]

void hyperapi::Catalog::attachDatabase	(	const std::string &	databasePath,
		const DatabaseName &	databaseName
	)

Attaches a database file databasePath to the underlying connection under the name databaseName.

Parameters

databasePath	The path to the database file
databaseName	The name for the database

Precondition: getConnection().isOpen()

Exceptions

HyperException

◆ createDatabase()

void hyperapi::Catalog::createDatabase ( const std::string & databasePath )

Creates a database file with the given path.

Does not attach to it automatically. If a relative path is given, it will be relative to the working directory of the Hyper instance.

Parameters

databasePath The path for the new database. Has to end with ".hyper".

Exceptions

HyperException

Precondition: getConnection().isOpen()

◆ createDatabaseIfNotExists()

void hyperapi::Catalog::createDatabaseIfNotExists ( const std::string & databasePath )

Creates a database file with the given path if it doesn't exist yet.

Does not attach to it automatically. If a relative path is given, it will be relative to the working directory of the Hyper instance. Note: This method will throw if a file with the given path exists that is not a valid hyper database.

Parameters

databasePath The path for the new database. Has to end with ".hyper".

Exceptions

HyperException

Precondition: getConnection().isOpen()

◆ createSchema()

void hyperapi::Catalog::createSchema ( const SchemaName & schemaName ) const

Creates a SQL schema with the given name.

The method will throw if a schema with this name already exists.

Parameters

schemaName The name of the schema.

Precondition: getConnection().isOpen()

Exceptions

HyperException

Examples: insert_data_into_single_table.cpp, insert_data_with_expressions.cpp, and insert_spatial_data_to_a_hyper_file.cpp.

◆ createSchemaIfNotExists()

void hyperapi::Catalog::createSchemaIfNotExists ( const SchemaName & schemaName ) const

Creates a SQL schema with the given name.

The method will just silently do nothing if a schema with this name already exists.

Parameters

schemaName The name of the schema.

Precondition: getConnection().isOpen()

Exceptions

HyperException

◆ createTable()

void hyperapi::Catalog::createTable ( const hyperapi::TableDefinition & table_definition ) const

Creates a SQL table with the given table definition.

The method will throw if a table with this name already exists.

Parameters

table_definition The definition of the table.

Precondition: getConnection().isOpen()

Exceptions

HyperException

Examples: create_hyper_file_from_csv.cpp, insert_data_into_multiple_tables.cpp, insert_data_into_single_table.cpp, insert_data_with_expressions.cpp, and insert_spatial_data_to_a_hyper_file.cpp.

◆ createTableIfNotExists()

void hyperapi::Catalog::createTableIfNotExists ( const hyperapi::TableDefinition & table_definition ) const

Creates a SQL table with the given table definition.

The method will just silently do nothing if a table with this name already exists.

Parameters

table_definition The definition of the table.

Precondition: getConnection().isOpen()

Exceptions

HyperException

◆ detachAllDatabases()

void hyperapi::Catalog::detachAllDatabases ( )

Detaches all databases from the underlying connection.

If this connection was the only connection that was currently attached to these databases, then the database files will be unloaded, all updates will be written to disk, and the database file can be accessed externally (e.g., copied, moved, etc.).

Precondition: getConnection().isOpen()

Exceptions

HyperException

◆ detachDatabase()

void hyperapi::Catalog::detachDatabase ( const DatabaseName & databaseName )

Detaches a database from the underlying connection.

Parameters

databaseName The name of the database.

Precondition: getConnection().isOpen()

Exceptions

HyperException

◆ dropDatabase()

void hyperapi::Catalog::dropDatabase ( const std::string & databasePath )

Drops the database with the given path.

If a relative path is given, it will be relative to the working directory of the Hyper instance. Dropping a database will delete the corresponding database file.

Throws if a database file with the given path doesn't exist.

Parameters

databasePath The path to the database.

Exceptions

HyperException

Precondition: getConnection().isOpen()

◆ dropDatabaseIfExists()

void hyperapi::Catalog::dropDatabaseIfExists ( const std::string & databasePath )

Drops the database with the given path.

If a relative path is given, it will be relative to the working directory of the Hyper instance. Dropping a database will delete the corresponding database file.

Does nothing if a database file with the given path doesn't exist.

Parameters

databasePath The path to the database.

Exceptions

HyperException

Precondition: getConnection().isOpen()

◆ getConnection()

Connection & hyperapi::Catalog::getConnection ( ) const

inlinenoexcept

Returns the underlying connection.

Definition at line 221 of file Catalog.hpp.

◆ getSchemaNames() [1/2]

std::unordered_set< SchemaName > hyperapi::Catalog::getSchemaNames ( ) const

Gets the name of all schemas in the first database in the database search path.

Note that by default, this is the single database that is attached if only one database is attached. When multiple databases are attached, the database search path is empty by default and this method will fail. The user can set the database search path in this case to specify from which database to retrieve schema names.

Returns: The schema names.

Exceptions

HyperException

Precondition: getConnection().isOpen()

◆ getSchemaNames() [2/2]

std::unordered_set< SchemaName > hyperapi::Catalog::getSchemaNames ( const DatabaseName & database ) const

Gets the names of all schemas in database.

Parameters

database The name of the database.

Returns: The schema names.

Exceptions

HyperException

Precondition: getConnection().isOpen()

◆ getTableDefinition()

TableDefinition hyperapi::Catalog::getTableDefinition ( const TableName & tableName ) const

Gets the table definition for an existing table.

Note that the name of the table definition will always be fully qualified, even if the input name was not. E.g., if the user queries table "foo", which resolves to the table "db1"."bar"."foo", then the resulting TableDefinition will have the latter set as name.

Parameters

tableName The name of the table.

Returns: The table definition of the table.

Exceptions

HyperException

Precondition: getConnection().isOpen()

Examples: read_and_print_data_from_existing_hyper_file.cpp.

◆ getTableNames()

std::unordered_set< TableName > hyperapi::Catalog::getTableNames ( const SchemaName & schema ) const

Gets the names of all tables in the given schema.

If the schema name does not specify a database, the first database in the schema_search_path is used.

Parameters

schema The (qualified) schema name.

Returns: The table names.

Exceptions

HyperException

Precondition: getConnection().isOpen()

Examples: insert_data_into_single_table.cpp, and read_and_print_data_from_existing_hyper_file.cpp.

◆ hasTable()

bool hyperapi::Catalog::hasTable ( const TableName & table ) const

Checks whether a table with the given name exists.

Parameters

table The name of the table.

Returns: Whether the table exists.

Exceptions

HyperException

Precondition: getConnection().isOpen(); If a database name is specified, it has to refer to an attached database.

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

hyperapi/Catalog.hpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ attachDatabase() [1/2]

◆ attachDatabase() [2/2]

◆ createDatabase()

◆ createDatabaseIfNotExists()

◆ createSchema()

◆ createSchemaIfNotExists()

◆ createTable()

◆ createTableIfNotExists()

◆ detachAllDatabases()

◆ detachDatabase()

◆ dropDatabase()

◆ dropDatabaseIfExists()

◆ getConnection()

◆ getSchemaNames() [1/2]

◆ getSchemaNames() [2/2]

◆ getTableDefinition()

◆ getTableNames()

◆ hasTable()