Field

The Field class represents a field definition on a table. It is available as a global in all script actions — no import is needed.

Fields should be created via the Field.load_from_data() factory method, which returns the correct subclass (e.g. StringField, IntegerField, ChoiceField) based on the field_type_name parameter.

Factory Method

field = Field.load_from_data(
    name="field_name",
    label="Field Label",
    field_type_name="String",
)

Parameters

Parameter	Type	Required	Default	Description
`name`	str	Yes	—	The field's internal name (used as the key in `record.data`).
`label`	str	No	`None`	Human-readable display label.
`description`	str	No	`None`	Help text describing the field.
`field_type_name`	str	No	`None`	The field type. Defaults to `"String"` if not matched. See Field Types below.
`is_primary_key`	bool	No	`False`	Whether this is the table's primary key field.
`is_display_field`	bool	No	`False`	Whether this field is used as the record's display label.
`readable`	bool	No	`True`	Whether this field can be read from the API.
`creatable`	bool	No	`True`	Whether this field can be set when creating a record.
`updatable`	bool	No	`True`	Whether this field can be set when updating a record.
`queryable`	bool	No	`True`	Whether this field can be used in filter queries.
`required_on_create`	bool	No	`False`	Whether this field is mandatory for insert operations.
`required_on_update`	bool	No	`False`	Whether this field is mandatory for update operations.
`calculated`	bool	No	`False`	Whether this is a server-computed/read-only field.
`allow_conversion_to_choice_field`	bool	No	`True`	Whether this field may be converted to a ChoiceField when choice metadata is discovered.
`context`	dict \| None	No	`None`	Raw API metadata to preserve for debugging or downstream use. Defaults to an empty dict at runtime when omitted.
`custom_types`	dict[str, FieldTypes]	No	`None`	Optional mapping of custom type names to FieldType enum values.

Field Types

The field_type_name parameter determines which Field subclass is created:

Type Name	Subclass	Sample Value	Notes
`"String"`	StringField	`"string"`	Has optional `max_length` attribute.
`"Integer"`	IntegerField	`1`
`"Numeric"`	NumericField	`1.5`	For decimal/float values.
`"Boolean"`	BooleanField	`True`
`"Date"`	DateField	`date.today()`
`"DateTime"`	DateTimeField	`datetime.now()`
`"Time"`	TimeField	`time(12, 0)`
`"Duration"`	DurationField	`timedelta(hours=1)`
`"Reference"`	ReferenceField	`"reference"`	Has `reference_to` (str) for the target table name.
`"Choice"`	ChoiceField	`"choice"`	Has `values` (list[str]) and optional `labels` (list[str]).
`"List"`	ListField	`["a", "b"]`	Has optional `reference_to`.
`"Currency"`	CurrencyField	`"£10.00"`
`"Other"`	OtherField	`"other"`	Fallback for unrecognised types.

If field_type_name doesn't match any known type, StringField is used as the default.

Properties

All fields share these base properties:

Property	Type	Default	Description
`type_name`	str	—	The type discriminator (e.g. `"String"`, `"Integer"`).
`name`	str	—	Internal field name.
`label`	str \| None	`None`	Display label.
`description`	str \| None	`None`	Help text.
`default`	Any \| None	`None`	Default value for the field.
`required_on_create`	bool	`False`	Mandatory for inserts.
`required_on_update`	bool	`False`	Mandatory for updates.
`readable`	bool	`True`	Can be read.
`creatable`	bool	`True`	Can be set on create.
`updatable`	bool	`True`	Can be set on update.
`queryable`	bool	`True`	Can be filtered on.
`calculated`	bool	`False`	Server-computed field.
`is_primary_key`	bool	`False`	Primary key field.
`is_display_field`	bool	`False`	Display/label field.
`allow_conversion_to_choice_field`	bool	`True`	Eligible for choice detection.
`context`	dict	`{}`	Preserved API metadata.

Common Patterns

Basic field metadata extraction

fields = {}
for item in api_response:
    field = Field.load_from_data(
        name=item["name"],
        label=item.get("label"),
        description=item.get("description"),
        field_type_name=item.get("type", "String"),
        is_primary_key=item.get("is_key", False),
        readable=item.get("readable", True),
        creatable=item.get("creatable", True),
        updatable=item.get("updatable", True),
        required_on_create=item.get("required", False),
        context=item,  # preserve raw API metadata
    )
    fields[item["name"]] = field
return fields

Converting a field to a ChoiceField

existing = context.table.fields["status"]
if existing.allow_conversion_to_choice_field:
    choice = Field.load_from_data(
        name=existing.name,
        label=existing.label,
        field_type_name="Choice",
        readable=existing.readable,
        creatable=existing.creatable,
        updatable=existing.updatable,
    )
    choice.values = ["Open", "In Progress", "Closed"]
    choice.labels = ["Open", "In Progress", "Closed"]  # optional
    context.table.fields["status"] = choice