Skip to contents

Write (create) records in an Airtable table

Source: R/air_write.R
air_write.Rd

Converts a data frame into records and creates them in the specified table. Automatically batches in groups of 10. Computed fields (formulas, rollups, autoNumber, createdTime, lastModifiedTime, etc.) and attachment fields are automatically excluded from the upload payload. When attachments is "file" or "blob", attachment content is uploaded separately after record creation using the dedicated upload endpoint.

Usage

air_write(
  data,
  table,
  base_id = NULL,
  typecast = TRUE,
  add_fields = c("error", "warn", "yes"),
  attachments = c("meta", "file", "blob"),
  attachment_dir = NULL,
  progress = NULL,
  .token = NULL
)

Arguments

data

A data frame of records to create. Should not contain airtable_id (those would be ignored). Computed field columns and attachment field columns are silently dropped from the record payload.

table

Table name or ID.

base_id

Base ID (e.g., "appXXXXXX"). If NULL, uses the session default set by air_set_base() or the AIRTABLE_BASE_ID environment variable.

typecast

If TRUE (default), Airtable will attempt to coerce values to match field types.

add_fields

What to do when data contains columns not in the table:

  • "error" (default): error if unknown columns exist.

  • "warn": warn and drop unknown columns.

  • "yes": create missing fields before writing (as singleLineText).

attachments

How to handle attachment fields: "meta" (default) keeps only metadata (filename, url, size, type); "file" downloads to attachment_dir; "blob" downloads as in-memory raw vectors.

attachment_dir

Directory for downloading attachments (required when attachments = "file"). Files are saved as {attachment_dir}/{record_id}/{filename}.

progress

Logical or NULL. If TRUE, shows a cli progress bar for paginated requests. If NULL (default), uses option airtable2.progress.bar or env var AIRTABLE2_PROGRESS_BAR.

.token

Personal access token (resolved via air_token() if NULL).

Value

A character vector of the created record IDs (invisibly).

Examples

if (FALSE) { # \dontrun{
data <- data.frame(Name = c("Alice", "Bob"), Age = c(30, 25))
ids <- air_write(data, "Contacts", "appXXXXXX")

# Write records and upload attachments from list-column
ids <- air_write(data, "Projects", "appXXXXXX",
  attachments = "file",
  attachment_dir = "files/"
)

# Write records and add new columns if they don't exist
ids <- air_write(data, "Contacts", "appXXXXXX", add_fields = "yes")
} # }