INSERT - Kinetica Docs

There are two methods for inserting data into a table from within the database:

When specifying a column list using either method, any non-nullable fields not included in the list will be given default values—empty string for strings, and 0 for numerics. The fields in the column list and the values or fields selected must align.

If Multi-Head Ingest has been enabled on the database server, INSERT operations will automatically leverage it, when applicable.

See Loading Data for inserting data into a table from sources external to the database.

INSERT INTO … VALUES

Records with literal values can be inserted into the database.

INSERT INTO ... VALUES Syntax

INSERT INTO [<schema name>.]<table name> [(<column list>)]
VALUES (<column value list>)[,...]
[ON CONFLICT (<conflict column list>)
<
    DO NOTHING
    |
    DO UPDATE SET
    <
        <column 1> = <expression 1>,
        ...
        <column n> = <expression n>
        |
        (<column list>) = (<sub-select statement>)
    >
>
]
[WITH OPTIONS (<insert option name> = '<insert option value>'[,...])]

INSERT INTO ... VALUES Example

INSERT INTO example.employee (id, dept_id, manager_id, first_name, last_name, sal, hire_date)
VALUES
    (1, 1, null, 'Anne', 'Arbor', 200000, '2000-01-01'),
    (2, 2, 1, 'Brooklyn', 'Bridges', 100000, '2000-02-01'),
    (3, 3, 1, 'Cal', 'Cutta', 100000, '2000-03-01'),
    (4, 2, 2, 'Dover', 'Della', 150000, '2000-04-01'),
    (5, 2, 2, 'Elba', 'Eisle', 50000, '2000-05-01'),
    (6, 4, 1, 'Frank', 'Furt', 12345.67, '2000-06-01')

Insert Options

The following options can be specified to modify the way data is inserted (or not inserted) into the target table.

The WITH OPTIONS clause is only valid when used within JDBC.

BATCH SIZE

Use an ingest batch size of the given number of records.The default batch size is 50,000.

ON ERROR

When an error is encountered inserting a record, handle it using one of the following modes. The default mode is ABORT.

Mode	Description
`PERMISSIVE`	If an error is encountered parsing a source record, attempt to insert as many of the valid fields from the record as possible; insert a null for each errant value found.
`SKIP`	If an error is encountered parsing a source record, skip the record.
`ABORT`	If an error is encountered parsing a source record, stop the insert process. Primary key collisions are considered abortable errors in this mode.

ON CONFLICT

The ON CONFLICT clause controls the behavior when an inserted record conflicts with an existing record on the specified columns. Use DO NOTHING to silently discard the conflicting record, or DO UPDATE SET to update the existing record with new values.

The ON CONFLICT clause is only valid when used within an /execute/sql call.

Within the DO UPDATE SET clause, the special EXCLUDED reference provides access to the values of the record that was proposed for insertion.

INSERT INTO ... VALUES ... ON CONFLICT Example

INSERT INTO example.employee (id, dept_id, manager_id, first_name, last_name, sal, hire_date)
VALUES
    (6, 4, 1, 'Frank', 'Furt', 24680.50, '2000-06-01'),
    (7, 3, 3, 'George', 'Towne', 103050, '2000-03-02')
ON CONFLICT (id)
DO UPDATE SET
    last_name = EXCLUDED.last_name,
    dept_id = EXCLUDED.dept_id,
    manager_id = EXCLUDED.manager_id,
    sal = EXCLUDED.sal

INSERT INTO … SELECT

Records that are the result set of a query can be inserted into the database.

INSERT INTO ... SELECT Syntax

INSERT INTO [<schema name>.]<table name> [(<column list>)]
<select statement>
[ON CONFLICT (<conflict column list>)
<
    DO NOTHING
    |
    DO UPDATE SET
    <
        <column 1> = <expression 1>,
        ...
        <column n> = <expression n>
        |
        (<column list>) = (<sub-select statement>)
    >
>
]

INSERT INTO ... SELECT Example

INSERT INTO example.employee_backup (id, dept_id, manager_id, first_name, last_name, sal)
SELECT id, dept_id, manager_id, first_name, last_name, sal
FROM example.employee
WHERE hire_date >= '2000-04-01'

The ON CONFLICT clause can also be used with INSERT INTO ... SELECT. See ON CONFLICT for details.

ON CONFLICT

The ON CONFLICT clause is only valid when used within an /execute/sql call.

Within the DO UPDATE SET clause, the special EXCLUDED reference provides access to the values of the record that was proposed for insertion.

INSERT INTO ... SELECT ... ON CONFLICT Example

INSERT INTO example.employee_backup (id, dept_id, manager_id, first_name, last_name, sal, hire_date)
SELECT id, dept_id, manager_id, first_name, last_name, sal, hire_date
FROM example.employee
WHERE hire_date >= '2000-04-01'
ON CONFLICT (id)
DO UPDATE SET
    last_name = EXCLUDED.last_name,
    dept_id = EXCLUDED.dept_id,
    manager_id = EXCLUDED.manager_id,
    sal = EXCLUDED.sal

Upserting

To upsert records, inserting new records and updating existing ones (as denoted by primary key), use the KI_HINT_UPDATE_ON_EXISTING_PK hint. If the target table has no primary key, this hint will be ignored.

This hint can be specified as the connection option UpdateOnExistingPk when using JDBC/ODBC.

Upsert Example

INSERT INTO example.employee_backup /* KI_HINT_UPDATE_ON_EXISTING_PK */
SELECT *
FROM example.employee
WHERE hire_date >= '2000-01-01'

By default, any record being inserted that matches the primary key of an existing record in the target table will be discarded, and the existing record will remain unchanged. The KI_HINT_UPDATE_ON_EXISTING_PK hint overrides this behavior, favoring the source records over the target ones.

Ignoring Duplicates

To discard duplicate records (as denoted by primary key) when inserting data, use the KI_HINT_IGNORE_EXISTING_PK hint. If the target table has no primary key or if in upsert mode (using KI_HINT_UPDATE_ON_EXISTING_PK), this hint will be ignored.

Both of these hints can be specified as the connection options IgnoreExistingPk & UpdateOnExistingPk, respectively, when using JDBC/ODBC.

Ignore Duplicates Example

INSERT INTO example.employee_backup /* KI_HINT_IGNORE_EXISTING_PK */
SELECT *
FROM example.employee
WHERE hire_date >= '2000-01-01'

​INSERT INTO … VALUES

​Insert Options

​ON CONFLICT

​INSERT INTO … SELECT

​ON CONFLICT

​Upserting

​Ignoring Duplicates

INSERT INTO … VALUES

Insert Options

ON CONFLICT

INSERT INTO … SELECT

ON CONFLICT

Upserting

Ignoring Duplicates