[DX] GAP-11: sdk.entities.insert_records() entity_key must be a UUID, not the entity name — undocumented #1503

Summary

sdk.entities.insert_records(entity_key="DepartmentBudget", ...) returns HTTP 400 "The value 'DepartmentBudget' is not valid." The parameter name entity_key implies a logical key (like a name or slug), but the API actually requires the entity's internal UUID.

Root Cause

The DataFabric API endpoint EntityService/entity/{entity_key}/insert-batch expects the entity's internal UUID (the id field), not its name. The sdk.entities.insert_records() method accepts entity_key: str with no type hint or documentation about what value is expected.

The SQL query path (sdk.entities.query_entity_records()) accepts names, which makes the inconsistency more confusing.

Observed Behaviour

result = sdk.entities.insert_records(
    entity_key="DepartmentBudget",   # entity name — reasonable assumption
    records=[{"department": "Finance", "budget": 100000}]
)
# HTTP 400: "The value 'DepartmentBudget' is not valid."

Workaround

Call the DataFabric entities list API directly to obtain the UUID, then pass that UUID:

import httpx
resp = httpx.get(f"{base_url}/datafabric_/api/Entity", headers={"Authorization": f"Bearer {token}"})
entity_uuid = next(e["id"] for e in resp.json() if e["name"] == "DepartmentBudget")
sdk.entities.insert_records(entity_key=entity_uuid, records=[...])

Note: sdk.entities.list_entities() cannot be used for this lookup — it crashes with a pydantic validation error (see related issue GAP-12).

Suggested Fix

1. Accept the entity name and resolve it to a UUID internally (preferred).
2. Or document clearly in the docstring that entity_key is a UUID and show how to obtain it.
3. Consider renaming the parameter to entity_id to make the UUID requirement obvious.

Impact

• Severity: High
• HTTP 400 with a cryptic error message; no guidance on what the correct value should be
• The inconsistency with the SQL query path (which accepts names) makes this especially confusing