Metadata¶

The Airtable API gives you the ability to list all of your bases, tables, fields, and views. pyAirtable allows you to inspect and interact with this metadata in your bases.

There may be parts of the Airtable API which are not supported below; you can always use Api.request to call them directly.

Reading schemas¶

All of the methods below return complex nested data structures, some of which have their own convenience methods for searching their contents, such as TableSchema.field(). You’ll find more detail in the API reference for pyairtable.models.schema.

Api.bases(*, force=False)[source]

Retrieve the base’s schema and return a list of Base instances.

Parameters: force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Usage:

>>> api.bases()
[
    <pyairtable.Base base_id='appSW9...'>,
    <pyairtable.Base base_id='appLkN...'>
]

Return type: List[Base]

Base.schema()[source]

Retrieve the schema of all tables in the base and caches it.

Usage:

>>> base.schema().tables
[TableSchema(...), TableSchema(...), ...]
>>> base.schema().table("tblXXXXXXXXXXXXXX")
TableSchema(id="tblXXXXXXXXXXXXXX", ...)
>>> base.schema().table("My Table")
TableSchema(id="...", name="My Table", ...)

Parameters: force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: BaseSchema

Base.tables(*, force=False)[source]

Retrieve the base’s schema and returns a list of Table instances.

Parameters: force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Usage:

>>> base.tables()
[
    <Table base='appLkN...' id='tbltp8DGLhqbUmjK1' name='Apartments'>,
    <Table base='appLkN...' id='tblK6MZHez0ZvBChZ' name='Districts'>
]

Return type: List[Table]

Table.schema(*, force=False)[source]

Retrieve the schema of the current table.

Usage:

>>> table.schema()
TableSchema(
    id='tblslc6jG0XedVMNx',
    name='My Table',
    primary_field_id='fld6jG0XedVMNxFQW',
    fields=[...],
    views=[...]
)

Parameters: force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: TableSchema

Modifying existing schema¶

To modify a table or field, you can modify its schema object directly and call save(), as shown below. You can only change names and descriptions; the Airtable API does not permit changing any other options.

>>> schema = table.schema()
>>> schema.name = "Renamed"
>>> schema.save()
>>> field = schema.field("Name")
>>> field.name = "Label"
>>> field.description = "The primary field on the table"
>>> field.save()

Creating schema elements¶

The following methods allow creating bases, tables, or fields:

Api.create_base(workspace_id, name, tables)[source]

Create a base in the given workspace.

See https://airtable.com/developers/web/api/create-base

Parameters

workspace_id (str) – The ID of the workspace where the new base will live.
name (str) – The name to give to the new base. Does not need to be unique.
tables (Sequence[Dict[str, Any]]) – A list of dict objects that conform to Airtable’s Table model.

Return type

Base

Workspace.create_base(name, tables)[source]

Create a base in the given workspace.

See https://airtable.com/developers/web/api/create-base

Parameters

name (str) – The name to give to the new base. Does not need to be unique.
tables (Sequence[Dict[str, Any]]) – A list of dict objects that conform to Airtable’s Table model.

Return type

Base

Workspace.move_base(base, target, index=None)[source]

⚠ This feature is only available on Enterprise billing plans.

Move the given base to a new workspace.

See https://airtable.com/developers/web/api/move-base

Usage:

>>> ws = api.workspace("wspmhESAta6clCCwF")
>>> base = api.workspace("appCwFmhESAta6clC")
>>> workspace.move_base(base, "wspSomeOtherPlace", index=0)

Return type: None

Base.create_table(name, fields, description=None)[source]

Create a table in the given base.

Parameters

name (str) – The unique table name.
fields (Sequence[Dict[str, Any]]) – A list of dict objects that conform to the Airtable field model.
description (Optional[str], default: None) – The table description. Must be no longer than 20k characters.

Return type

Table

Table.create_field(name, type, description=None, options=None)[source]

Create a field on the table.

Parameters

name (str) – The unique name of the field.
field_type – One of the Airtable field types.
description (Optional[str], default: None) – A long form description of the table.
options (Optional[Dict[str, Any]], default: None) – Only available for some field types. For more information, read about the Airtable field model.

Return type

Union[AITextFieldSchema, AutoNumberFieldSchema, BarcodeFieldSchema, ButtonFieldSchema, CheckboxFieldSchema, CountFieldSchema, CreatedByFieldSchema, CreatedTimeFieldSchema, CurrencyFieldSchema, DateFieldSchema, DateTimeFieldSchema, DurationFieldSchema, EmailFieldSchema, ExternalSyncSourceFieldSchema, FormulaFieldSchema, LastModifiedByFieldSchema, LastModifiedTimeFieldSchema, MultilineTextFieldSchema, MultipleAttachmentsFieldSchema, MultipleCollaboratorsFieldSchema, MultipleLookupValuesFieldSchema, MultipleRecordLinksFieldSchema, MultipleSelectsFieldSchema, NumberFieldSchema, PercentFieldSchema, PhoneNumberFieldSchema, RatingFieldSchema, RichTextFieldSchema, RollupFieldSchema, SingleCollaboratorFieldSchema, SingleLineTextFieldSchema, SingleSelectFieldSchema, UrlFieldSchema, UnknownFieldSchema]

Deleting schema elements¶

⚠ This feature is only available on Enterprise billing plans.

The Airtable API does not allow deleting tables or fields, but it does allow deleting workspaces, bases, and views. pyAirtable supports the following methods:

To delete a Workspace:

>>> ws = api.workspace("wspmhESAta6clCCwF")
>>> ws.delete()

To delete a Base:

>>> base = api.base("appMxESAta6clCCwF")
>>> base.delete()

To delete a view, first retrieve its ViewSchema:

>>> vw = table.schema().view("View Name")
>>> vw.delete()