Airtable

Overview

The Airtable class allows you to interact with an Airtable base. In order to use this class you must generate an Airtable personal access token which can be found in your Airtable settings.

Note

Finding The Base Key

The easiest place to find the base_key for the base that you wish to interact with is via the Airtable API documentation.

  • Go to the Airtable API Base List and select the base.

  • The url of the resulting page will contain the base_key.

  • Example: https://airtable.com/[BASE_KEY]/api/docs#curl/introduction

QuickStart

To instantiate the Airtable class, you can either store your Airtable personal access token AIRTABLE_PERSONAL_ACCESS_TOKEN as an environmental variable or pass in your personal access token as an argument. You also need to pass in the base key and table name.

from parsons import Airtable

# First approach: Use personal access token via environmental variable and pass
# the base key and the table as arguments.
at = Airtable(base_key, 'table01')

# Second approach: Pass personal access token, base key and table name as arguments.
at = Airtable(base_key, 'table01', personal_access_token='MYFAKETOKEN')

You can then call various endpoints:

# Get records from a base
at.get_records(fields=['id', 'fn', 'ln'])

# Get a single record from a base
at.get_record(1233)

# Insert records
tbl.from_csv('my_new_records')
at.insert_records(tbl)

API

class parsons.Airtable(base_key, table_name, personal_access_token=None)[source]
Args:
base_key: str

The key/ID of the Airtable base that you will interact with, typically prefixed with app.

table_name: str

The name or key/ID of the table in the base. The table name is the equivalent of the sheet name in Excel or GoogleDocs. The ID can be found in the URL and is typically prefixed with tbl.

personal_access_token: str

The Airtable personal access token. Not required if AIRTABLE_PERSONAL_ACCESS_TOKEN env variable set.

get_record(record_id)[source]

Returns a single record.

Args:
record_id: str

The Airtable record id

Returns:

A dictionary of the record

get_records(fields=None, max_records=None, view=None, formula=None, sort=None, sample_size=None)[source]
Args:
fields: str or lst

Only return specified column or list of columns. The column name is case sensitive

max_records: int

The maximum total number of records that will be returned.

view: str

If set, only the records in that view will be returned. The records will be sorted according to the order of the view.

formula: str

The formula will be evaluated for each record, and if the result is not 0, false, “”, NaN, [], or #Error! the record will be included in the response.

If combined with view, only records in that view which satisfy the formula will be returned. For example, to only include records where COLUMN_A isn’t empty, pass in: "NOT({COLUMN_A}='')"

For more information see Airtable Docs on formulas.

Usage - Text Column is not empty:

airtable.get_all(formula="NOT({COLUMN_A}='')")

Usage - Text Column contains:

airtable.get_all(formula="FIND('SomeSubText', {COLUMN_STR})=1")

sort: str or lst

Specifies how the records will be ordered. If you set the view parameter, the returned records in that view will be sorted by these fields. If sorting by multiple columns, column names can be passed as a list. Sorting Direction is ascending by default, but can be reversed by prefixing the column name with a minus sign -.

Example usage: airtable.get_records(sort=['ColumnA', '-ColumnB'])

sample_size: int

Number of rows to sample before determining columns

Returns:
Parsons Table

See Parsons Table for output options.

insert_record(row, typecast=False)[source]

Insert a single record into an Airtable.

Args:
row: dict

Fields to insert. Must be dictionary with Column names as Key.

typecast: boolean

Automatic data conversion from string values.

Returns:

Dictionary of inserted row

insert_records(table, typecast=False)[source]

Insert multiple records into an Airtable. The columns in your Parsons table must exist in the Airtable. The method will attempt to map based on column name, so the order of the columns is irrelevant.

Args:
table: A Parsons Table or list of dicts

Insert a Parsons table or list

typecast: boolean

Automatic data conversion from string values.

Returns:

List of dictionaries of inserted rows

update_record(record_id, fields, typecast=False, replace=False)[source]

Updates a record by its record id. Only Fields passed are updated, the rest are left as is.

Args:
record_id: str

The Airtable record id

fields: dict

Fields to insert. Must be dictionary with Column names as Key.

typecast: boolean

Automatic data conversion from string values.

replace: boolean

Only provided fields are updated. If True, record is replaced in its entirety by provided fields; if a field is not included its value will bet set to null.

Returns:

Dictionary of updated row

update_records(table, typecast=False, replace=False)[source]

Update multiple records into an Airtable. The columns in your Parsons table must exist in the Airtable, and the record id column must be present. The method will attempt to map based on column name, so the order of the columns is irrelevant.

Args:
table: A Parsons Table or list of dicts

Insert a Parsons table or list. Record must contain the record id column and columns containing the fields to update

typecast: boolean

Automatic data conversion from string values.

replace: boolean

Only provided fields are updated. If True, record is replaced in its entirety by provided fields; if a field is not included its value will bet set to null.

Returns:

List of dicts of updated records

upsert_records(table, key_fields=None, typecast=False, replace=False)[source]

Update and/or create records, either using id (if included) or using a set of fields (key_fields) to look for matches. The columns in your Parsons table must exist in the Airtable. The method will attempt to map based on column name, so the order of the columns is irrelevant.

Args:
table: A Parsons Table or list of dicts

Parsons table or list with records to upsert. Records must contain the record id column or the column(s) defined in key_fields.

key_fields: list of str

List of field names that Airtable should use to match records in the input with existing records.

typecast: boolean

Automatic data conversion from string values.

replace: boolean

Only provided fields are updated. If True, record is replaced in its entirety by provided fields; if a field is not included its value will bet set to null.

Returns:
Dictionary containing:
  • updated_records: list of updated record `id`s

  • created_records: list of created records `id`s

  • records: list of records

delete_record(record_id)[source]

Deletes a record by its record id.

Args:
record_id: str

The Airtable record id

Returns:

Dictionary of record id and deleted status

delete_records(table)[source]

Delete multiple records from an Airtable.

Args:

table: A Parsons Table or list containing the record `id`s to delete.

Returns:

List of dicts with record id and deleted status