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

# /create/union

```
URL: http://<db.host>:<db.port>/create/union
```

Merges data from one or more tables with comparable data types into a new
table.

The following merges are supported:

UNION (DISTINCT/ALL) - For data set union details and examples, see
[Union](../../concepts/unions/). For limitations, see
[Union Limitations and Cautions](../../concepts/unions/#limitations-and-cautions).

INTERSECT (DISTINCT/ALL) - For data set intersection details and examples, see
[Intersect](../../concepts/intersect/). For limitations, see
[Intersect Limitations](../../concepts/intersect/#limitations).

EXCEPT (DISTINCT/ALL) - For data set subtraction details and examples, see
[Except](../../concepts/except/). For limitations, see
[Except Limitations](../../concepts/except/#limitations).

## Input Parameter Description

<ParamField body="table_name" type="string">
  Name of the table to be created, in \[schema\_name.]table\_name format, using standard [name resolution rules](../../concepts/tables/#table-name-resolution) and meeting [table naming criteria](../../concepts/tables/#table-naming-criteria).
</ParamField>

<ParamField body="table_names" type="array of strings">
  The list of table names to merge, in \[schema\_name.]table\_name format, using standard [name resolution rules](../../concepts/tables/#table-name-resolution). Must contain the names of one or more existing tables.
</ParamField>

<ParamField body="input_column_names" type="array of arrays of strings">
  The list of columns from each of the corresponding input tables.
</ParamField>

<ParamField body="output_column_names" type="array of strings">
  The list of names of the columns to be stored in the output table.
</ParamField>

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

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

  <Expandable title="options">
    <ParamField body="create_temp_table">
      If *true*, a unique temporary table name will be generated in the sys\_temp schema and used in place of input parameter *table\_name*. If *persist* is *false* (or unspecified), then this is always allowed even if the caller does not have permission to create tables. The generated name is returned in *qualified\_table\_name*.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="collection_name">
      \[DEPRECATED--please specify the containing schema for the projection as part of input parameter *table\_name* and use [/create/schema](/content/api/rest/create_schema_rest) to create the schema if non-existent] Name of the schema for the output table. If the schema provided is non-existent, it will be automatically created.

      The default value is ''.
    </ParamField>

    <ParamField body="mode">
      The mode describes what rows of the tables being unioned will be retained.

      The default value is `union_all`.

      * **union\_all**: Retains all rows from the specified tables.
      * **union**: Retains all unique rows from the specified tables (synonym for *union\_distinct*).
      * **union\_distinct**: Retains all unique rows from the specified tables.
      * **except**: Retains all unique rows from the first table that do not appear in the second table (only works on 2 tables).
      * **except\_all**: Retains all rows(including duplicates) from the first table that do not appear in the second table (only works on 2 tables).
      * **intersect**: Retains all unique rows that appear in both of the specified tables (only works on 2 tables).
      * **intersect\_all**: Retains all rows(including duplicates) that appear in both of the specified tables (only works on 2 tables).
    </ParamField>

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

    <ParamField body="chunk_column_max_memory">
      Indicates the target maximum data size for each column in a chunk to be used for this output table.
    </ParamField>

    <ParamField body="chunk_max_memory">
      Indicates the target maximum data size for all columns in a chunk to be used for this output table.
    </ParamField>

    <ParamField body="create_indexes">
      Comma-separated list of columns on which to create indexes on the output table. The columns specified must be present in input parameter *output\_column\_names*.
    </ParamField>

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

      * **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 output table specified in input parameter *table\_name*.
    </ParamField>

    <ParamField body="persist">
      If *true*, then the output table specified in input parameter *table\_name* will be persisted and will not expire unless a *ttl* is specified. If *false*, then the output table will be an in-memory table and will expire unless a *ttl* is specified otherwise.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="view_id">
      ID of view of which this output table is a member.

      The default value is ''.
    </ParamField>

    <ParamField body="force_replicated">
      If *true*, then the output table specified in input parameter *table\_name* will be replicated even if the source tables are not.

      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>

    <ParamField body="no_count">
      Return a count of 0 for the union table response to avoid the cost of counting; optimization needed for many chunk virtual unions.

      The default value is `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">
  'create\_union\_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 /create/union endpoint:

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

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

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

      <Expandable title="info">
        <ResponseField name="count">
          Number of records in the final table.
        </ResponseField>

        <ResponseField name="qualified_table_name">
          The fully qualified name of the result table (i.e. including the schema).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

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