Insert Or Replace Entity

5 minutes to read

Contributors

In this article

The Insert Or Replace Entity operation replaces an existing entity or inserts a new entity if it does not exist in the table. Because this operation can insert or update an entity, it is also known as an upsert operation.

Request

The Insert Or Replace Entity request may be constructed as follows. HTTPS is recommended. Replace the following values with your own:

myaccount with the name of your storage account

mytable with the name of your table

myPartitionKey and myRowKey with the name of the partition key and row key for entity to be updated

Remarks

The Insert Or Replace Entity operation does not use the If-Match header and it must be called using the 2011-08-18 version or newer. These attributes distinguish this operation from the Update Entity operation.

If the Insert Or Replace Entity operation is used to replace an entity, any properties from the previous entity will be removed if the new entity does not define them. Properties with a null value will also be removed.

When calling the Insert or Replace Entity operation, you must specify values for the PartitionKey and RowKey system properties. Together, these properties form the primary key and must be unique within the table.

Both the PartitionKey and RowKey values must be string values; each key value may be up to 64 KB in size. If you are using an integer value for the key value, you should convert the integer to a fixed-width string, because they are canonically sorted. For example, you should convert the value 1 to 0000001 to ensure proper sorting.

To explicitly type a property, specify the appropriate OData data type by setting the m:type attribute within the property definition in the Atom feed. For more information about typing properties, see Inserting and Updating Entities.

Any application that can authenticate and send an HTTP PUT request can insert or replace an entity.

See Also

The feedback system for this content will be changing soon. Old comments will not be carried over. If content within a comment thread is important to you, please save a copy. For more information on the upcoming change, we invite you to read our blog post.