roboto.domain.custom_fields#

Submodules#

Package Contents#

class roboto.domain.custom_fields.CreateCustomFieldRequest(/, **data)#

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 (Any)

check_options_match_field_type()#
Return type:

CreateCustomFieldRequest

description: FieldDescription | None = None#

Long-form description of the field’s meaning.

display_name: FieldDisplayName | None = None#

Human-readable label shown in the UI.

entity_type: roboto.domain.custom_fields.record.TargetEntityType#

Roboto entity type the field extends.

field_name: Annotated[str, pydantic.StringConstraints(pattern='^[a-z][a-z0-9_]{0,62}$')]#

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).

field_type: roboto.domain.custom_fields.record.CustomFieldType#

Value type of the field.

Determines which operators are supported in search and sort.

metadata_path: str | None = None#

Reserved for promoting an existing metadata key into a custom field.

Not yet supported; leave as None.

options: roboto.domain.custom_fields.record.CustomFieldOptions | None = None#

Type-specific configuration.

Required for CustomFieldType.Enum fields (to declare the allowed values).

class roboto.domain.custom_fields.CustomField(record, roboto_client)#

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 of entity_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:
classmethod create(field_name, field_type, entity_type, display_name=None, description=None, options=None, metadata_path=None, caller_org_id=None, roboto_client=None)#

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 (str) – Name 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.

  • field_type (roboto.domain.custom_fields.record.CustomFieldType) – Value type of the field. Determines which operators are supported in search and sort.

  • entity_type (roboto.domain.custom_fields.record.TargetEntityType) – 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.domain.custom_fields.record.CustomFieldOptions]) – 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.http.RobotoClient]) – 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:

  • RobotoConflictException – A field with this field_name and entity_type already exists in the target org.

  • RobotoInvalidRequestException – 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).

  • RobotoLimitExceededException – The limit on custom field definitions has been reached for the target organization and Roboto entity type.

  • RobotoUnauthorizedException – The caller is not an administrator in the target org.

Return type:

CustomField

Examples

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"]),
... )
property created: datetime.datetime#

UTC timestamp when this field was defined.

Return type:

datetime.datetime

property created_by: str#

User ID that defined this field.

Return type:

str

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:

RobotoUnauthorizedException – The caller lacks permission to delete this field.

Return type:

None

Examples

>>> field = CustomField.from_name_and_entity_type("flight_id", TargetEntityType.Dataset)
>>> field.delete()
>>> field.wait_to_be_deleted()
property description: str | None#

Long-form description of the field’s meaning, or None if unset.

Return type:

Optional[str]

property display_name: str | None#

Human-readable label for the field, or None.

Return type:

Optional[str]

property entity_type: roboto.domain.custom_fields.record.TargetEntityType#

Roboto entity type this field extends.

Return type:

roboto.domain.custom_fields.record.TargetEntityType

property field_id: str#

Opaque, globally unique identifier for this field.

Return type:

str

property field_name: str#

Name of the field, unique within (org_id, entity_type) and fixed at creation time.

Return type:

str

property field_type: roboto.domain.custom_fields.record.CustomFieldType#

Value type of the field. Fixed at creation time.

Return type:

roboto.domain.custom_fields.record.CustomFieldType

classmethod from_id(field_id, roboto_client=None)#

Load an existing custom field by its field_id.

Parameters:

  • field_id (str) – Opaque identifier assigned at create time.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Roboto client instance. Uses the default if omitted.

Returns:

The CustomField with this field_id.

Raises:

RobotoNotFoundException – No field with this field_id is visible to the caller.

Return type:

CustomField

Examples

>>> field = CustomField.from_id("cf_abc123")
>>> field.field_name
'flight_id'
classmethod from_name_and_entity_type(field_name, entity_type, owner_org_id=None, roboto_client=None)#

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:
Returns:

The matching CustomField.

Raises:
Return type:

CustomField

Examples

>>> field = CustomField.from_name_and_entity_type(
...     field_name="flight_id",
...     entity_type=TargetEntityType.Dataset,
... )
property last_error: str | None#

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.

Return type:

Optional[str]

classmethod list(entity_type=None, statuses=None, owner_org_id=None, roboto_client=None)#

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:
Yields:

CustomField instances matching the filters, in pages transparently fetched as the generator is consumed.

Return type:

collections.abc.Generator[CustomField, None, None]

Examples

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)
property metadata_path: str | None#

Source metadata key the field was promoted from, if any. Reserved for future use.

Return type:

Optional[str]

property modified: datetime.datetime#

UTC timestamp of the field’s most recent status or other change.

Return type:

datetime.datetime

property modified_by: str#

User ID of the most recent modifier. May be a system identity for automatic status changes.

Return type:

str

property options: roboto.domain.custom_fields.record.CustomFieldOptions | None#

Type-specific configuration, or None if the field type takes none.

For enum fields this carries the allowed values and is required.

Return type:

Optional[roboto.domain.custom_fields.record.CustomFieldOptions]

property org_id: str#

Organization that owns this field.

Return type:

str

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:

RobotoNotFoundException – The field has been fully deleted.

Return type:

CustomField

Examples

>>> field.refresh().status
<CustomFieldStatus.Ready: 'ready'>
property status: roboto.domain.custom_fields.record.CustomFieldStatus#

Current lifecycle status. See the class docstring for the state machine.

Return type:

roboto.domain.custom_fields.record.CustomFieldStatus

update(display_name=NotSet, description=NotSet)#

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:
Returns:

This same CustomField, with its in-memory record replaced by the server’s updated copy.

Raises:
Return type:

CustomField

Examples

>>> field.update(display_name="Flight identifier")

Clear the description:

>>> field.update(description=None)
wait_to_be_deleted(timeout=5 * 60, poll_interval=2)#

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 (float) – Maximum time, in seconds, to wait. Most fields are deleted well within the default; raise this value if you observe legitimate timeouts.

  • poll_interval (int) – Seconds to sleep between polls.

Raises:
Return type:

None

Examples

>>> field.delete()
>>> field.wait_to_be_deleted()
wait_to_be_ready(timeout=5 * 60, poll_interval=2)#

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 (float) – Maximum time, in seconds, to wait. Most fields reach Ready well within the default; raise this value if you observe legitimate timeouts.

  • poll_interval (int) – Seconds to sleep between polls.

Raises:
Return type:

None

Examples

>>> 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'>
type roboto.domain.custom_fields.CustomFieldOptions = Annotated[EnumFieldOptions, pydantic.Field(discriminator='field_type')]#

Type-specific configuration carried alongside a custom field. Currently only EnumFieldOptions.

class roboto.domain.custom_fields.CustomFieldRecord(/, **data)#

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 (Any)

attempts: int = 0#

Number of attempts the platform has made for the field’s current lifecycle phase.

Diagnostic; not actionable for callers.

created: datetime.datetime#

UTC timestamp when the field was defined.

created_by: str#

User ID that defined the field.

description: str | None = None#

Long-form description of the field’s meaning, or None if unset.

display_name: str | None = None#

Human-readable label for the field, ir None if unset.

entity_type: TargetEntityType#

Roboto entity type the field extends.

field_id: str#

Opaque, globally unique identifier for the field.

field_name: str#

Name of the field. Unique within (org_id, entity_type) and fixed at creation time.

field_type: CustomFieldType#

Value type of the field. Fixed at creation time.

last_error: str | None = None#

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.

metadata_path: str | None = None#

Source metadata key the field was promoted from, if any. Reserved for future use.

modified: datetime.datetime#

Timestamp of the field’s most recent status or metadata change.

modified_by: str#

User ID of the most recent modifier. May be a system identity for automatic status changes.

options: CustomFieldOptions | None = None#

Type-specific configuration.

Present for CustomFieldType.Enum fields; None for types that take no options.

org_id: str#

Organization that owns the field.

status: CustomFieldStatus#

Current lifecycle status. See CustomFieldStatus.

class roboto.domain.custom_fields.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.

Creating = 'creating'#

The field is being set up.

Values cannot yet be assigned to entities, and the field cannot be referenced in search or sort.

Deleting = 'deleting'#

The field is on its way out. Callers should treat it as already gone.

Failed = '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.

Ready = '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.

class roboto.domain.custom_fields.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.

Boolean = 'boolean'#

A boolean value. Supports equality filtering.

Enum = '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.

Number = 'number'#

A numeric value. Supports equality, range filtering, and sort.

String = 'string'#

A free-form string value. Supports equality, substring, and sort.

Timestamp = 'timestamp'#

A point in time. Supports equality, range filtering, and sort.

class roboto.domain.custom_fields.EnumFieldOptions(/, **data)#

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 (Any)

enum_values: list[EnumValue] = None#

Allowed values for the field. Must contain at least one value.

field_type: Literal[CustomFieldType]#

Discriminator that identifies this options payload as belonging to an enum field.

class roboto.domain.custom_fields.ListCustomFieldsRequest(/, **data)#

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 (Any)

entity_type: roboto.domain.custom_fields.record.TargetEntityType | None = None#

If provided, restrict results to fields targeting this entity type.

page_token: str | None = None#

Opaque token returned by a prior page; omit on the first request.

statuses: list[roboto.domain.custom_fields.record.CustomFieldStatus] = None#

Statuses to include in the results. Must contain at least one status.

class roboto.domain.custom_fields.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.

Collection = 'collection'#

Field applies to Collection entities.

Dataset = 'dataset'#

Field applies to Dataset entities.

Device = 'device'#

Field applies to Device entities.

Event = 'event'#

Field applies to Event entities.

Session = 'session'#

Field applies to Session entities.

property url_safe_value: str#

URL-encoded form of this entity type’s value, suitable for embedding in a path segment.

Return type:

str

class roboto.domain.custom_fields.UpdateCustomFieldRequest(/, **data)#

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 (Any)

description: FieldDescription | None | roboto.sentinels.NotSetType#

New description for the field, or None to clear it.

Leave as NotSet to leave unchanged.

display_name: FieldDisplayName | None | roboto.sentinels.NotSetType#

New display name for the field, or None to clear it.

Leave as NotSet to leave unchanged.

model_config#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

On this page