> ## 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/fromquery

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

Computes remote query result and inserts the result data into a new or existing
table.

## Input Parameter Description

<ParamField body="table_name" type="string">
  Name of the table into which the data will be inserted, in \[schema\_name.]table\_name format, using standard [name resolution rules](../../concepts/tables/#table-name-resolution). If the table does not exist, the table will be created using either an existing *type\_id* or the type inferred from the remote query, and the new table name will have to meet standard [table naming criteria](../../concepts/tables/#table-naming-criteria).
</ParamField>

<ParamField body="remote_query" type="string">
  Query for which result data needs to be imported.
</ParamField>

<ParamField body="modify_columns" type="map of string to maps of string to strings">
  Not implemented yet.

  The default value is an empty map ( \{} ).
</ParamField>

<ParamField body="create_table_options" type="map of string to strings">
  Options used when creating the target table.

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

  <Expandable title="create_table_options">
    <ParamField body="type_id">
      ID of a currently registered [type](../../concepts/types/).

      The default value is ''.
    </ParamField>

    <ParamField body="no_error_if_exists">
      If *true*, prevents an error from occurring if the table already exists and is of the given type.  If a table with the same ID but a different type exists, it is still an error.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="is_replicated">
      Affects the [distribution scheme](../../concepts/tables/#distribution) for the table's data.  If *true* and the given type has no explicit [shard key](../../concepts/tables/#shard-key) defined, the table will be [replicated](../../concepts/tables/#replication). If *false*, the table will be [sharded](../../concepts/tables/#sharding) according to the shard key specified in the given *type\_id*, or [randomly sharded](../../concepts/tables/#random-sharding), if no shard key is specified.  Note that a type containing a shard key cannot be used to create a replicated table.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="foreign_keys">
      Semicolon-separated list of [foreign keys](../../concepts/tables/#foreign-keys), of the format '(source\_column\_name \[, ...]) references target\_table\_name(primary\_key\_column\_name \[, ...]) \[as foreign\_key\_name]'.
    </ParamField>

    <ParamField body="foreign_shard_key">
      Foreign shard key of the format 'source\_column references shard\_by\_column from target\_table(primary\_key\_column)'.
    </ParamField>

    <ParamField body="partition_type">
      [Partitioning](../../concepts/tables/#partitioning) scheme to use.

      * **RANGE**: Use [range partitioning](../../concepts/tables/#partitioning-by-range).
      * **INTERVAL**: Use [interval partitioning](../../concepts/tables/#partitioning-by-interval).
      * **LIST**: Use [list partitioning](../../concepts/tables/#partitioning-by-list).
      * **HASH**: Use [hash partitioning](../../concepts/tables/#partitioning-by-hash).
      * **SERIES**: Use [series partitioning](../../concepts/tables/#partitioning-by-series).
    </ParamField>

    <ParamField body="partition_keys">
      Comma-separated list of partition keys, which are the columns or column expressions by which records will be assigned to partitions defined by *partition\_definitions*.
    </ParamField>

    <ParamField body="partition_definitions">
      Comma-separated list of partition definitions, whose format depends on the choice of *partition\_type*.  See [range partitioning](../../concepts/tables/#partitioning-by-range), [interval partitioning](../../concepts/tables/#partitioning-by-interval), [list partitioning](../../concepts/tables/#partitioning-by-list), [hash partitioning](../../concepts/tables/#partitioning-by-hash), or [series partitioning](../../concepts/tables/#partitioning-by-series) for example formats.
    </ParamField>

    <ParamField body="is_automatic_partition">
      If *true*, a new partition will be created for values which don't fall into an existing partition.  Currently only supported for [list partitions](../../concepts/tables/#partitioning-by-list).

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="ttl">
      Sets the [TTL](../../concepts/ttl/) of the table specified in input parameter *table\_name*.
    </ParamField>

    <ParamField body="chunk_size">
      Indicates the number of records per chunk to be used for this table.
    </ParamField>

    <ParamField body="is_result_table">
      Indicates whether the table is a [memory-only table](../../concepts/tables_memory_only/). A result table cannot contain columns with text\_search [data-handling](../../concepts/types/#data-handling), and it will not be retained if the server is restarted.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="strategy_definition">
      The [tier strategy](../../rm/concepts/#tier-strategies) for the table and its columns.
    </ParamField>

    <ParamField body="compression_codec">
      The default [compression codec](../../concepts/column_compression/) for this table's columns.
    </ParamField>
  </Expandable>
</ParamField>

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

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

  <Expandable title="options">
    <ParamField body="bad_record_table_name">
      Name of a table to which records that were rejected are written.  The bad-record-table has the following columns: line\_number (long), line\_rejected (string), error\_message (string). When error handling is Abort, bad records table is not populated.
    </ParamField>

    <ParamField body="bad_record_table_limit">
      A positive integer indicating the maximum number of records that can be written to the bad-record-table. Default value is 10000.
    </ParamField>

    <ParamField body="batch_size">
      Number of records per batch when inserting data.
    </ParamField>

    <ParamField body="datasource_name">
      Name of an existing external data source from which table will be loaded.
    </ParamField>

    <ParamField body="error_handling">
      Specifies how errors should be handled upon insertion.

      The default value is `abort`.

      * **permissive**: Records with missing columns are populated with nulls if possible; otherwise, the malformed records are skipped.
      * **ignore\_bad\_records**: Malformed records are skipped.
      * **abort**: Stops current insertion and aborts entire operation when an error is encountered.  Primary key collisions are considered abortable errors in this mode.
    </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 *error\_handling*.  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="ingestion_mode">
      Whether to do a full load, dry run, or perform a type inference on the source data.

      The default value is `full`.

      * **full**: Run a type inference on the source data (if needed) and ingest.
      * **dry\_run**: Does not load data, but walks through the source data and determines the number of valid records, taking into account the current mode of *error\_handling*.
      * **type\_inference\_only**: Infer the type of the source data and return, without ingesting any data.  The inferred type is returned in the response.
    </ParamField>

    <ParamField body="jdbc_fetch_size">
      The JDBC fetch size, which determines how many rows to fetch per round trip.
    </ParamField>

    <ParamField body="jdbc_session_init_statement">
      Executes the statement per each JDBC session before doing actual load.

      The default value is ''.
    </ParamField>

    <ParamField body="num_splits_per_rank">
      Number of splits for reading data per rank. Default will be external\_file\_reader\_num\_tasks.

      The default value is ''.
    </ParamField>

    <ParamField body="num_tasks_per_rank">
      Number of tasks for reading data per rank. Default will be external\_file\_reader\_num\_tasks.
    </ParamField>

    <ParamField body="primary_keys">
      Comma separated list of column names, to set as primary keys, when not specified in the type.

      The default value is ''.
    </ParamField>

    <ParamField body="shard_keys">
      Comma separated list of column names, to set as shard keys, when not specified in the type.

      The default value is ''.
    </ParamField>

    <ParamField body="subscribe">
      Continuously poll the data source to check for new data and load it into the table.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="truncate_table">
      If set to *true*, truncates the table specified by input parameter *table\_name* prior to loading the data.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="remote_query">
      Remote SQL query from which data will be sourced.
    </ParamField>

    <ParamField body="remote_query_order_by">
      Name of column to be used for splitting the query into multiple sub-queries using ordering of given column.

      The default value is ''.
    </ParamField>

    <ParamField body="remote_query_filter_column">
      Name of column to be used for splitting the query into multiple sub-queries using the data distribution of given column.

      The default value is ''.
    </ParamField>

    <ParamField body="remote_query_increasing_column">
      Column on subscribed remote query result that will increase for new records (e.g., TIMESTAMP).

      The default value is ''.
    </ParamField>

    <ParamField body="remote_query_partition_column">
      Alias name for *remote\_query\_filter\_column*.

      The default value is ''.
    </ParamField>

    <ParamField body="truncate_strings">
      If set to *true*, truncate string values that are longer than the column's type size.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <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* and *error\_handling*.  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>
  </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\_from\_query\_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/fromquery endpoint:

  <Expandable title="data_str">
    <ResponseField name="table_name" type="string">
      Value of input parameter *table\_name*.
    </ResponseField>

    <ResponseField name="type_id" type="string">
      ID of the currently registered table structure [type](../../concepts/types/) for the target table.
    </ResponseField>

    <ResponseField name="type_definition" type="string">
      A JSON string describing the columns of the target table.
    </ResponseField>

    <ResponseField name="type_label" type="string">
      The user-defined description associated with the target table's structure.
    </ResponseField>

    <ResponseField name="type_properties" type="map of string to arrays of strings">
      A mapping of each target table column name to an array of column properties associated with that column.
    </ResponseField>

    <ResponseField name="count_inserted" type="long">
      Number of records inserted into the target table.
    </ResponseField>

    <ResponseField name="count_skipped" type="long">
      Number of records skipped, when not running in *abort* error handling mode.
    </ResponseField>

    <ResponseField name="count_updated" type="long">
      \[Not yet implemented]  Number of records updated within the target table.
    </ResponseField>

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

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