ORM

New in version 1.0.0.

Warning

This feature is experimental. Feel free to submit suggestions or feedback in our Github repo

Model

The Model class allows you create an orm-style class for your Airtable tables.

>>> from pyairtable.orm import Model, fields
>>> class Contact(Model):
...     first_name = fields.TextField("First Name")
...     last_name = fields.TextField("Last Name")
...     email = fields.EmailField("Email")
...     is_registered = fields.CheckboxField("Registered")
...     partner = fields.LinkField("Partner", "Contact", lazy=False)
...
...     class Meta:
...         base_id = "appaPqizdsNHDvlEm"
...         table_name = "Contact"
...         api_key = "keyapikey"

Once you have a class, you can create new objects to represent your Airtable records. Call save() to create a new record.

>>> contact = Contact(
...     first_name="Mike",
...     last_name="McDonalds",
...     email="mike@mcd.com",
...     is_registered=False
... )
...
>>> assert contact.id is None
>>> contact.exists()
False
>>> assert contact.save()
>>> contact.exists()
True
>>> contact.id
rec123asa23

You can read and modify attributes. If record already exists, save() will update the record:

>>> assert contact.is_registered is False
>>> contact.save()
>>> assert contact.is_registered is True
>>> contact.to_record()
{
    "id": recS6qSLw0OCA6Xul",
    "createdTime": "2021-07-14T06:42:37.000Z",
    "fields": {
        "First Name": "Mike",
        "Last Name": "McDonalds",
        "Email": "mike@mcd.com",
        "Resgistered": True
    }
}

Finally, you can use delete() to delete the record:

>>> contact.delete()
True
class pyairtable.orm.model.Model(**fields)[source]

This class allows you create an orm-style class for your Airtable tables.

This is a meta class and can only be used to define sub-classes.

The Meta is reuired and must specify all three attributes: base_id, table_id, and api_key.

>>> from pyairtable.orm import Model, fields
>>> class Contact(Model):
...     first_name = fields.TextField("First Name")
...     age = fields.IntegerField("Age")
...
...     class Meta:
...         base_id = "appaPqizdsNHDvlEm"
...         table_name = "Contact"
...         api_key = "keyapikey"
...         timeout: Optional[Tuple[int, int]] = (5, 5)
...         typecast: bool = True
classmethod all(**kwargs)[source]

Returns all records for this model. See all()

Return type

List[~T]

created_time: str = ''
delete()[source]

Deleted record. Must have ‘id’ field

Return type

bool

exists()[source]

Returns boolean indicating if instance exists (has ‘id’ attribute)

Return type

bool

fetch()[source]

Fetches field and resets instance field values from the Airtable record

classmethod first(**kwargs)[source]

Returns first record for this model. See first()

Return type

List[~T]

classmethod from_id(record_id, fetch=True)[source]

Create an instance from a record_id

Parameters

record_id (str) – An Airtable record id.

Keyward Args:
fetch: If True, record will be fetched and fields will be

updated. If False, a new instance is created with the provided id, but field values are unset. Default is True.

Returns

Instance of model

Return type

(Model)

classmethod from_record(record)[source]

Create instance from record dictionary

Return type

~T

classmethod get_table()[source]

Return Airtable Table class instance

Return type

Table

id: str = ''
save()[source]

Saves or updates a model. If instance has no ‘id’, it will be created, otherwise updatedself.

Returns True if was created and False if it was updated

Return type

bool

to_record()[source]

Returns a dictionary object as an Airtable record. This method converts internal field values into values expected by Airtable. e.g. a datetime value from :class:DateTimeField is converted into an ISO 8601 string

Return type

dict

Fields

Field are used to define the Airtable column type for your pyAirtable models.

Internally these are implemented as descriptors, this allows us to proxy getting and settings values, while also providing a type-annotated interface.

>>> from pyairtable.orm import Model, fields
>>> class Contact(Model):
...     name = fields.TextField("Name")
...     is_registered = fields.CheckboxField("Registered")
...
...     class Meta:
...         ...
>>> contact = Contact(name="George", is_registered=True)
>>> assert contact.name == "George"
>>> reveal_type(contact.name)  # -> str
>>> contact.to_record()
{
    "id": recS6qSLw0OCA6Xul",
    "createdTime": "2021-07-14T06:42:37.000Z",
    "fields": {
        "Name": "George",
        "Registered": True,
    }
}