Skip to main content

​
Entity Update Behavior (PUT vs PATCH)

PUT and PATCH behave differently when you update an entity that already exists. This page covers three things: which fields PUT keeps versus overwrites, why PATCH is the right tool for intentionally replacing a value, and a common mistake to avoid with placeholder text.
PUT is not always a full overwrite, but the protection is caller- and field-specific, not universal. For a defined set of fields, if a value is already set, PUT keeps it instead of replacing it with an empty or missing one — but which fields are protected, and whether a caller can override them, depends on who’s calling and which field it is. See PUT Preserve Logic below for the exact rules. To intentionally replace a protected value, use PATCH.

​
PUT Preserve Logic (Bot-Driven Updates)

When a bot — for example, the ingestion-bot running a metadata ingestion workflow — updates an entity with PUT, the backend keeps several fields as they are instead of overwriting them. This stops metadata that someone curated by hand from being wiped out by a routine ingestion run. Protection works a little differently depending on the field: Preserved for bot-driven PUT — PATCH only: If any of these fields already have a value, a bot’s PUT request won’t change them. There’s no way around this except PATCH.
  • extension and custom properties
  • domain and dataProducts
  • Certifications
  • Nested metadata, such as a column’s description and displayName on a table
Preserved for bot-driven PUT — override available: Same as above: if these fields already have a value, a bot’s PUT request won’t change them. The one exception is a bulk create-or-update request with overrideMetadata=true, which forces the overwrite without needing PATCH.
  • Top-level description
  • owners — no PUT request, from a bot or a person, can ever remove owners by leaving the field blank or sending an empty list. Separately, a bot can’t replace the owners with a different value either, but only if that bot’s role doesn’t have EditOwners permission.
Applies to every PUT request, not just bots:
  • tags — PUT adds the tags in the request to the entity’s existing tags. This happens for every caller, not just bots. PUT never removes an existing tag; only PATCH can do that.
overrideMetadata=true only works on the bulk create-or-update endpoint (the same setting shown as the “Override Metadata” toggle in connector ingestion configs). The regular single-entity PUT endpoints used throughout this API reference don’t support it.

​
The PATCH Requirement

PATCH preserves any field you don’t include in the request — it only changes the fields you explicitly target. Replacing one of the fields above with PATCH still requires the caller to have permission to modify that specific field; it isn’t a way around field-level authorization, only around the PUT preserve rules. Use JSON Patch (RFC 6902) to set exactly the fields you want to change. Unlike PUT, PATCH applies the values you send instead of preserving what’s already there — so it’s the right tool whenever you need to correct or replace curated metadata, not just fill in a gap.

​
Best Practice: Avoid Placeholder Values

Don’t send placeholder strings such as "No description provided" when you create an entity. The backend can’t tell a placeholder from a real description — it treats both as a value that’s already set. That matters because of the preserve logic above: once a description has any value, a bot-driven PUT won’t touch it. So a placeholder set at creation time permanently blocks a later ingestion run from ever filling in the real description. Leave the field empty instead — only an empty field can be filled in later by PUT.
Already created entities with placeholder descriptions? A PUT request won’t clear them. Use PATCH to replace the placeholder with the real value, or with an empty string.

​
Scope

This applies to the create-or-update (PUT) APIs for entities such as Tables, Dashboards, Pipelines, Domains, Glossaries, and Services — as well as other data assets, governance entities, data quality entities, and users. It doesn’t apply to action or configuration endpoints, such as Lineage operations or system settings. Those follow different rules.

Update via PATCH

See a full PATCH example for updating a table

Bots

Learn how to set up the ingestion-bot that drives PUT updates