> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# /insert/records

```
URL: http://<db.host>:<db.port>/insert/records
```

Adds multiple records to the specified table. The operation is synchronous,
meaning that a response will not be returned until all the records are fully
inserted and available. The response payload provides the counts of the number
of records actually inserted and/or updated, and can provide the unique
identifier of each added record.

The input parameter *options* parameter can be used to customize this
function's behavior.

The *update\_on\_existing\_pk* option specifies the record collision policy for
inserting into a table with a
[primary key](../../concepts/tables/#primary-keys), but is ignored if no
primary key exists.

The *return\_record\_ids* option indicates that the database should return the
unique identifiers of inserted records.

## Input Parameter Description

<ParamField body="table_name" type="string">
  Name of table to which the records are to be added, in \[schema\_name.]table\_name format, using standard [name resolution rules](../../concepts/tables/#table-name-resolution). Must be an existing table.
</ParamField>

<ParamField body="list" type="array of bytes">
  An array of binary-encoded data for the records to be added. All records must be of the same type as that of the table. Empty array if input parameter *list\_encoding* is *json*.
</ParamField>

<ParamField body="list_str" type="array of strings">
  An array of JSON encoded data for the records to be added. All records must be of the same type as that of the table. Empty array if input parameter *list\_encoding* is *binary*.
</ParamField>

<ParamField body="list_encoding" type="string">
  The encoding of the records to be inserted.

  The default value is `binary`.

  The supported values are:

  * binary
  * json
</ParamField>

<ParamField body="options" type="map of string to strings">
  Optional parameters.

  The default value is an empty map ( \{} ).

  <Expandable title="options">
    <ParamField body="update_on_existing_pk">
      Specifies the record collision policy for inserting into a table with a [primary key](../../concepts/tables/#primary-keys). If set to *true*, any existing table record with primary key values that match those of a record being inserted will be replaced by that new record (the new data will be "upserted"). If set to *false*, any existing table record with primary key values that match those of a record being inserted will remain unchanged, while the new record will be rejected and the error handled as determined by *ignore\_existing\_pk*, *allow\_partial\_batch*, and *return\_individual\_errors*.  If the specified table does not have a primary key, then this option has no effect.

      The default value is `false`.

      * **true**: Upsert new records when primary keys match existing records.
      * **false**: Reject new records when primary keys match existing records.
    </ParamField>

    <ParamField body="ignore_existing_pk">
      Specifies the record collision error-suppression policy for inserting into a table with a [primary key](../../concepts/tables/#primary-keys), only used when not in upsert mode (upsert mode is disabled when *update\_on\_existing\_pk* is *false*).  If set to *true*, any record being inserted that is rejected for having primary key values that match those of an existing table record will be ignored with no error generated.  If *false*, the rejection of any record for having primary key values matching an existing record will result in an error being reported, as determined by *allow\_partial\_batch* and *return\_individual\_errors*.  If the specified table does not have a primary key or if upsert mode is in effect (*update\_on\_existing\_pk* is *true*), then this option has no effect.

      The default value is `false`.

      * **true**: Ignore new records whose primary key values collide with those of existing records.
      * **false**: Treat as errors any new records whose primary key values collide with those of existing records.
    </ParamField>

    <ParamField body="pk_conflict_predicate_higher">
      The record with higher value for the column resolves the primary-key insert conflict.

      The default value is ''.
    </ParamField>

    <ParamField body="pk_conflict_predicate_lower">
      The record with lower value for the column resolves the primary-key insert conflict.

      The default value is ''.
    </ParamField>

    <ParamField body="return_record_ids">
      If *true* then return the internal record id along for each inserted record.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="truncate_strings">
      If set to *true*, any strings which are too long for their target charN string columns will be truncated to fit.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="return_individual_errors">
      If set to *true*, success will always be returned, and any errors found will be included in the info map.  The "bad\_record\_indices" entry is a comma-separated list of bad records (0-based).  If so, there will also be an "error\_N" entry for each record with an error, where N is the index (0-based).

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="allow_partial_batch">
      If set to *true*, all correct records will be inserted and incorrect records will be rejected and reported.  Otherwise, the entire batch will be rejected if any records are incorrect.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="dry_run">
      If set to *true*, no data will be saved and any errors will be returned.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>
  </Expandable>
</ParamField>

## Output Parameter Description

The Kinetica server embeds the endpoint response inside a standard response structure which contains status information and the actual response to the query.  Here is a description of the various fields of the wrapper:

<ResponseField name="status" type="String">
  'OK' or 'ERROR'
</ResponseField>

<ResponseField name="message" type="String">
  Empty if success or an error message
</ResponseField>

<ResponseField name="data_type" type="String">
  'insert\_records\_response' or 'none' in case of an error
</ResponseField>

<ResponseField name="data" type="String">
  Empty string
</ResponseField>

<ResponseField name="data_str" type="JSON or String">
  This embedded JSON represents the result of the /insert/records endpoint:

  <Expandable title="data_str">
    <ResponseField name="record_ids" type="array of strings">
      An array containing the IDs with which the added records are identified internally.
    </ResponseField>

    <ResponseField name="count_inserted" type="int">
      The number of records inserted.
    </ResponseField>

    <ResponseField name="count_updated" type="int">
      The number of records updated.
    </ResponseField>

    <ResponseField name="info" type="map of string to strings">
      Additional information.

      <Expandable title="info">
        <ResponseField name="bad_record_indices">
          If return\_individual\_errors option is specified or implied, returns a comma-separated list of invalid indices (0-based).
        </ResponseField>

        <ResponseField name="error_N">
          Error message for record at index N (0-based).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  Empty string in case of an error.
</ResponseField>