einstein-analytics-data-model

# Einstein Analytics Data Model (XMD and Dataset Versioning)

Use this skill when a practitioner needs to understand the CRM Analytics dataset conceptual model — specifically the Extended Metadata (XMD) three-layer system, dataset versioning, and the REST API mechanics for customizing how dataset fields are displayed. This skill is scoped to XMD conceptual understanding and API mechanics, not to dataflow or recipe transformation logic.

---

## Before Starting

Gather this context before working on anything in this domain:

- What is the API name and ID of the target dataset? (The ID is required for all XMD API calls, not the API name.)
- Which XMD type is the target: `main` (org-level customization) or `user` (per-user preference)? System XMD is platform-generated and immutable.
- Is this a field label change, a field type reclassification (measure vs. dimension), or a date/number format override?
- Is the dataset a live dataset or a versioned snapshot? Dataset version IDs differ from the stable dataset ID.

---

## Core Concepts

### The Three-Layer XMD System

CRM Analytics datasets have three XMD layers:

1. **System XMD** (`type=system`) — Auto-generated by the platform when a dataset is created. Contains the base field schema: API names, inferred data types, and default formatting. **Immutable.** PATCH to system XMD returns HTTP 400.

2. **Main XMD** (`type=main`) — The org-level customization layer. Changes here apply to all users who access the dataset. This is where field labels, aliases, date formats, number formats, measure/dimension reclassification, and color palettes are set. PATCH `/wave/datasets/{datasetId}/xmds/main` to apply org-wide customizations.

3. **User XMD** (`type=user`) — Per-user preference layer. Overrides main XMD only for the requesting user. Not suitable for shared org-wide label standards.

When the Analytics UI renders a field, it resolves the label using: user XMD → main XMD → system XMD (first non-null value wins). Practitioners often mistake system XMD labels as the changeable default — you must write to main XMD to override them.

### CRM Analytics Datasets Are Columnar Stores, Not Object Stores

CRM Analytics datasets are **columnar stores**. They do not have a relationship graph like Salesforce object relationships. There are no foreign key constraints. Cross-dataset relationships (joins) are expressed at query time in SAQL using `load` and `join` operations — not as persistent relationship metadata in XMD. XMD does not store join definitions.

**Critical distinction:** You cannot query WaveXmd records using SOQL. The XMD REST API (`/wave/datasets/{id}/xmds/{xmdtype}`) is the only supported interface. SOQL cannot access Analytics metadata objects and throws INVALID_TYPE if attempted.

### Dataset Versioning

CRM Analytics datasets are versioned. Each time a dataflow or recipe runs and produces output, a new **version** of the dataset is created. The dataset has:
- A stable `id` (the dataset's persistent identifier across all versions)
- A `currentVersionId` pointing to the latest version
- Historical version IDs accessible via `GET /wave/datasets/{datasetId}/versions`

XMD is attached at the **dataset level** (not version level) — main XMD changes persist across dataset refreshes. However, if a new dataflow run changes the schema (adds or removes fields), the system XMD for the new version will differ, and main XMD customizations for removed fields will be orphaned silently.

---

## Common Patterns

### Pattern: PATCH Main XMD to Rename a Field Label

**When to use:** When a dataset field API name is a cryptic system-generated string and the dashboard should display a business-readable label.

**How it works:**
1. GET the current main XMD: `GET /services/data/v60.0/wave/datasets/{datasetId}/xmds/main`
2. Locate the field entry under `dimensions` or `measures` in the response body.
3. Construct a PATCH payload with only the `label` property changed.
4. PATCH: `PATCH /services/data/v60.0/wave/datasets/{datasetId}/xmds/main`

XMD PATCH is **additive-merge** — you only need to include changed properties. The full field list is not required.

**Why not edit system XMD:** System XMD is immutable. The API returns HTTP 400 if you attempt to PATCH `xmds/system`.

### Pattern: Reclassify a Field from Dimension to Measure (or Vice Versa)

**When to use:** When a numeric field like year or fiscal period is being aggregated as a measure but should be treated as a grouping dimension.

**How it works:** In the main XMD PATCH payload, move the field from the `measures` array to the `dimensions` array. Include the field's API name and `label`. The platform validates that the field's data type is compatible with the target classification — numeric fields can be either; string fields cannot be measures.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Rename a field label for all users | PATCH main XMD `label` property | Main XMD applies org-wide |
| Override label only for yourself | PATCH user XMD | User XMD is per-user |
| Understand raw field schema | GET system XMD | System XMD shows platform-generated schema |
| Attempt to edit system XMD | Stop — not supported | System XMD is immutable; PATCH returns HTTP 400 |
| Query dataset fields via SOQL | Use REST API instead | WaveXmd is not queryable via SOQL |
| Field disappeared after dataflow refresh | Check schema drift | New version may have dropped the field |

---

## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. **Identify the dataset** — Get the dataset ID via `GET /wave/datasets` or the Analytics Studio Dataset Inspector.
2. **Read system XMD** — `GET /wave/datasets/{id}/xmds/system` to understand raw schema, field API names, and defaults.
3. **Read and back up main XMD** — `GET /wave/datasets/{id}/xmds/main`. Save the response to file — main XMD has no version history and cannot be recovered after PATCH.
4. **Identify target fields** — List fields needing label, format, or classification changes. Note whether they are in `dimensions` or `measures`.
5. **Construct PATCH payload** — Build the minimal additive-merge JSON with only changed properties.
6. **PATCH main XMD** — `PATCH /wave/datasets/{id}/xmds/main`. Verify HTTP 200.
7. **Validate in Analytics Studio** — Open a lens on the dataset and confirm field labels and formats are correct.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] Targeting main XMD, not system XMD
- [ ] Used REST API (`/wave/datasets/{id}/xmds/main`), not SOQL
- [ ] Main XMD backed up before PATCH
- [ ] PATCH payload verified as additive-merge format
- [ ] Field API names match exactly (case-sensitive)
- [ ] After PATCH: HTTP 200 confirmed and label visible in Analytics Studio lens

---

## Salesforce-Specific Gotchas

1. **System XMD is immutable — PATCH returns HTTP 400** — A frequent mistake is attempting `PATCH /wave/datasets/{id}/xmds/system`. The API rejects this with HTTP 400. Always PATCH `xmds/main`.

2. **WaveXmd is not SOQL-queryable** — SOQL does not support `SELECT … FROM WaveXmd`. The REST API is the only interface. Attempting SOQL on WaveXmd throws an INVALID_TYPE error.

3. **Main XMD has no version history — PATCH is destructive** — CRM Analytics does not save the previous main XMD before a PATCH overwrites it. There is no undo. Always GET and save the current main XMD JSON to a file before any modification.

4. **Schema drift orphans main XMD customizations silently** — If a new dataflow run removes a field from the dataset schema, the main XMD entry for that field becomes orphaned. It does not cause an error but the customization applies to a field that no longer exists.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| XMD PATCH payload | JSON delta for main XMD update |
| Pre-patch XMD backup | GET response of main XMD before modification |
| Dataset version log | Record of current version ID and schema change history |

---

## Related Skills

- `admin/analytics-dataflow-development` — Use for sfdcDigest, Augment, sfdcRegister node configuration and Data Sync setup
- `admin/analytics-recipe-design` — Use for recipe node types, transformation logic, and formula language
- `admin/analytics-dataset-management` — Use for dataset scheduling, row limits, and dataset sharing settings
- `architect/analytics-data-architecture` — Use for multi-dataset architecture decisions and CRM Analytics platform design