pacx data upsert

Creates or updates a record in a Dataverse table using a record ID or an alternate key (upsert).

Usage

Overview

This command performs an upsert (insert-or-update) operation on a Dataverse table. It uses either a record GUID (--id) or an alternate key (--key) to determine whether the target record already exists: if it does, the record is updated; otherwise, a new record is created. The operation is idempotent and can be safely repeated.

Input modes

Exactly one of the following input modes must be used (they are mutually exclusive):

• --plain (-p): semicolon-separated list of field=value pairs, e.g. name=Contoso Ltd;telephone1=+39 02 1234567
• --json (-j): a JSON object string representing the record payload
• --file (-f): path to a JSON file containing the record payload

Record identifier: --id vs --key

Exactly one of the following record identifier options must be provided (they are mutually exclusive):

• --id: GUID of the record to upsert, e.g. --id 3fa85f64-5717-4562-b3fc-2c963f66afa6
• --key (-k): semicolon-separated field=value pairs forming the alternate key, e.g. --key accountnumber=ACC001

For --key, multi-field alternate keys are also supported: --key "field1=value1;field2=value2"

For --key, Dataverse uses the key fields for lookup and automatically applies those values when creating a record. Do not repeat key fields in --plain/--json/--file.

Supported field types

Type	Format	Example
String / Memo	Any text value	name=Contoso Ltd
Integer	Whole number	numberofemployees=100
Decimal / Double	Decimal number	revenue=1234.56
Money	Monetary value	estimatedvalue=50000
Boolean	true/false, 1/0	donotbulkemail=true
Date Only	yyyy-MM-dd	birthdate=1990-05-20
Date & Time	ISO 8601	overriddencreatedon=2024-01-15T08:30:00Z
Choice (OptionSet)	Integer code or label text	statecode=0 or statecode=Active
Multi-Select Choice	Comma-separated codes or labels	new_tags=Red,Blue,Green
Lookup	entity(GUID) or entity(field='value')	ownerid=systemuser(domainname='user@org.com')

Options

• --id: GUID of the record to upsert (mutually exclusive with --key)
• --key (-k): semicolon-separated field=value pairs for the alternate key (mutually exclusive with --id)
• --return (-r): comma-separated list of columns to retrieve after the operation and display; if omitted only the record ID is shown
• --dry-run (-dr): validates and displays the resolved payload without actually performing the upsert

Output

The command reports whether the operation resulted in a record creation or an update, and returns the record ID.

Examples

# Upsert an account by record GUID
pacx data upsert -t account --id 3fa85f64-5717-4562-b3fc-2c963f66afa6 --plain "name=Contoso Ltd"

# Upsert an account by alternate key
pacx data upsert -t account --key accountnumber=ACC001 --plain "name=Contoso Ltd"

# Upsert with multiple fields
pacx data upsert -t account --key accountnumber=ACC001 --plain "name=Contoso Ltd;telephone1=+39 02 1234567"

# Upsert and return specific fields
pacx data upsert -t account --key accountnumber=ACC001 --plain "name=Contoso Ltd" --return "name,telephone1"

# Upsert using JSON payload
pacx data upsert -t account --key accountnumber=ACC001 --json '{"name":"Contoso Ltd","telephone1":"+39 02 1234567"}'

# Upsert from a JSON file
pacx data upsert -t account --key accountnumber=ACC001 --file ./account-payload.json

# Dry-run: validate the payload without upserting
pacx data upsert -t account --key accountnumber=ACC001 --plain "name=Contoso Ltd" --dry-run

# Multi-field alternate key
pacx data upsert -t new_config --key "new_category=pricing;new_region=EMEA" --plain "new_value=standard"

Arguments

Long Name	Short Name	Required?	Description	Default value	Valid values
table	t	Y	Logical name of the target table.	-	String
dry-run	dr	N	Validates the payload without performing the upsert.	False	true, false
file	f	N	Path to a JSON file containing the record payload. Mutually exclusive with --plain and --json.	-	String
id	id	N	The GUID of the record to upsert. Mutually exclusive with --key.	-	Guid
json	j	N	JSON string representing the record payload. Mutually exclusive with --plain and --file.	-	String
key	k	N	Semicolon-separated list of field=value pairs that form the alternate key used to identify the record. Mutually exclusive with --id.	-	String
plain	p	N	Semicolon-separated list of field=value pairs for the record payload. Mutually exclusive with --json and --file.	-	String
return	r	N	Comma-separated list of columns to return after the operation. If omitted, only the record ID is returned.	-	String