|
| 1 | +# Airtable |
| 2 | + |
| 3 | +This connector captures data from Airtable into Flow collections. |
| 4 | + |
| 5 | +It is available for use in the Flow web application. For local development or open-source workflows, [`ghcr.io/estuary/source-airtable-native:dev`](https://ghcr.io/estuary/source-airtable-native:dev) provides the latest version of the connector as a Docker image. You can also follow the link in your browser to see past image versions. |
| 6 | + |
| 7 | +## Supported data resources |
| 8 | + |
| 9 | +This connector captures data from accessible bases and tables in an Airtable account. All available tables will appear after connecting to Airtable. |
| 10 | + |
| 11 | +Resources are named using the pattern `{base_name}/{table_name}/{table_id}`. |
| 12 | + |
| 13 | +:::info |
| 14 | + |
| 15 | +If you rename a base or table in Airtable, the connector treats the renamed resource as a new resource. The connector stops populating collections under the old name and begins populating new collections with the updated name. |
| 16 | + |
| 17 | +::: |
| 18 | + |
| 19 | +## Prerequisites |
| 20 | + |
| 21 | +### Authentication |
| 22 | + |
| 23 | +Capturing data from Airtable requires an active Airtable account and an [access token](https://airtable.com/developers/web/guides/personal-access-tokens#creating-a-token). |
| 24 | + |
| 25 | +### Setup |
| 26 | + |
| 27 | +To create an access token, do the following: |
| 28 | + |
| 29 | +1. Log into your Airtable account. |
| 30 | +2. In the navigation bar, click on "Builder Hub". |
| 31 | +3. In the "Developers" section, click on "Personal access tokens". |
| 32 | +4. Click on "Create token". |
| 33 | +5. Give your token a name and add the following scopes: |
| 34 | + - `data.records:read` |
| 35 | + - `data.recordComments:read` |
| 36 | + - `schema.bases:read` |
| 37 | +6. Under the "Access" section, choose the bases you want to capture data from. |
| 38 | +7. Click on "Create token". |
| 39 | +8. Copy the token for use in the connector configuration. |
| 40 | + |
| 41 | +## Configuration |
| 42 | + |
| 43 | +You configure connectors either in the Flow web app, or by directly editing the catalog specification file. |
| 44 | +See [connectors](../../../concepts/connectors.md#using-connectors) to learn more about using connectors. The values and specification sample below provide configuration details specific to the Airtable source connector. |
| 45 | + |
| 46 | +### Properties |
| 47 | + |
| 48 | +#### Endpoint |
| 49 | + |
| 50 | +| Property | Title | Description | Type | Required/Default | |
| 51 | +|---|---|---|---|---| |
| 52 | +| **`/credentials/access_token`** | Access Token | The Airtable access token. | string | Required | |
| 53 | +| **`/credentials/credentials_title`** | Authentication Method | Name of the credentials set. Set to `Private App Credentials`. | string | Required | |
| 54 | + |
| 55 | +#### Bindings |
| 56 | + |
| 57 | +| Property | Title | Description | Type | Required/Default | |
| 58 | +|---|---|---|---|---| |
| 59 | +| **`/name`** | Data resource | Name of the data resource. | string | Required | |
| 60 | +| `/interval` | Interval | Interval between data syncs | string | | |
| 61 | +| `/schedule` | Formula Field Refresh Schedule | The schedule for refreshing this binding's [formula fields](#formula-fields). Accepts a cron expression. For example, a schedule of `55 23 * * *` means the binding will refresh formula fields at 23:55 UTC every day. If left empty, the binding will not refresh formula fields. | string | 55 23 * * * | |
| 62 | + |
| 63 | +### Sample |
| 64 | + |
| 65 | +```yaml |
| 66 | +captures: |
| 67 | + ${PREFIX}/${CAPTURE_NAME}: |
| 68 | + endpoint: |
| 69 | + connector: |
| 70 | + image: ghcr.io/estuary/source-airtable-native:dev |
| 71 | + config: |
| 72 | + credentials: |
| 73 | + credentials_title: Private App Credentials |
| 74 | + access_token: <secret> |
| 75 | + bindings: |
| 76 | + - resource: |
| 77 | + name: base_name/table_name/table_id |
| 78 | + target: ${PREFIX}/base_name/table_name/table_id |
| 79 | + {...} |
| 80 | +``` |
| 81 | + |
| 82 | +## Incremental Replication |
| 83 | + |
| 84 | +Tables that include a `lastModifiedTime` field are replicated incrementally, meaning only new and updated records are captured after the initial sync. Tables without this field are replicated using full refreshes, where all records are fetched on every sync. |
| 85 | + |
| 86 | +To enable incremental replication for a table, add a `lastModifiedTime` field: |
| 87 | + |
| 88 | +1. Click the **+** icon (Add field) in your table. |
| 89 | +2. Select **Last modified time** as the field type. |
| 90 | +3. Enter a name for the field. |
| 91 | +4. In the **Fields** section, select **All editable fields**. |
| 92 | +5. In the **Formatting** section, select **Include time**. |
| 93 | +6. Click **Create field**. |
| 94 | + |
| 95 | + |
| 96 | + |
| 97 | +## Formula Fields |
| 98 | + |
| 99 | +Airtable tables can contain [formula fields](https://support.airtable.com/docs/formula-field-overview), fields whose values are calculated at query time. Formula field updates do not cause `lastModifiedTime` fields to change. Since the connector uses `lastModifiedTime` fields to incrementally detect changes, formula field updates are not incrementally captured. |
| 100 | + |
| 101 | +To address this challenge, the Airtable connector is able to refresh the values of formula fields on a schedule after the initial backfill completes. This is controlled at a binding level by the cron expression in the [`schedule` property](#bindings). When a scheduled formula field refresh occurs, the connector fetches every record's current formula field values and merges them into the associated collection using [`merge` reduction strategies](/reference/reduction-strategies/merge). |
| 102 | + |
| 103 | +### Formula Field Errors |
| 104 | + |
| 105 | +The connector omits formula fields containing [error codes](https://support.airtable.com/docs/common-formula-errors-and-how-to-fix-them) to avoid schema evolution that would widen column types in downstream materializations. |
0 commit comments