roboto.domain.custom_fields
Submodules
Package Contents
CUSTOM_FIELD_NAME_PATTERN
Regular expression describing the format of a valid custom-field name.
A custom-field name is at most 63 characters long, starts with a lowercase ASCII letter, and may otherwise contain lowercase ASCII letters, digits, and underscores.
Unanchored, for embedding in a larger pattern; wrap as ^{...}$ to match a whole field name.
CreateCustomFieldRequest
Bases: pydantic.BaseModel
Request body for POST /v1/custom-fields.
Defines a new custom field for an entity type in the caller’s organization. Normally constructed by create() rather than instantiated directly.
Parameters
data AnyCreateCustomFieldRequest.check_options_match_field_type()
Return type
Attributes
CreateCustomFieldRequest.description
Long-form description of the field’s meaning.
Surrounding whitespace is removed. Text that is empty once stripped counts as unset.
CreateCustomFieldRequest.display_name
Human-readable label shown in the UI.
Surrounding whitespace is removed. Text that is empty once stripped counts as unset.
CreateCustomFieldRequest.entity_type
Roboto entity type the field extends.
CreateCustomFieldRequest.field_name
Name of the field. Fixed at creation time.
Must match ^[a-z][a-z0-9_]{0,62}$ (lowercase ASCII, max 63 chars) and is unique within (org_id, entity_type).
CreateCustomFieldRequest.field_type
Value type of the field.
Determines which operators are supported in search and sort.
CreateCustomFieldRequest.metadata_path
Reserved for promoting an existing metadata key into a custom field.
Not yet supported; leave as None. Supplying a value is rejected.
CreateCustomFieldRequest.options
Type-specific configuration.
Required for CustomFieldType.Enum fields (to declare the allowed values).
Enum values are tidied before they are stored: each is normalized to Unicode NFC, surrounding whitespace is removed, internal runs of whitespace become a single space, and values that repeat after that are deduplicated. A field may declare at most 250 distinct values, each at most 256 characters long as supplied, not counting surrounding whitespace.
A value is rejected if it is blank, or if it contains a control character, a double quote, or a backslash: a value carrying one of those cannot be relied on to work in search.
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'>CustomFieldOptions
Type-specific configuration carried alongside a custom field. Currently only EnumFieldOptions.
CustomFieldRecord
Bases: pydantic.BaseModel
Wire-transmissible representation of a CustomField.
Returned by the custom-fields API and wrapped by CustomField for ergonomic access. Callers normally interact with the wrapping class rather than this record directly.
Parameters
data AnyAttributes
CustomFieldRecord.attempts
Number of attempts the platform has made for the field’s current lifecycle phase.
Diagnostic; not actionable for callers.
CustomFieldRecord.description
Long-form description of the field’s meaning, or None if unset.
CustomFieldRecord.display_name
Human-readable label for the field, or None if unset.
CustomFieldRecord.field_name
Name of the field. Unique within (org_id, entity_type) and fixed at creation time.
CustomFieldRecord.field_type
Value type of the field. Fixed at creation time.
CustomFieldRecord.last_error
Human-readable summary of the most recent failure, if any.
Populated when status is CustomFieldStatus.Failed, and may stay set after a retry until the next failure or success.
CustomFieldRecord.metadata_path
Source metadata key the field was promoted from, if any. Reserved for future use.
CustomFieldRecord.modified
Timestamp of the field’s most recent status or metadata change.
CustomFieldRecord.modified_by
User ID of the most recent modifier. May be a system identity for automatic status changes.
CustomFieldRecord.options
Type-specific configuration.
Present for CustomFieldType.Enum fields; None for types that take no options.
CustomFieldStatus
Bases: roboto.compat.StrEnum
Lifecycle state of a CustomField.
The status tells a caller what they can do with the field right now. See the CustomField class docstring for the full lifecycle narrative.
Attributes
CustomFieldStatus.Creating
The field is being set up.
Values cannot yet be assigned to entities, and the field cannot be referenced in search or sort.
CustomFieldStatus.Deleting
The field is on its way out. Callers should treat it as already gone.
CustomFieldStatus.Failed
The most recent create or delete attempt did not succeed.
The field stays in this state until an operator intervenes. A field that failed during creation can normally be deleted, however.
CustomFieldStatus.Ready
The field is fully available.
Values can be set on entities and the field can be used in search filters and as a sort key.
CustomFieldType
Bases: roboto.compat.StrEnum
Value type of a custom field.
A field’s type is fixed at creation time and determines which operators are supported in search and sort, as well as which Python types can be assigned as values.
Attributes
CustomFieldType.Enum
A string value drawn from a fixed set of allowed values.
The allowed values are declared at creation time via EnumFieldOptions. Supports equality and membership filtering, plus sort.
CustomFieldType.Number
A numeric value. Supports equality, range filtering, and sort.
CustomFieldType.String
A free-form string value. Supports equality, substring, and sort.
CustomFieldType.Timestamp
A point in time. Supports equality, range filtering, and sort.
Values may be given as a datetime, an ISO 8601 string, an int of nanoseconds since the Unix epoch, or a float, decimal.Decimal or numeric string of seconds since it. A string is read as seconds whenever it parses as a number, so the all-digit date 20260101 names a moment in 1970 rather than a day in 2026.
A value carrying no time zone, whether a naive datetime or an ISO 8601 string with no offset, is read as UTC; a date with no time, such as 2026-05-14, resolves to midnight UTC. Sub-microsecond precision is not retained.
Values are returned as ISO 8601 strings, which datetime.datetime.fromisoformat parses.
EnumFieldOptions
Bases: pydantic.BaseModel
Configuration for an CustomFieldType.Enum custom field.
Declares the set of values an enum field will accept. Required when creating an enum field; unused for other field types.
Parameters
data AnyAttributes
EnumFieldOptions.enum_values
Allowed values for the field. Must contain at least one value.
EnumFieldOptions.field_type
Discriminator that identifies this options payload as belonging to an enum field.
ListCustomFieldsRequest
Bases: pydantic.BaseModel
Request body for POST /v1/custom-fields/query.
Pages through the custom fields visible to the caller, optionally filtered by entity type and status. Normally constructed by list() rather than directly.
Parameters
data AnyAttributes
ListCustomFieldsRequest.entity_type
If provided, restrict results to fields targeting this entity type.
ListCustomFieldsRequest.page_token
Opaque token returned by a prior page; omit on the first request.
ListCustomFieldsRequest.statuses
Statuses to include in the results. Must contain at least one status.
TargetEntityType
Bases: roboto.compat.StrEnum
Roboto entity type that a custom field extends.
Each custom field is scoped to exactly one entity type, and a given field_name is unique within an (org_id, entity_type) pair.
Attributes
Properties
TargetEntityType.url_safe_value
URL-encoded form of this entity type’s value, suitable for embedding in a path segment.
UpdateCustomFieldRequest
Bases: pydantic.BaseModel
Request body for POST /v1/custom-fields/{field_id}.
Carries mutable metadata changes for an existing custom field. Each request attribute defaults to NotSet, which leaves the corresponding attribute unchanged; pass None explicitly to clear an attribute.
Parameters
data AnyAttributes
UpdateCustomFieldRequest.description
New description for the field, or None to clear it.
Leave as NotSet to leave unchanged. Surrounding whitespace is removed, and text that is empty once stripped clears the attribute.
UpdateCustomFieldRequest.display_name
New display name for the field, or None to clear it.
Leave as NotSet to leave unchanged. Surrounding whitespace is removed, and text that is empty once stripped clears the attribute.
UpdateCustomFieldRequest.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
UpdateCustomFieldRequest.options
Replacement type-specific configuration for the field.
Leave as NotSet to leave unchanged. Must be for the field’s field_type. For an enum field, the new enum_values must include every existing value: values can be added but not removed. Values are tidied and capped exactly as they are at creation. A value that repeats an earlier one in enum_values, once tidied, is discarded rather than rejected, so re-sending a value the field already has changes nothing and raises nothing.