uip df entities

Syntax and options for `uip df entities`, which browses and mutates Data Fabric entity schemas.

uip df entities browses and mutates Data Fabric entity schemas. An entity is a typed data model — a row shape with named fields and types. The verbs cover discovery (list, get), authoring (create, update), and removal (delete); record-level operations live on uip df records.

With --local, the same verbs act on entities authored in a solution on disk instead of the tenant. Refer to Local entities.

Synopsis

uip df entities list [--native-only | --federated-only] [--folder-key <key> | --include-folders]
uip df entities get <id> [--folder-key <key>]
uip df entities create <name> (-f <path> | --body <json>) [--folder-key <key>]
uip df entities update <id> (-f <path> | --body <json>) [-y --reason <text>] [--folder-key <key>]
uip df entities delete <id> -y --reason <text> [--folder-key <key>]
uip df entities validate [name] --local [--project-name <name>]

# Entities authored in the solution on disk
uip df entities list --local [--project-name <name>]
uip df entities get <name> --local [--project-name <name>]
uip df entities create <name> --local [--project-name <name>] [-f <path> | --body <json>]
uip df entities update <name> --local [--project-name <name>] (-f <path> | --body <json>)
uip df entities delete <name> --local -y [--project-name <name>] [--force]

Verbs

Verb	Purpose
list	List entities. Defaults to tenant-level entities; --folder-key scopes to one folder, --include-folders includes every folder's entities alongside tenant-level ones.
get	Return the schema (including all fields) of a single entity.
create	Create a new entity from a JSON definition.
update	Update an entity's metadata or schema — add fields, update field metadata, or remove fields (destructive, requires -y/--reason).
delete	Delete an entity outright (destructive, requires -y/--reason).
validate	Check the entities authored in a local solution, without packing. Requires --local.

--folder-key, --native-only, --federated-only, --include-folders

• --folder-key <key> (a folder GUID) scopes a verb to a folder-level entity instead of the tenant. It's accepted on every verb in this group. On list, it's mutually exclusive with --include-folders.
• --include-folders (on list only) lists tenant-level entities together with every folder's entities in one call.
• --native-only (on list only) filters out federated entities — those backed by an external connector connection (identified by a non-empty externalFields array).
• --federated-only (on list only) does the reverse and shows only federated entities. It is mutually exclusive with --native-only. Without either one, list returns all entities.

Local entities (--local)

--local switches list, get, create, update, and delete from the tenant to the entities authored in the solution on disk. No login is required, and nothing exists on a tenant until the solution deploys. The command must run from inside the solution: the CLI looks upward from the current directory for the solution's .uipx file and fails with Not inside a solution when it finds none.

Each locally authored entity is a pair of files:

• A .entity stub in its Entity project, for example MasterData/PurchaseOrder.entity.
• A definition resource, for example resources/solution_folder/entity/native/PurchaseOrder.json.

Differences from the tenant form:

• get, update, and delete take the entity name as <id>, because nothing has an ID until deploy. Entity names are unique across the solution, so the owning project is found by name.
• --project-name <name> names an Entity project in the solution. It is optional on every verb, and fails with --project-name requires --local when passed without --local.
• Options that address the tenant fail with --local. The command names the offending option instead of ignoring it:
  • On every verb: --folder-key.
  • On list: --include-folders, --native-only, and --federated-only.
  • On update and delete: --reason.
• update takes the same addFields / updateFields / removeFields body as the tenant form, applied to the local document.
• list and get return Code: InlineEntityList and InlineEntitySchema; create, update, and delete return InlineEntityCreated, InlineEntityUpdated, and InlineEntityDeleted. Refer to Local entity examples.

uip df entities validate --local checks the pairs before uip solution pack does.

uip df entities list

List Data Fabric entities.

Options

Short	Long	Value	Default	Description
—	--native-only	flag	off	Show only native entities; exclude federated entities with external connections.
—	--folder-key	key	—	Folder key (GUID) to scope the listing to a specific folder. Mutually exclusive with --include-folders.
—	--include-folders	flag	off	List tenant-level entities together with entities from every folder you can see. Mutually exclusive with --folder-key.
—	--federated-only	flag	off	Show only federated entities, those backed by external connections. Mutually exclusive with --native-only.
—	--local	flag	off	List the entities authored in the solution on disk instead of the tenant.
—	--project-name	name	—	With --local: list only this Entity project. Omitted, every Entity project in the solution is listed.

Examples

uip df entities list --native-only

uip df entities list --folder-key f1000000-0000-0000-0000-000000000001

Data shape (--output json)

{
  "Code": "EntityList",
  "Data": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Invoice",
      "displayName": "Invoice",
      "entityType": "Standard",
      "description": "Invoice records",
      "folderId": "f1000000-0000-0000-0000-000000000001",
      "isRbacEnabled": false,
      "fields": [
        { "id": "f1000000-0000-0000-0000-000000000001", "name": "amount" }
      ],
      "externalFields": []
    }
  ]
}

Important:

Data rows here are the raw SDK objects, in camelCase — unlike get's response below, list does not PascalCase field names or reshape the payload. Each row's folderId is the value to pass as --folder-key on follow-up commands targeting that entity.

uip df entities get

Return the schema of a single entity, including all fields.

Arguments

Name	Required	Purpose
<id>	yes	Entity ID (UUID). Find it with entities list. With --local, the entity name.

Options

Short	Long	Value	Default	Description
—	--folder-key	key	—	Folder key (GUID) of the folder containing the entity, for folder-scoped entities.
—	--local	flag	off	Read an entity authored in the solution on disk. <id> is then the entity name.
—	--project-name	name	—	With --local: the Entity project that owns the entity. Optional — omitted, the owner is found by name.

Example

uip df entities get a1b2c3d4-0000-0000-0000-000000000001

Data shape (--output json)

{
  "Code": "EntitySchema",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Invoice",
    "DisplayName": "Invoice",
    "EntityType": "Standard",
    "Description": "Invoice records",
    "IsRbacEnabled": false,
    "Fields": [
      {
        "Id": "f1000000-0000-0000-0000-000000000002",
        "Name": "amount",
        "DisplayName": "Amount",
        "FieldDataType": {
          "Name": "DECIMAL",
          "DecimalPrecision": 2,
          "MinValue": 0,
          "MaxValue": 999999
        },
        "IsRequired": true,
        "IsUnique": false,
        "IsEncrypted": false,
        "IsRbacEnabled": false,
        "IsPrimaryKey": false,
        "IsSystemField": false
      }
    ]
  }
}

Unlike list, this response is PascalCase. A field's type name and its constraints (DecimalPrecision, MinValue, MaxValue, LengthLimit, and so on, depending on type) live nested under FieldDataType, not as flat properties on the field.

uip df entities create

Create a new entity. The entity name must start with a letter and contain only letters, numbers, and underscores. Pass the definition either inline (--body) or from a file (--file).

Arguments

Name	Required	Purpose
<name>	yes	Entity name (starts with a letter; letters, numbers, underscores only).

Options

Short	Long	Value	Default	Description
-f	--file	path	—	Path to a JSON file with the entity definition (fields array required; displayName, description, isRbacEnabled, isAnalyticsEnabled optional).
—	--body	JSON	—	Inline JSON entity definition, same shape as --file.
—	--folder-key	key	—	Folder key (GUID) of the target folder, to create a folder-scoped entity instead of a tenant-level one.
—	--local	flag	off	Create the entity in the solution on disk instead of the tenant.
—	--project-name	name	—	With --local: the Entity project to create the entity in. A missing project is scaffolded and registered in the solution. Omitted, the project is named after the entity. An existing project must be of type Entity, since pack ships entities only from those.

Entity definition object:

{
  "displayName": "Invoice",
  "description": "Invoice records",
  "isRbacEnabled": false,
  "fields": [
    { "name": "title", "type": "STRING" }
  ]
}

Important:

Each field object requires name, not fieldName — passing fieldName fails with the validation error Each field must include a 'name' string. A field object copied verbatim from entities get's output (which uses Name/FieldDataType, PascalCase) is also accepted here and normalized automatically to this flat write shape.

Valid type values come from the SDK's EntityFieldDataType enum — an invalid type fails with a ValidationError listing the full allowed set. Beyond the simple scalar types (STRING, DECIMAL, GUID, BOOLEAN, DATE, DATETIME, …), several types take extra required properties on the field object:

Type	Extra required properties
CHOICE_SET_SINGLE / CHOICE_SET_MULTIPLE	choiceSetId — UUID from df choice-sets list.
RELATIONSHIP	referenceEntityId (UUID of the target entity, from entities list) and referenceFieldId (UUID of a field on the target entity, from entities get <target-id>). Optionally referenceFolderKey when the target entity lives in a different folder.
FILE	Only name and type — the server auto-wires the internal attachment reference. Populate the value later with uip df files upload.
MULTILINE_MAX	Optional lengthLimit (UTF-16 byte budget, 1–131072; defaults to roughly 65,536 characters). Not filterable or sortable; records list/query return only a size marker for it — read full content with records get. Gated by the tenant's MultilineMax feature flag.

A RELATIONSHIP column on a record always stores the target record's Id (a UUID), regardless of which referenceFieldId configured the join — see records insert for how to write the value.

Examples

uip df entities create Invoice --file ./invoice.entity.json

uip df entities create Invoice \
    --body '{"displayName":"Invoice","fields":[{"name":"amount","type":"DECIMAL"}]}'

# choice-set, relationship, file, and large-text fields
uip df entities create Expense \
    --body '{"displayName":"Expense","fields":[{"name":"category","type":"CHOICE_SET_SINGLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000001","isRequired":true},{"name":"submitter","type":"RELATIONSHIP","referenceEntityId":"a1b2c3d4-0000-0000-0000-000000000010","referenceFieldId":"f1000000-0000-0000-0000-000000000100","isRequired":true},{"name":"receipt","type":"FILE"},{"name":"notes","type":"MULTILINE_MAX"}]}'

Data shape (--output json)

{
  "Code": "EntityCreated",
  "Data": { "ID": "a1b2c3d4-0000-0000-0000-000000000001" }
}

uip df entities update

Update an entity's metadata or schema. The body accepts addFields, updateFields, removeFields, displayName, description, and isAnalyticsEnabled/isRbacEnabled. The entity name itself is immutable — it cannot be included in the update body.

Arguments

Name	Required	Purpose
<id>	yes	Entity ID (UUID). With --local, the entity name.

Options

Short	Long	Value	Default	Description
-f	--file	path	—	Path to JSON file with update options.
—	--body	JSON	—	Inline JSON update options.
-y	--yes	flag	—	Required when removeFields is non-empty — acknowledges the field deletion is irreversible.
—	--reason	text	—	Required when removeFields is non-empty — echoed back in the response so the caller can log it.
—	--folder-key	key	—	Folder key (GUID) of the folder containing the entity, for folder-scoped entities.
—	--local	flag	off	Update an entity authored in the solution on disk. <id> is then the entity name.
—	--project-name	name	—	With --local: the Entity project that owns the entity. Optional — omitted, the owner is found by name.

• addFields — array of new fields, flat write shape (name + type, plus type-specific extras — see the create section above). A field object copied from entities get is also accepted and normalized.
• updateFields — array keyed by field id (from entities get), with the metadata properties being changed (for example displayName, description, isRequired, isRbacEnabled, isEncrypted, isHiddenField, defaultValue, constraints). Do not paste a full copied field object here — pass id plus only the flat properties being changed. updateFields cannot change a field's type or its isUnique setting.
• removeFields — array of {"name": "<fieldName>"} objects, identified by name, not id. Requires -y/--yes and --reason "<text>" — the operation deletes the field's stored values and cannot be undone.
• Updating entity metadata (description, isRbacEnabled, isAnalyticsEnabled) requires displayName to also be present in the same body, even if it's unchanged — fetch the current displayName with entities get first if you don't already have it.

Examples

# Add a field
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"addFields":[{"name":"note","type":"STRING","lengthLimit":200}]}'

# Rename an existing field's display name
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"updateFields":[{"id":"f1000000-0000-0000-0000-000000000002","displayName":"Amount (USD)","isRequired":true}]}'

# Remove a field — destructive, requires --yes and --reason
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"removeFields":[{"name":"oldColumn"}]}' \
    --yes --reason "quarterly cleanup"

Data shape (--output json)

{
  "Code": "EntityUpdated",
  "Data": { "ID": "a1b2c3d4-0000-0000-0000-000000000001" }
}

When the update includes removeFields, the response also echoes what was removed:

{
  "Code": "EntityUpdated",
  "Data": {
    "ID": "a1b2c3d4-0000-0000-0000-000000000001",
    "RemovedFields": ["oldColumn"],
    "Reason": "quarterly cleanup"
  }
}

uip df entities delete

Delete an entity outright. This is irreversible and removes the entity's schema along with all its records.

Arguments

Name	Required	Purpose
<id>	yes	Entity ID (UUID). With --local, the entity name.

Options

Short	Long	Value	Default	Description
-y	--yes	flag	—	Required. Acknowledges this is an irreversible operation.
—	--reason	text	—	Required. Reason for the deletion — echoed back in the response so the caller can log it.
—	--folder-key	key	—	Folder key (GUID) of the folder containing the entity, for folder-scoped entities.
—	--local	flag	off	Delete an entity authored in the solution on disk: its .entity stub and its definition resource. <id> is then the entity name, and --reason is not accepted.
—	--project-name	name	—	With --local: the Entity project that owns the entity. Optional — omitted, the owner is found by name.
—	--force	flag	off	With --local: delete a stub/resource pair that does not verify — anything entities list --local reports with a Problem — or a definition resource that no project declares any more. Every check runs before anything is removed: a resource another project still declares, or one that describes a referenced platform entity, is refused and nothing changes.

Example

uip df entities delete a1b2c3d4-0000-0000-0000-000000000001 \
    --yes --reason "test entity cleanup"

Data shape (--output json)

{
  "Code": "EntityDeleted",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Reason": "test entity cleanup"
  }
}

uip df entities validate

Validate the entities authored in the solution on disk, without packing. validate runs the same two checks that uip solution pack runs on each entity, in the same order: the pairing between the entity's .entity stub and its definition resource, then the entity schema. A clean result means the project's entities do not fail the pack. No login is required.

validate works on local entities only. Without --local, it fails with 'entities validate' requires --local, because the server validates tenant entities on write.

Arguments

Name	Required	Purpose
[name]	no	Validate only this entity. Entity names are unique across the solution, so the owning project is found by name.

Options

Short	Long	Value	Default	Description
—	--local	flag	—	Required. Act on the entities authored in the local solution.
—	--project-name	name	—	Validate only this Entity project. Omitted, every Entity project in the solution is checked.

Examples

# Validate every entity in the solution
uip df entities validate --local

# Validate every entity in one Entity project
uip df entities validate --local --project-name MasterData

# Validate one entity
uip df entities validate PurchaseOrder --local

Data shape (--output json)

{
  "Code": "InlineEntityValidated",
  "Data": {
    "Project": "MasterData",
    "Valid": true,
    "Entities": [
      {
        "Entity": "PurchaseOrder",
        "Diagnostics": []
      }
    ]
  }
}

A whole-solution run omits the top-level Project field and names the project on each row instead.

Failures

When any entity fails a check, the command exits 1 with ErrorCode: invalid_argument and Retry: RetryWillNotFix. Data.Diagnostics holds one row per entity checked:

Field	Meaning
Project	Entity project, on a whole-solution run.
Entity	Entity name.
ResourceFile	Definition resource the stub resolved to.
PairProblem	Set when the .entity stub and its definition resource do not agree. uip df entities delete <name> --local --force removes such a pair.
ProjectProblem	Set on a whole-solution run when an Entity project cannot be read at all.
Diagnostics	Schema findings, each with Code, Message, and Field.

Local entity examples

These commands run from inside the solution directory, without a login.

# Create an Entity project with its first entity
uip df entities create PurchaseOrder --local --project-name MasterData

# Add two fields to it
uip df entities update PurchaseOrder --local \
    --body '{"addFields":[{"name":"OrderNumber","type":"STRING","lengthLimit":100,"isRequired":true},{"name":"Amount","type":"DECIMAL","decimalPrecision":2,"defaultValue":"0"}]}'

# List every entity authored in the solution
uip df entities list --local

# Read one entity's stored document
uip df entities get PurchaseOrder --local

# Delete it; add --force for a pair that does not verify
uip df entities delete PurchaseOrder --local --yes

create --local returns the files it wrote, and Created: "project" when it scaffolded the project:

{
  "Code": "InlineEntityCreated",
  "Data": {
    "Project": "MasterData",
    "Entity": "PurchaseOrder",
    "EntityFile": "/workspace/Sol/MasterData/PurchaseOrder.entity",
    "ResourceFile": "/workspace/Sol/resources/solution_folder/entity/native/PurchaseOrder.json",
    "Created": "project"
  }
}

list --local returns one row per entity:

{
  "Code": "InlineEntityList",
  "Data": [
    {
      "Project": "MasterData",
      "Entity": "PurchaseOrder",
      "EntityFile": "/workspace/Sol/MasterData/PurchaseOrder.entity",
      "ResourceFile": "/workspace/Sol/resources/solution_folder/entity/native/PurchaseOrder.json",
      "LocallyAuthored": true
    }
  ]
}

• LocallyAuthored: false marks an entity the solution references from the platform. The local commands do not edit it.
• A row with Problem is a stub/resource pair that does not verify, or a project directory the command cannot read. uip df entities delete <name> --local --force clears a broken pair.

get --local returns the stored entity document as-is, so a field carries SqlType and FieldDisplayType, not the type that the create body takes.

Related

• uip df records — manage the rows held by these entities.
• uip df files — file attachments on records.
• uip df choice-sets — the choice sets referenced by CHOICE_SET_SINGLE/CHOICE_SET_MULTIPLE fields.
• uip vss generate — generate TypeScript types from a Data Fabric schema export.

See also

• Data Fabric tool overview
• Global options
• Exit codes