Entities best practices

• Use bulk/batch rather than individual requests for ingestion.

  • Batch operations are always executed in this fixed order regardless of request sequence: (1) DELETE components, (2) POST entity components, (3) PUT entity components, (4) POST entities, (5) PUT entities, (6) PUT components, (7) PATCH entities, (8) PATCH components. This ordering ensures data integrity and prevents dependency conflicts between operations.

• Be aware that deleting an entity removes its associated components and relationships.

• Entity Management supports filtering with a query parameter in the request URL. However, ASP.NET Core/Kestrel has a default MaxRequestLineSize of 8 KB (8,192 bytes). Query strings that are too long will hit this limit, and the server will return a bad request.

Properties and relationships

• It is best to set relationships on the child pointing up to the parent (100+ children point to 1 parent).

• Entity Management does not validate relationship targets on ingress.

  • It is possible to have relationships to an entity or streams that don't exist.

• Property/relationship count constraints:

  • Ad hoc properties + Ad hoc relationships + Component properties + Relationships ≤ 1,024

  • Any combination of these elements is supported as long as their combined total does not exceed 1,024.

• Missing values are prefilled from the type definition. Callers do not need to supply every field on a property. The service automatically backfills the following from the type definition if they are absent from the request:

  • Unit of measure (Uom/UnknownUom)

  • Data type (TypeCode)

  • Enumeration set ID (EnumerationSetId) — populated for enum-typed properties

  • Property name

• Entity Management validates properties and relationships against the type definition:

  • Each property must exist in the type definition and be in an Active state. Required properties cannot carry a null value.

  • The unit of measure must be valid and dimensionally compatible with the type definition. The TypeCode must match exactly, with Object and ObjectArray rejected as unsupported.

  • For enum-typed properties, the submitted value must exist within the enumeration set and be Active.

  • For each relationship, it checks that the relationship is defined on the type, is Active, and respects cardinality (single-target relationships cannot have more than one target).

  • Any required properties or relationships defined on the type that are absent from the request are reported as validation errors after all items are processed.