An inserter. More...

#include <Inserter.hpp>

Classes
class	ColumnMapping
	Maps an expression to a column More...

Public Member Functions
	Inserter (Connection &connection, const TableName &name)
	Creates an inserter on a table.

	Inserter (Connection &connection, const TableName &name, std::vector< std::string > columns)
	Creates an inserter on a table.

	Inserter (Connection &connection, hyperapi::TableDefinition tableDefinition)
	Creates an inserter on a table.

	Inserter (Connection &connection, const hyperapi::TableDefinition &tableDefinition, std::vector< std::string > columns)
	Creates an inserter on a table.

	Inserter (Connection &connection, const hyperapi::TableDefinition &tableDefinition, std::vector< Inserter::ColumnMapping > columnMappings, std::vector< TableDefinition::Column > inserterDefinition)
	Creates an inserter for an existing table.

	Inserter (Connection &connection, const TableName &name, std::vector< Inserter::ColumnMapping > columnMappings, std::vector< TableDefinition::Column > inserterDefinition)
	Creates an inserter for an existing table.

	Inserter ()
	Constructs an `Inserter` object that does not represent an inserter.

	~Inserter () noexcept
	Destroys the inserter.

	Inserter (Inserter &&other) noexcept
	Move constructor.

Inserter &	operator= (Inserter &&other) noexcept
	Move assignment.

	Inserter (const Inserter &)=delete
	Copy forbidden.

Inserter &	operator= (const Inserter &)=delete

template<typename ValueType >
Inserter &	add (ValueType value)
	Sets the current field to the given value.

template<typename... ValueTypes>
Inserter &	addRow (ValueTypes... values)
	Inserts all given values.

Inserter &	endRow ()
	Advances the inserter to the next row.

bool	isOpen () const noexcept
	Returns whether the inserter is open.

void	execute ()
	Submits the previously added data.

void	close () noexcept
	Closes the inserter.

Detailed Description

An inserter.

Used to insert data into existing tables in Hyper. The insertion happens row by row. Inside one row, all the columns have to be added sequentially in the right order. Note: While this resource is open, the connection is busy.

Examples: 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.

Definition at line 24 of file Inserter.hpp.

Constructor & Destructor Documentation

◆ Inserter() [1/7]

hyperapi::Inserter::Inserter	(	Connection &	connection,
		const TableName &	name
	)

Creates an inserter on a table.

Parameters

connection	The connection to the Hyper instance containing the table.
name	The name of the table.

Exceptions

HyperException in case of error

Precondition: connection.isOpen()

Postcondition: isOpen()

◆ Inserter() [2/7]

hyperapi::Inserter::Inserter	(	Connection &	connection,
		const TableName &	name,
		std::vector< std::string >	columns
	)

Creates an inserter on a table.

Parameters

connection	The connection to the Hyper instance containing the table.
name	The name of the table.
columns	The set of columns in which to insert. The columns have to exist in the table.

Exceptions

HyperException in case of error

Precondition: connection.isOpen(); all given columns are part of the table definition

Postcondition: isOpen()

◆ Inserter() [3/7]

hyperapi::Inserter::Inserter	(	Connection &	connection,
		hyperapi::TableDefinition	tableDefinition
	)

Creates an inserter on a table.

Note: Will not keep a reference to the table definition. You can modify it afterwards.

Parameters

connection	The connection to the Hyper instance containing the table.
tableDefinition	The table definition for the table into which the data is inserted.

Exceptions

HyperException in case of error

Precondition: connection.isOpen()

Postcondition: isOpen()

◆ Inserter() [4/7]

hyperapi::Inserter::Inserter	(	Connection &	connection,
		const hyperapi::TableDefinition &	tableDefinition,
		std::vector< std::string >	columns
	)

Creates an inserter on a table.

Note: Will not keep a reference to the table definition. You can modify it afterwards.

Parameters

connection	The connection to the Hyper instance containing the table.
tableDefinition	The table definition for the table into which the data is inserted.
columns	The set of columns into which to insert. The columns have to be contained in the `table_definition`.

Exceptions

HyperException in case of error

Precondition: connection.isOpen(); all given columns are part of the table definition

Postcondition: isOpen()

◆ Inserter() [5/7]

hyperapi::Inserter::Inserter	(	Connection &	connection,
		const hyperapi::TableDefinition &	tableDefinition,
		std::vector< Inserter::ColumnMapping >	columnMappings,
		std::vector< TableDefinition::Column >	inserterDefinition
	)

Creates an inserter for an existing table.

Note: Will not keep a reference to the table definition. You can modify it afterwards. Note: SQL expression provided during insertion are used without any modification during insertion and hence vulnerable to SQL injection attacks. Applications must prevent end-users from providing expressions directly during insertion

Parameters

connection	The connection to the Hyper instance containing the table.
tableDefinition	The name of the table.
columnMappings	The set of columns in which to insert. The columns have to exist in the table. The columnMappings cannot be empty. Columns not present in columMappings will be set to their default value. A columnMapping can optionally contain a valid SQL expression. The SQL expression specified for the column is used to transform or compute values on the fly during insertion. The SQL expression can depend on columns that exist in the table. The SQL expression can also depend on values or columns that do not exist in the table, but must be specified in the `inserterDefinition`.
inserterDefinition	The definition of columns to which values are provided. The column definition for all the columns without SQL expression must be specified in `inserterDefinition`. For a column without SQL expression the column definition provided in `inserterDefinition` must match the actual definition of the column in the table. All columns used by SQL expressions specified in `columnMappings` must be in `inserterDefinition`.

Exceptions

HyperException in case of error

Precondition: connection.isOpen(); all columns in columnMappings are part of the table definition; columns without expressions are provided in the inserter definition

Postcondition: isOpen()

Consider the following pseudo-code on how to transform or compute values on the fly during insertion: TableDefinition : [TableName="example", Columns=["ColumnA" as INT, "ColumnB" as BIG_INT]] ColumnMapping : [[Name: "ColumnA"], [Name:"ColumnB", Expression:"ColumnA"*"ColumnC"]] InserterDefinition : ["ColumnA" integer, "ColumnC" integer]

Notice that "ColumnA" does not specify an expression and "ColumnB" is a product of "ColumnA" and "ColumnC", but "ColumnC" is not part of the table. The InserterDefinition contains "ColumnA" and "ColumnC" "ColumnA" since it is not computed on the fly and has to be provided to the inserter "ColumnC" since it is specified in the SQL expression that computes "ColumnB" on the fly

try (Inserter inserter(conn, "example", columnMapping, inserterDefinition)) { inserter.add(2).add(3).endRow(); inserter.execute(); } The insertion code snippet above inserts 2 into "ColumnA" and 6 into "ColumnB" (product of 2 and 3)

◆ Inserter() [6/7]

hyperapi::Inserter::Inserter	(	Connection &	connection,
		const TableName &	name,
		std::vector< Inserter::ColumnMapping >	columnMappings,
		std::vector< TableDefinition::Column >	inserterDefinition
	)

Creates an inserter for an existing table.

Note: Will not keep a reference to the table definition. You can modify it afterwards. Note: SQL expression provided during insertion are used without any modification during insertion and hence vulnerable to SQL injection attacks. Applications must prevent end-users from providing expressions directly during insertion

Parameters

connection	The connection to the Hyper instance containing the table.
name	The name of the table.
columnMappings	The set of columns in which to insert. The columns have to exist in the table. The columnMappings cannot be empty. Columns not present in columMappings will be set to their default value. A columnMapping can optionally contain a valid SQL expression. The SQL expression specified for a column is used to transform or compute values on the fly during insertion. The SQL expression can depend on columns that exist in the table. The SQL expression can also depend on values or columns that do not exist in the table, but must be specified in the `inserterDefinition`.
inserterDefinition	The definition of columns to which values are provided. The column definition for all the columns without SQL expression must be specified in `inserterDefinition`. For a column without SQL expression the column definition provided in `inserterDefinition` must match the actual definition of the column in the table. All columns that SQL expressions specified in `columnMappings` must be in `inserterDefinition`.

Exceptions

HyperException in case of error

Precondition: connection.isOpen(); all columns in columnMappings are part of the table definition; columns without expressions are provided in the inserter definition

Postcondition: isOpen()

Consider the following pseudo-code on how to transform or compute values on the fly during insertion: TableDefinition : [TableName="example", Columns=["ColumnA" as INT, "ColumnB" as BIG_INT]] ColumnMapping : [[Name: "ColumnA"], [Name:"ColumnB", Expression:"ColumnA"*"ColumnC"]] InserterDefinition : ["ColumnA" integer, "ColumnC" integer]

Notice that "ColumnA" does not specify an expression and "ColumnB" is a product of "ColumnA" and "ColumnC", but "ColumnC" is not part of the table. The InserterDefinition contains "ColumnA" and "ColumnC" "ColumnA" since it is not computed on the fly and has to be provided to the inserter "ColumnC" since it is specified in the SQL expression that computes "ColumnB" on the fly

try (Inserter inserter(conn, "example", columnMapping, inserterDefinition)) { inserter.add(2).add(3).endRow(); inserter.execute(); } The insertion code snippet above inserts 2 into "ColumnA" and 6 into "ColumnB" (product of 2 and 3)

◆ Inserter() [7/7]

hyperapi::Inserter::Inserter ( )

inline

Constructs an Inserter object that does not represent an inserter.

Postcondition: !isOpen()

Exceptions

bad_alloc in case of error

Definition at line 200 of file Inserter.hpp.

◆ ~Inserter()

hyperapi::Inserter::~Inserter ( )

noexcept

Destroys the inserter.

Discards all data if the insert was not executed.

Member Function Documentation

◆ add()

template<typename ValueType >

Inserter & hyperapi::Inserter::add ( ValueType value )

Sets the current field to the given value.

If the current field is nullable, you can insert optional<Type>.

The following types are supported: short int long long long bool float double hyperapi::Numeric<precision, scale> uint32_t hyperapi::string_view ByteSpan hyperapi::Interval hyperapi::Date hyperapi::Time hyperapi::Timestamp hyperapi::OffsetTimestamp

Calling the method advances the current field.

Template Parameters

ValueType The type of the value to insert.

Parameters

value The value.

Returns: *this, to allow call chaining

Precondition: isOpen(); The SQL type of the current column has to be compatible.; There is at least one column left in the current row.

Exceptions

HyperException in case of error

◆ addRow()

template<typename... ValueTypes>

Inserter & hyperapi::Inserter::addRow ( ValueTypes... values )

Inserts all given values.

Implicitly calls endRow().

See also: add(ValueType value)

Returns: *this, to allow call chaining

Precondition: isOpen(); The SQL type of the current column has to be compatible.; There is at least one column left in the current row.

◆ close()

void hyperapi::Inserter::close ( )

noexcept

Closes the inserter.

Closing the inserter discards all data if the insert was not executed.

Postcondition: !isOpen()

◆ endRow()

Inserter & hyperapi::Inserter::endRow ( )

Advances the inserter to the next row.

May cause the inserter to send data over the connection. The next add method will insert into the first column again.

Returns: *this, to allow call chaining.

Exceptions

HyperException in case of error

Precondition: isOpen(); All columns of the current row are added.

◆ execute()

void hyperapi::Inserter::execute ( )

Submits the previously added data.

If this operation succeeds without throwing, all previously added data is sent to Hyper; otherwise all data is discarded. In either way, the inserter will be closed once this method completes.

Exceptions

HyperException in case of error

Precondition: isOpen(); endRow() was called for all inserted rows.

Postcondition: !isOpen()

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

hyperapi/Inserter.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Inserter() [1/7]

◆ Inserter() [2/7]

◆ Inserter() [3/7]

◆ Inserter() [4/7]

◆ Inserter() [5/7]

◆ Inserter() [6/7]

◆ Inserter() [7/7]

◆ ~Inserter()

Member Function Documentation

◆ add()

◆ addRow()

◆ close()

◆ endRow()

◆ execute()