roboto.domain.custom_fields.custom_field
Module Contents
CustomField
A typed, queryable schema extension defined by an organization for a Roboto entity type.
Custom fields let an organization extend Roboto’s built-in entity schemas with typed fields tailored to its data and workflows. Each field is scoped to one TargetEntityType (e.g. Dataset, Collection, or Device) and is optimized for efficient search — equality, range, prefix, and sort — on its values.
A field’s status tells you what you can do with it:
Creating: the field is being set up. Values cannot yet be assigned to entities, and search and sort queries cannot reference it.Ready: the field is available end-to-end. Values can be set on entities ofentity_type, and the field can be used in search filters and to sort search results.Deleting: the field is on its way out. Callers should treat it as already gone — values can no longer be set and the field will shortly disappear.Failed: the most recent create or delete attempt did not succeed.
Create and delete return as soon as the status transition has been recorded; the rest of the work happens asynchronously. Use wait_to_be_ready() after create() and wait_to_be_deleted() after delete() if you need to wait for that work to finish.
Field names are unique within an (org_id, entity_type) pair, must match ^[a-z][a-z0-9_]{0,62}$ (lowercase ASCII, max 63 chars), and are subject to a per-org-tier quota on each entity type.
Parameters
roboto_client roboto.CustomField.add_enum_values()
Add values to the set this enum field accepts.
Re-fetches the field before updating it: an update has to list every value the field already has, so a value someone else added since this object was loaded would otherwise read as a removal and be rejected.
Only administrators in this field’s organization can update it.
Parameters
values strValues to allow, on top of the field’s current ones. Each is normalized to Unicode NFC with runs of whitespace collapsed to a single space; passing one the field already has, in any spelling that normalizes the same, changes nothing. A field may hold at most 250 values.
Returns
This same CustomField, with its in-memory record replaced by the server’s updated copy. Called with no values, it returns without contacting the server.
Raises
This field is not an enum field.
The field no longer exists.
The caller lacks permission to update this field.
pydantic.ValidationErrorA value cannot be stored, or the field would end up with more values than it is allowed.
Usage
field.options.enum_values
# ['low', 'medium', 'high']
field.add_enum_values("critical").options.enum_values
# ['low', 'medium', 'high', 'critical']CustomField.create()
Define a new custom field for an entity type in the caller’s organization.
Returns as soon as the field has been registered. The newly created field is typically still Creating and is not yet usable for setting values or running queries; call wait_to_be_ready() if you need to use the field immediately.
Only administrators in the organization can define new custom fields.
Parameters
field_name strName of the field, unique within the (org_id, entity_type) pair. Must match ^[a-z][a-z0-9_]{0,62}$. Fixed at creation time — cannot be changed later.
Value type of the field. Determines which operators are supported in search and sort.
Roboto entity type this field extends.
display_name Optional[str]Human-readable label shown in the UI. Defaults to None.
description Optional[str]Longer description of the field’s meaning.
options Optional[roboto.Type-specific configuration. Required for Enum fields (to declare the allowed values).
metadata_path Optional[str]Reserved for promoting an existing metadata key into a custom field. Not yet supported; leave as None.
caller_org_id Optional[str]Organization that should own the field. If omitted, the field is created in the caller’s organization.
roboto_client Optional[roboto.Roboto client instance. Uses the default if omitted.
Returns
The newly created CustomField. Its status is typically Creating; call wait_to_be_ready() to block until it is Ready.
Raises
A field with this field_name and entity_type already exists in the target org.
The request fails validation (e.g., a field_name that does not match the regex, an enum field without options, or options whose field_type does not match field_type).
The limit on custom field definitions has been reached for the target organization and Roboto entity type.
The caller is not an administrator in the target org.
Usage
Define a string field on datasets:
field = CustomField.create(
field_name="flight_id",
field_type=CustomFieldType.String,
entity_type=TargetEntityType.Dataset,
display_name="Flight ID",
)
field.wait_to_be_ready()Define an enum field with a fixed set of allowed values:
from roboto.domain.custom_fields import EnumFieldOptions
field = CustomField.create(
field_name="severity",
field_type=CustomFieldType.Enum,
entity_type=TargetEntityType.Event,
options=EnumFieldOptions(enum_values=["low", "medium", "high"]),
)CustomField.delete()
Delete this custom field.
Returns as soon as the field has been moved to Deleting. From the caller’s perspective the field is gone at that point: values can no longer be set, and the field will shortly disappear from query results. The rest of the removal happens asynchronously; call wait_to_be_deleted() if you need to know when it has finished.
Only administrators in the target organization can delete custom fields.
Raises
The caller lacks permission to delete this field.
Return type
Usage
field = CustomField.from_name_and_entity_type("flight_id", TargetEntityType.Dataset)
field.delete()
field.wait_to_be_deleted()Properties
CustomField.description
Long-form description of the field’s meaning, or None if unset.
CustomField.display_name
Human-readable label for the field, or None.
CustomField.entity_type
Roboto entity type this field extends.
CustomField.field_id
Opaque, globally unique identifier for this field.
CustomField.field_name
Name of the field, unique within (org_id, entity_type) and fixed at creation time.
CustomField.field_type
Value type of the field. Fixed at creation time.
CustomField.from_id()
Load an existing custom field by its field_id.
Parameters
field_id strOpaque identifier assigned at create time.
roboto_client Optional[roboto.Roboto client instance. Uses the default if omitted.
Returns
The CustomField with this field_id.
Raises
No field with this field_id is visible to the caller.
Usage
field = CustomField.from_id("cf_abc123")
field.field_name
# 'flight_id'CustomField.from_name_and_entity_type()
Load a custom field by field_name and entity_type.
Field names are unique within an (org_id, entity_type) pair, so the name plus the entity type fully qualifies a field within a given org.
Parameters
field_name strName of the field, as supplied to create().
Entity type the field extends.
owner_org_id Optional[str]Organization that owns the field. If omitted, searches the caller’s organization.
roboto_client Optional[roboto.Roboto client instance. Uses the default if omitted.
Returns
The matching CustomField.
Raises
No field with this name and entity type exists in the target org.
The caller is not authorized to retrieve the field.
Usage
field = CustomField.from_name_and_entity_type(
field_name="flight_id",
entity_type=TargetEntityType.Dataset,
)Properties
CustomField.last_error
Human-readable summary of the most recent failure, if any.
Populated when status is CustomFieldStatus.Failed, and may stay set until the next failure or success.
CustomField.list()
Yield custom fields visible to the caller, optionally filtered by entity type and status.
By default, only fields in Creating, Ready, or Failed are returned; fields in Deleting are excluded because they are on their way out. Pass statuses= explicitly to override this.
Parameters
entity_type Optional[roboto.If provided, restrict results to fields targeting this entity type.
statuses Optional[collections.If provided, restrict results to fields in any of these statuses. Defaults to (Creating, Ready, Failed).
owner_org_id Optional[str]Organization to list fields from. If omitted, lists fields in the caller’s organization.
roboto_client Optional[roboto.Roboto client instance. Uses the default if omitted.
Yields
CustomField instances matching the filters, in pages transparently fetched as the generator is consumed.
Return type
Usage
List every Ready field on datasets in the caller’s org:
for field in CustomField.list(
entity_type=TargetEntityType.Dataset,
statuses=[CustomFieldStatus.Ready],
):
print(field.field_name, field.field_type)Properties
CustomField.metadata_path
Source metadata key the field was promoted from, if any. Reserved for future use.
CustomField.modified
UTC timestamp of the field’s most recent status or other change.
CustomField.modified_by
User ID of the most recent modifier. May be a system identity for automatic status changes.
CustomField.options
Type-specific configuration, or None if the field type takes none.
For enum fields this carries the allowed values and is required.
CustomField.refresh()
Re-fetch this field’s record from the server and return self.
Useful for observing asynchronous state transitions (e.g., Creating → Ready) without constructing a new object.
Returns
This same CustomField, with its in-memory record replaced by a freshly fetched copy.
Raises
The field has been fully deleted.
Usage
field.refresh().status
# <CustomFieldStatus.Ready: 'ready'>Properties
CustomField.status
Current lifecycle status. See the class docstring for the state machine.
CustomField.update()
Update mutable metadata on this custom field in place.
Passing NotSet (the default) leaves a field unchanged; passing None clears it.
Only administrators in this field’s organization can update it.
Parameters
display_name Union[str, None, roboto.New display name, or None to clear it.
description Union[str, None, roboto.New description, or None to clear it.
Replacement type-specific configuration. Must be for this field’s field_type. For an enum field, the new enum_values must include every existing value: values can be added but not removed. Re-sending a value the field already has is harmless: repeats are dropped, not rejected.
Returns
This same CustomField, with its in-memory record replaced by the server’s updated copy.
Raises
options are for a different field type, or would remove an existing enum value.
The field no longer exists.
The caller lacks permission to update this field.
pydantic.ValidationErrorAn enum value cannot be stored, or enum_values is longer than a field may declare. Raised before the request is sent.
Usage
field.update(display_name="Flight identifier")Add a value to an enum field:
from roboto.domain.custom_fields import EnumFieldOptions
field.update(options=EnumFieldOptions(enum_values=[*field.options.enum_values, "critical"]))A value the field already has keeps its place, and the new one is appended:
field.options.enum_values
# ['low', 'medium', 'high']
updated = field.update(
options=EnumFieldOptions(enum_values=[*field.options.enum_values, "medium", "critical"])
)
updated.options.enum_values
# ['low', 'medium', 'high', 'critical']Clear the description:
field.update(description=None)CustomField.wait_to_be_deleted()
Block until this custom field is fully deleted.
Intended to be called immediately after delete() to know when the field has been fully removed from the platform.
Parameters
timeout floatMaximum time, in seconds, to wait. Most fields are deleted well within the default; raise this value if you observe legitimate timeouts.
poll_interval intSeconds to sleep between polls.
Raises
The field is in a state from which it will not progress to deleted (Ready, Creating, or Failed). Call delete() first.
The field is still Deleting after timeout seconds.
Return type
Usage
field.delete()
field.wait_to_be_deleted()CustomField.wait_to_be_ready()
Block until this custom field reaches the Ready state.
Intended to be called immediately after create() to know when the field is usable for setting values and querying.
Parameters
timeout floatMaximum time, in seconds, to wait. Most fields reach Ready well within the default; raise this value if you observe legitimate timeouts.
poll_interval intSeconds to sleep between polls.
Raises
The field is in a state from which it cannot reach Ready (Failed or Deleting), or it was deleted while waiting.
The field is still Creating after timeout seconds.
Return type
Usage
field = CustomField.create(
field_name="flight_id",
field_type=CustomFieldType.String,
entity_type=TargetEntityType.Dataset,
)
field.wait_to_be_ready()
field.status
# <CustomFieldStatus.Ready: 'ready'>