> ## 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.

# /update/records

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

Runs multiple predicate-based updates in a single call.  With the list of given
expressions, any matching record's column values will be updated as provided in
input parameter *new\_values\_maps*.  There is also an optional 'upsert'
capability where if a particular predicate doesn't match any existing record,
then a new record can be inserted.

Note that this operation can only be run on an original table and not on a
result view.

This operation can update primary key values.  By default only 'pure primary
key' predicates are allowed when updating primary key values. If the primary
key for a table is the column 'attr1', then the operation will only accept
predicates of the form: "attr1 == 'foo'" if the attr1 column is being updated.
For a composite primary key (e.g. columns 'attr1' and 'attr2') then this
operation will only accept predicates of the form: "(attr1 == 'foo') and (attr2
\== 'bar')".  Meaning, all primary key columns must appear in an equality
predicate in the expressions.  Furthermore each 'pure primary key' predicate
must be unique within a given request.  These restrictions can be removed by
utilizing some available options through input parameter *options*.

The *update\_on\_existing\_pk* option specifies the record primary key collision
policy for tables with a
[primary key](../../concepts/tables/#primary-keys), while
*ignore\_existing\_pk* specifies the record primary key collision
error-suppression policy when those collisions result in the update being
rejected.  Both are ignored on tables with no primary key.

## Input Parameter Description

<ParamField body="table_name" type="string">
  Name of table to be updated, in \[schema\_name.]table\_name format, using standard [name resolution rules](../../concepts/tables/#table-name-resolution). Must be a currently existing table and not a view.
</ParamField>

<ParamField body="expressions" type="array of strings">
  A list of the actual predicates, one for each update; format should follow the guidelines [here](/content/api/rest/filter_rest).
</ParamField>

<ParamField body="new_values_maps" type="array of maps of string to strings and/or nulls">
  List of new values for the matching records.  Each element is a map with (key, value) pairs where the keys are the names of the columns whose values are to be updated; the values are the new values.  The number of elements in the list should match the length of input parameter *expressions*.
</ParamField>

<ParamField body="records_to_insert" type="array of bytes">
  An *optional* list of new binary-avro encoded records to insert, one for each update.  If one of input parameter *expressions* does not yield a matching record to be updated, then the corresponding element from this list will be added to the table.

  The default value is an empty array ( \[] ).
</ParamField>

<ParamField body="records_to_insert_str" type="array of strings">
  An optional list of JSON encoded objects to insert, one for each update, to be added if the particular update did not match any objects.

  The default value is an empty array ( \[] ).
</ParamField>

<ParamField body="record_encoding" type="string">
  Identifies which of input parameter *records\_to\_insert* and input parameter *records\_to\_insert\_str* should be used.

  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="global_expression">
      An optional global expression to reduce the search space of the predicates listed in input parameter *expressions*.

      The default value is ''.
    </ParamField>

    <ParamField body="bypass_safety_checks">
      When set to *true*, all predicates are available for primary key updates.  Keep in mind that it is possible to destroy data in this case, since a single predicate may match multiple objects (potentially all of records of a table), and then updating all of those records to have the same primary key will, due to the primary key uniqueness constraints, effectively delete all but one of those updated records.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="update_on_existing_pk">
      Specifies the record collision policy for updating a table with a [primary key](../../concepts/tables/#primary-keys). There are two ways that a record collision can occur.

      The first is an "update collision", which happens when the update changes the value of the updated record's primary key, and that new primary key already exists as the primary key of another record in the table.

      The second is an "insert collision", which occurs when a given filter in input parameter *expressions* finds no records to update, and the alternate insert record given in input parameter *records\_to\_insert* (or input parameter *records\_to\_insert\_str*) contains a primary key matching that of an existing record in the table.

      If *update\_on\_existing\_pk* is set to *true*, "update collisions" will result in the existing record collided into being removed and the record updated with values specified in input parameter *new\_values\_maps* taking its place; "insert collisions" will result in the collided-into record being updated with the values in input parameter *records\_to\_insert* / input parameter *records\_to\_insert\_str* (if given).

      If set to *false*, the existing collided-into record will remain unchanged, while the update will be rejected and the error handled as determined by *ignore\_existing\_pk*.  If the specified table does not have a primary key, then this option has no effect.

      The default value is `false`.

      * **true**: Overwrite the collided-into record when updating a record's primary key or inserting an alternate record causes a primary key collision between the record being updated/inserted and another existing record in the table
      * **false**: Reject updates which cause primary key collisions between the record being updated/inserted and an existing record in the table
    </ParamField>

    <ParamField body="ignore_existing_pk">
      Specifies the record collision error-suppression policy for updating a table with a [primary key](../../concepts/tables/#primary-keys), only used when primary key record collisions are rejected (*update\_on\_existing\_pk* is *false*). If set to *true*, any record update that is rejected for resulting in a primary key collision with an existing table record will be ignored with no error generated.  If *false*, the rejection of any update for resulting in a primary key collision will cause an error to be reported.  If the specified table does not have a primary key or if *update\_on\_existing\_pk* is *true*, then this option has no effect.

      The default value is `false`.

      * **true**: Ignore updates that result in primary key collisions with existing records.
      * **false**: Treat as errors any updates that result in primary key collisions with existing records.
    </ParamField>

    <ParamField body="update_partition">
      Force qualifying records to be deleted and reinserted so their partition membership will be reevaluated.

      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 charN string fields will be truncated to fit.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="use_expressions_in_new_values_maps">
      When set to *true*, all new values in input parameter *new\_values\_maps* are considered as expression values. When set to *false*, all new values in input parameter *new\_values\_maps* are considered as constants.  NOTE:  When *true*, string constants will need to be quoted to avoid being evaluated as expressions.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="record_id">
      ID of a single record to be updated (returned in the call to [/insert/records](/content/api/rest/insert_records_rest) or [/get/records/fromcollection](/content/api/rest/get_records_fromcollection_rest)).
    </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">
  'update\_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 /update/records endpoint:

  <Expandable title="data_str">
    <ResponseField name="count_updated" type="long">
      Total number of records updated.
    </ResponseField>

    <ResponseField name="counts_updated" type="array of longs">
      Total number of records updated per predicate in input parameter *expressions*.
    </ResponseField>

    <ResponseField name="count_inserted" type="long">
      Total number of records inserted (due to expressions not matching any existing records).
    </ResponseField>

    <ResponseField name="counts_inserted" type="array of longs">
      Total number of records inserted per predicate in input parameter *expressions* (will be either 0 or 1 for each expression).
    </ResponseField>

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

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