INSERT statement

The INSERT statement inserts a row into a database table.

SYNTAX

A single row is inserted into the table identified by TableReference. The ColumnName list identifies those columns in the target table that are to be given specific values. These values are determined by the expressions within the VALUES clause (the first expression gives the value of the first named column, and so on). The number of expressions in the VALUES clause must be the same as the number of named columns. Any columns present in the table but not mentioned in the list are given their default values.

Table reference

A table reference is a special case of the field references used to refer to message trees. It always starts with the word "Database" and may contain any of the following:
  • A table name only
  • A schema name and a table name
  • A data source name (that is, the name of a database instance), a schema name, and a table name
In each case, the name may be specified directly or by an expression enclosed in braces ({...}). A directly-specified data source, schema, or table name is subject to name substitution. That is, if the name used has been declared to be a known name, the value of the declared name is used rather than the name itself (see DECLARE statement).

If a schema name is not specified, the default schema for the broker's database user is used.

If a data source name is not specified, the database pointed to by the node's data source attribute is used.

Handling errors

It is possible for errors to occur during insert operations. For example, the database may not be operational, or the table may have constraints defined which the new row would violate. In these cases, an exception is thrown (unless the node has its throw exception on database error property set to FALSE). These exceptions set appropriate SQL code, state, native error, and error text values and can be dealt with by error handlers (see the DECLARE HANDLER statement).

For further information about handling database errors, see Capturing database state.

Examples

The following example assumes that the dataSource property of the Database node has been configured, and that the database it identifies has a table called TABLE1 with columns A, B, and C.

Given a message with the following generic XML body:
<A>
 <B>1</B>
 <C>2</C>
 <D>3</D>
</A>
The following INSERT statement inserts a new row into the table with the values 1, 2, and 3 for the columns A, B, and C:
INSERT INTO Database.TABLE1(A, B, C) VALUES (Body.A.B, Body.A.C, Body.A.D);
The next example shows the use of calculated data source, schema, and table names:
-- Declare variables to hold the data source, schema, and table names
-- and set their default values
DECLARE Source CHARACTER 'Production';
DECLARE Schema CHARACTER 'db2admin';
DECLARE Table  CHARACTER 'DynamicTable1';

-- Code which calculates their actual values comes here

-- Insert the data into the tabl
INSERT INTO Database.{Source}.{Schema}.{Table} (Name, Value) values ('Joe', 12.34);
Related concepts
ESQL overview
Related tasks
Developing ESQL
Capturing database state
Related reference
Syntax diagrams: available types
ESQL statements