Entities and fields
Design an entity, pick field types and rules, index fields, and change a schema safely.
Beta
Data Hub is in Beta. It is off by default; an administrator turns it on per tenant.
You design entities in the web app under Data Hub ▸ Entities. You need the Data Hub Designer role, or Workspace Administrator.
Entities#
An entity has an API name and a display name. The API name is what automations use, and it cannot change. Names compare without regard to case, so two live entities in a workspace cannot share a name (dh_entity_name_taken).
A tenant can hold 200 entities by default. See Limits and permissions.
Fields#
A field has:
- An API name. It cannot change. It starts with a letter and then has up to 63 letters, digits or underscores (
^[A-Za-z][A-Za-z0-9_]{0,63}$). It cannot be one of the system field names. - A display name. Records store values by a hidden field id, so changing the display name never touches data.
- A type and rules: required, unique, indexed, a default, and options for the type.
A removed field can be restored for 30 days. After that it is purged.
Field types#
| Type | JSON value | Studio (.NET) | Python |
|---|---|---|---|
| Text | string | string |
str |
| Number | integer | long |
int |
| Decimal | string in canonical form ("1250.5"), never a float |
decimal |
Decimal |
| Boolean | true or false |
bool |
bool |
| Date | "yyyy-MM-dd" |
DateOnly |
datetime.date |
| Date and time | UTC "yyyy-MM-ddTHH:mm:ss.ffffffZ" |
DateTimeOffset (UTC) |
aware UTC datetime; a naive one is refused |
| Choice | the value's key, or a list for a multiple choice | string, List<string> |
str, list[str] |
Text compares without regard to case everywhere, including unique checks. Decimals compare by value: 1.0 and 1.00 are the same unique value.
A choice field takes its values from a choice set under Data Hub ▸ Choice sets. A choice set that a field uses cannot be deleted (dh_choice_set_in_use). Archive the values you no longer want instead.
Indexed fields#
An entity can have up to 20 indexed fields. Unique fields are always indexed. New fields are indexed by default until the 20 are used.
- A filter on an indexed field is fast at any size.
- Only indexed fields and system fields can be used to sort.
- A filter on a field that is not indexed scans the entity. It works up to 50,000 records with a warning. Above that it is refused with
422 dh_field_not_indexed. Index the field.
Change a schema#
- Safe changes apply at once: a new optional field, a new display name.
- Checked changes (making a field required or unique, narrower rules) first check every record. If records break the new rule, the change is refused with the list of those records (
dh_schema_change_unsafe). A checked change can check up to 50,000 records.
An automation that writes while a change is in progress gets 409 dh_schema_changed. Read the schema again and repeat the write.
History#
Every change to a record keeps the before and after value of each changed field. History is kept for 365 days by default (retention.dataHubHistoryDays). A record's history is purged with the record.
Let automations delete records#
Automations cannot delete records by default. To allow it, open the entity and turn on Settings ▸ Automations can delete records. Without it, a delete from an automation gets 403 dh_delete_disabled.
Entities
Fields
Field types
Indexed fields
Change a schema
History
Let automations delete records