Asset types#

An asset type defines an identity key and property rules for a class of assets. Assets can belong to multiple types. Every member must satisfy all of its types: the identity key is a nonempty string, and additional properties can be required or suggested, with string or numeric values.

Connect the client#

This guide assumes you have installed the client and setup your API keys.

Define a type and create an asset#

Use create_asset_type() to define the identity and AssetTypeProperty for additional property rules.

from nominal.core import AssetTypeProperty, AssetTypePropertyValueType

pump_type = client.create_asset_type(
    "Pump",
    primary_key="serial_number",
    properties={
        "model": AssetTypeProperty(required=True),
        "rated_power_kw": AssetTypeProperty(
            value_type=AssetTypePropertyValueType.NUMBER,
        ),
    },
)
pump = client.create_asset(
    "Pump P-001",
    types=[pump_type],
    properties={
        "serial_number": "P-001",
        "model": "Centrifugal",
        "rated_power_kw": 12.5,
    },
)
print(pump.nominal_url)
print(pump_type.nominal_url)

Creation uses the client’s default workspace. Each create_asset_type call creates a new resource; a name is not an identity. Save its RID and reuse it with client.get_asset_type(rid) on subsequent runs. Type objects and RIDs are both accepted wherever a type is assigned or selected.

AssetTypeProperty defaults to value_type=AssetTypePropertyValueType.STRING and required=False. Suggested properties may be omitted; required properties must be present. The primary key is always required and must not be repeated in the additional property rules.

Find types and their members#

search_asset_types() finds definitions; search_assets() finds their members.

Searches default to active resources in the client’s default workspace. Pass workspace=WorkspaceSearchType.ALL (imported from nominal.core) to search all accessible workspaces. search_assets(types=[...]) matches any selected type; an empty list matches no assets, while None omits the filter.

The type filter is ANDed with other filters. For example, client.search_assets(types=[pump_type], labels=["production", "validated"]) requires membership in the pump type and both labels. With multiple types, membership in any one of them is sufficient; all supplied labels and property equalities must still match.

type_rids is a snapshot. get_types() fetches definitions for those memberships; call pump.refresh() first if memberships may have changed remotely.

Resolve an asset by identity#

Use create_or_update_asset_by_primary_key() when repeated calls must resolve to the same active asset.

same_pump = client.create_or_update_asset_by_primary_key(
    pump_type,
    name="Pump P-001",
    properties={
        "serial_number": "P-001",
        "model": "Centrifugal",
    },
)
assert same_pump.rid == pump.rid

The server resolves concurrent requests with the same type and identity to one active asset. This differs from get_or_create_asset_by_properties, which searches before creating and does not provide an atomic identity guarantee. Archived assets are ignored: an identity held only by an archived asset can create a new active asset.

Existing assets are returned unchanged by default (update_if_exists=False).

Warning

update_if_exists=True replaces metadata and memberships; it is not a patch. It replaces the name, description, properties and labels, clears links and legacy data scopes, and keeps only the identity type plus the additional types you supply. Omitting description clears the existing description; omitting labels removes all labels, and omitting types removes other memberships. Properties absent from the supplied mapping are removed.

The server preserves attachments and attached data. Prefer update() for partial metadata edits.

Both creation and replacement use the client’s default workspace. Supply every required property for the identity type and any additional types. The returned object is a fresh snapshot; an earlier pump object is not refreshed by this call.

Update definitions and memberships#

Use update() to change a definition and update() to change memberships.

pump_type.update(description="Pumps tracked by manufacturer serial number")
pump.update(types=[pump_type])

Omitting types leaves memberships unchanged; types=[] removes them all. The server validates the resulting properties and memberships together, so pass both in one update when adding a type whose required properties are not yet present.

For type definitions, omitted properties leave the rules unchanged, while pump_type.update(properties={}) removes all additional property rules. The identity key is separate. The server rejects changes incompatible with active members and primary-key renames once memberships exist.

pump_type.archive() hides a type from default searches without removing existing memberships. Archived types cannot be assigned to new members. Use unarchive() to restore one and refresh() to update the local snapshot after either operation. Type search accepts ArchiveStatusFilter.ANY or .ARCHIVED from nominal.core.