Hyper API for C++  0.0.16377
Hyper client library for C++ applications
hyperapi::Catalog Class Referencefinal

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
 
Catalogoperator= (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. More...
 
TableDefinition getTableDefinition (const TableName &tableName) const
 Gets the table definition for an existing table. More...
 
void createSchema (const SchemaName &schemaName) const
 Creates a SQL schema with the given name. More...
 
void createSchemaIfNotExists (const SchemaName &schemaName) const
 Creates a SQL schema with the given name. More...
 
void createTable (const hyperapi::TableDefinition &table_definition) const
 Creates a SQL table with the given table definition. More...
 
void createTableIfNotExists (const hyperapi::TableDefinition &table_definition) const
 Creates a SQL table with the given table definition. More...
 
std::unordered_set< SchemaNamegetSchemaNames () const
 Gets the name of all schemas in the first database in the database search path. More...
 
std::unordered_set< SchemaNamegetSchemaNames (const DatabaseName &database) const
 Gets the names of all schemas in database. More...
 
std::unordered_set< TableNamegetTableNames (const SchemaName &schema) const
 Gets the names of all tables in the given schema. More...
 
void createDatabase (const std::string &databasePath)
 Creates a database file with the given path. More...
 
void createDatabaseIfNotExists (const std::string &databasePath)
 Creates a database file with the given path if it doesn't exist yet. More...
 
void detachDatabase (const DatabaseName &databaseName)
 Detaches a database from the underlying connection. More...
 
void attachDatabase (const std::string &databasePath, const DatabaseName &databaseName)
 Attaches a database file databasePath to the underlying connection under the name databaseName. More...
 
void attachDatabase (const std::string &databasePath)
 Attaches a database file databasePath to the underlying connection. More...
 
void detachAllDatabases ()
 Detaches all databases from the underlying connection. More...
 
void dropDatabase (const std::string &databasePath)
 Drops the database with the given path. More...
 
void dropDatabaseIfExists (const std::string &databasePath)
 Drops the database with the given path. More...
 
ConnectiongetConnection () 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
databasePathThe 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
databasePathThe path to the database file
databaseNameThe 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
databasePathThe 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
databasePathThe 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
schemaNameThe 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
schemaNameThe 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_definitionThe definition of the table.
Precondition
getConnection().isOpen()
Exceptions
HyperException
Examples
create_hyper_file_from_csv.cpp, and insert_data_into_multiple_tables.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_definitionThe 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
databaseNameThe 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
databasePathThe 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
databasePathThe path to the database.
Exceptions
HyperException
Precondition
getConnection().isOpen()

◆ 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
databaseThe 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
tableNameThe name of the table.
Returns
The table definition of the table.
Exceptions
HyperException
Precondition
getConnection().isOpen()

◆ 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
schemaThe (qualified) schema name.
Returns
The table names.
Exceptions
HyperException
Precondition
getConnection().isOpen()
Examples
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
tableThe 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: