Import List into Database

Audience: Low-code Engineers

Skill Prerequisites: Actions, Lists, SQL

Saves the items of a list into a SQL Server table. Each item becomes a row, and you choose which list properties go into which columns.

It can simply insert every item, or merge the list with the table: update the rows that already exist, insert the new ones, and optionally delete the rows that aren't in the list. It's much faster than running an insert for each item.

The list comes from an earlier action, such as Create List from SQL, Create List from JSON, Create List from a CSV source or Create List from Excel (.xlsx).

Typical Use Cases

• Import the rows of an uploaded CSV or Excel file into a table
• Save the items returned by an API, after turning the JSON into a list
• Keep a table in sync with an outside source, by merging a list into it on a schedule
• Copy rows from one database to another, using Create List from SQL and a different connection string

Don't use it to

• Insert or update a single row. Use Run SQL Query instead.
• Create a table. The table must already exist, with a primary key.
• Import into a database that isn't SQL Server. The action uses SQL Server bulk copy.

Related Actions

Action Name	Description
Create List from SQL	Creates a list from the rows of a query.
Create List from JSON	Creates a list from a JSON array.
Create List from a CSV source	Creates a list from CSV text or a CSV file.
Create List from Excel (.xlsx)	Creates a list from an Excel sheet.
Remap List	Renames or reshapes list properties before the import.
Execute Actions for each List Entry	Runs actions for each item, when you need more than a straight import.
Run SQL Query	Runs any SQL, for example to clean up a table before the import.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Connection String	A connection string, or the name of a connection string from web.config. If it's empty, the application database is used. Must point to SQL Server.	Yes	empty string	No
Prefix Database Schema	The schema of the table, for example dbo. For Plant an App entities, use app. If it's empty, the default schema of the database user is used.	Yes	empty string	No
Table Name	The table to import into. Pick it from the list, or use an expression. Enter only the table name, without the schema. The table must have a primary key.	Yes	empty string	Yes
List Name	The name of the list to import, for example ContactsList. If it's empty, the default list of the current context is used, for example the rows of a listing.	Yes	empty string	No
Insert all values	Maps every property of the list to a column with the same name. When it's on, Properties is ignored, and every property must match a column.	No	false	No
Properties	Maps list properties to columns. Each row has a List Property Name, for example Email, and a Database Column Name, for example EmailAddress. Only mapped columns are filled.	No	empty	Yes, unless Insert all values is on
Merge Existing Values	Matches list items to table rows by the table's primary key. Matching rows are updated and the other items are inserted. Map the primary key columns, or no rows will match.	No	false	No
Only Update Values	Updates matching rows but doesn't insert new ones. Only works with Merge Existing Values.	No	false	No
Delete Non-Existing Values	Deletes the table rows that have no matching item in the list. Only works with Merge Existing Values.	No	false	No
On Error	Actions to run if the import fails. They can use the [Exception], [ExceptionType], [ExceptionMessage] and [ExceptionStack] tokens. See Errors.	No	empty	No

This action has no output tokens.

How it works

Insert (Merge Existing Values off). Every item in the list is inserted into the table in one bulk copy. Existing rows aren't checked, so an item with a primary key that's already in the table makes the action fail.

Merge (Merge Existing Values on).

1. The list is copied into a temporary table with the same columns and primary key as your table.
2. A SQL MERGE compares the two tables on the primary key columns:
   • Rows that match are updated with the mapped columns.
   • Items that don't match are inserted, unless Only Update Values is on.
   • Table rows that have no matching item are deleted, if Delete Non-Existing Values is on.
3. The temporary table is dropped.

The bulk copy can run for up to 10 minutes.

Values and columns

• Types. Values are converted to the type of each column, for example text to a number or a date.
• Empty values. Empty text in a text column that allows NULL is saved as NULL.
• Columns you don't map get their default value, or NULL if they have none. They must allow NULL or have a default.
• Identity columns. If you don't map the identity column, the database generates the IDs. If you do map it, the values from the list are saved as they are. When merging on an identity primary key, map it so rows can be matched.
• Missing properties. If a mapped property is missing from an item, the action fails with The entity does not contain a property named "PropertyName".
• Names aren't case-sensitive for list properties.

Errors

• If the list doesn't exist, the action fails with Specified entity does not exist. The On Error actions don't run for this error.
• For other errors, such as a missing table, a missing column or a duplicate key, the On Error actions run first. Then the action still fails, unless an On Error action ends execution itself, for example Stop Execution.
• Low-code engineers and administrators see the original error. Other users see a generic message.

Considerations

• Delete Non-Existing Values deletes rows. Every row that isn't in the list is removed. If the list is empty, or was loaded with a filter, you can delete most of the table. Check the list first, for example with a condition on its size.
• Map the primary key when merging. If it isn't mapped, no rows match, and every item is inserted as a new row.
• Duplicate keys in the list make the merge fail, because the temporary table has the same primary key.
• Insert all values uses the first item to find the property names. It fails if the list is empty.
• Views show up in the Table Name list, but the import needs a table with a primary key.
• Large lists. Merge options take longer on big tables. The bulk copy stops after 10 minutes.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Insert contacts from a list

This action inserts every item of ContactsList into the dbo.Contacts table. The list properties Name and Email go into the FullName and EmailAddress columns. The ContactId identity column isn't mapped, so the database generates the IDs.

{
    "Title": "Import List into Database",
    "ActionType": "ImportIntoDatabaseFromEntity",
    "Description": "Insert the imported contacts",
    "Parameters": {
        "ConnectionString": "",
        "PrefixDatabaseSchema": "dbo",
        "TableName": {
            "Expression": "",
            "Value": "Contacts",
            "IsExpression": false,
            "Parameters": {}
        },
        "EntityName": "ContactsList",
        "InsertAllValues": false,
        "EntityProps": [
            {
                "name": "Name",
                "value": "FullName"
            },
            {
                "name": "Email",
                "value": "EmailAddress"
            }
        ],
        "MergeExistingValues": false,
        "OnlyUpdateValues": false,
        "DeleteNonExistingValues": false,
        "OnError": []
    }
}

2. Keep a products table in sync

This action merges ProductsList into dbo.Products. Sku is the table's primary key. Existing products are updated, new ones are inserted, and products that aren't in the list are deleted. The condition assumes an earlier action saved the number of items in [ProductCount]. It stops the action from running with an empty list, which would delete every product.

{
    "Title": "Import List into Database",
    "ActionType": "ImportIntoDatabaseFromEntity",
    "Description": "Sync products from the supplier feed",
    "Condition": "[ProductCount] != \"0\"",
    "Parameters": {
        "PrefixDatabaseSchema": "dbo",
        "TableName": {
            "Expression": "",
            "Value": "Products",
            "IsExpression": false,
            "Parameters": {}
        },
        "EntityName": "ProductsList",
        "InsertAllValues": false,
        "EntityProps": [
            {
                "name": "Sku",
                "value": "Sku"
            },
            {
                "name": "Name",
                "value": "Name"
            },
            {
                "name": "Price",
                "value": "Price"
            }
        ],
        "MergeExistingValues": true,
        "OnlyUpdateValues": false,
        "DeleteNonExistingValues": true
    }
}

3. Update order statuses in another database

This action updates the Status column of existing orders in the Orders table of another database. WarehouseDb is the name of a connection string in web.config. Items with an OrderId that isn't in the table are skipped. If the import fails, the error is logged before the action fails.

{
    "Title": "Import List into Database",
    "ActionType": "ImportIntoDatabaseFromEntity",
    "Description": "Update order statuses",
    "Parameters": {
        "ConnectionString": "WarehouseDb",
        "PrefixDatabaseSchema": "",
        "TableName": {
            "Expression": "",
            "Value": "Orders",
            "IsExpression": false,
            "Parameters": {}
        },
        "EntityName": "StatusList",
        "InsertAllValues": false,
        "EntityProps": [
            {
                "name": "OrderId",
                "value": "OrderId"
            },
            {
                "name": "Status",
                "value": "Status"
            }
        ],
        "MergeExistingValues": true,
        "OnlyUpdateValues": true,
        "DeleteNonExistingValues": false,
        "OnError": [
            {
                "Title": "Log Error",
                "ActionType": "LogError",
                "Parameters": {
                    "Message": "Order status import failed: [ExceptionMessage]"
                }
            }
        ]
    }
}

Revised 09/26/2026