update_schema_incremental
Evolve a schema in place by adding/removing fields or re-keying identity, then activate the new version immediately; optionally backfill historical data.
Instructions
Incrementally update a schema by adding fields (fields_to_add — minor version bump), removing fields (fields_to_remove — major version bump; observation data preserved, snapshot-excluded until re-added), or changing the identity rule (canonical_name_fields — major version bump). Creates a new schema version and activates it immediately, so all new data stored after this call uses the updated schema. Optionally migrates existing raw_fragments to observations for historical data backfill.
canonical_name_fields re-keys how the type derives canonical_name / identity. Rules are ordered precedence with fallback — the first rule whose fields are all present wins, e.g. [{composite:["linkedin_url"]},"email","name"] keys on linkedin_url, else email, else name. Reach for it when same-name-different-entity collisions appear (e.g. a bulk import collapses distinct people who share a name because identity resolves on name alone). The existing reducer_config is preserved automatically, so this is the safe way to re-key without a full register_schema re-supply. Applies to NEW writes only — it does not retroactively re-key existing entities, so it will not by itself merge existing duplicates. Omit to keep the current rule; pass [] to clear it (succeeds only if the schema also declares identity_opt_out). The response echoes the resolved canonical_name_fields; call describe_entity_type first to see the current rule before replacing it.
On ERR_SCHEMA_SCOPE_MISMATCH an active schema exists in a different scope than the call checked (details.guard_scope vs details.found_scope). Retry with user_specific matching details.found_scope (user→true, global→false/omit). Never call register_schema for that code — a second active row for the same entity_type risks dual-active corruption (#2374/#2378).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No | User ID for user-specific schema (required if user_specific=true) | |
| activate | No | Activate schema immediately so it applies to new data (default: true). If false, schema is registered but not active. | |
| entity_type | Yes | Entity type to update | |
| fields_to_add | No | Fields to add to schema | |
| user_specific | No | Create user-specific schema variant (default: false) | |
| schema_version | No | New schema version (auto-increments if not provided) | |
| fields_to_remove | No | Field names to remove from schema (triggers major version bump). Observation data is preserved; fields can be restored by re-adding them later. | |
| migrate_existing | No | Migrate existing raw_fragments to observations for historical data backfill (default: false). Note: New data automatically uses updated schema after activation, migration is only for old data. | |
| canonical_name_fields | No | Replace the entity type's identity rule (how canonical_name / entity identity is derived). Triggers a major version bump. Each item is a single field name (string) or an all-required composite ({composite:[...]}). Rules are ORDERED PRECEDENCE WITH FALLBACK: the resolver uses the first rule whose fields are all present, not an unordered set. Example: [{"composite":["linkedin_url"]},"email","name"] keys on linkedin_url when present, else email, else name. Omit to keep the current rule. Passing [] clears the rule, but only succeeds when the schema also declares identity_opt_out; otherwise it is rejected (a schema must declare canonical_name_fields OR identity_opt_out). The existing reducer_config is preserved automatically — this is the safe way to re-key a type without reconstructing it. Applies to NEW writes only; it does NOT retroactively re-key existing entities (they keep their stored canonical_name until re-derived), so re-keying will not by itself merge existing duplicates. To see the current rule before replacing it, call describe_entity_type first; the update response also echoes the resolved canonical_name_fields. |