Generador de upsert

Upsert en Airtable: PATCH /records with performUpsert

Nombra tu tabla, clave y columnas y obtén la sentencia que Airtable acepta de verdad, con una guarda para que una fila antigua nunca sobrescriba una nueva. Debajo: cómo funciona la mecánica, qué se rompe y cómo Datrise carga Airtable de forma incremental.

Las notas técnicas de esta página están en inglés.

Genera la sentencia

Sentencia · PATCH /records with performUpsert

// PATCH https://api.airtable.com/v0/{baseId}/deals
// Authorization: Bearer {personal access token}
{
  "performUpsert": {
    "fieldsToMergeOn": ["id"]
  },
  "records": [
    {
      "fields": {
        "id": "…",
        "name": "…",
        "stage": "…",
        "amount": "…",
        "owner_id": "…",
        "updated_at": "…"
      }
    }
  ]
}

Cómo funciona el upsert en Airtable

Airtable's REST API supports upserts directly: a PATCH to the records endpoint with performUpsert.fieldsToMergeOn matches incoming records to existing ones on up to three fields and updates or creates them. The response separates createdRecords from updatedRecords, which is the only way to tell an insert from an update. Fields you do not send are left alone with PATCH and cleared with PUT.

The limits shape the loader. Ten records per request and five requests per second per base means a 5,000-row entity takes 500 requests over at least 100 seconds, so send batches sequentially and back off on HTTP 429. The merge fields must identify one record; if two existing records match, the request fails rather than choosing. Land a focused field set, because bases also cap total records.

Antes de ejecutarla

fieldsToMergeOn takes up to three fields and they must uniquely identify a record; when more than one existing record matches, the request fails rather than picking one.
Each request carries at most 10 records and each base allows 5 requests per second. A 5,000-row sync is 500 requests over at least 100 seconds; send them sequentially with backoff on HTTP 429.
The response lists createdRecords and updatedRecords ids separately, which is the only way to tell an insert from an update; a PATCH leaves unlisted fields untouched, a PUT clears them.

Preguntas frecuentes

Which fields can I merge on?

Up to three fields whose combination is unique in the table, typically the source record id stored in a single-line text field. Linked-record and formula fields cannot be merge fields.

How fast can I sync?

Five requests per second per base, ten records each, so about 50 records per second at best. Exceeding it returns 429 and a short lockout; throttle client-side.

PATCH or PUT?

PATCH for syncs: it updates the listed fields and leaves others untouched. PUT rewrites the record and blanks any field you omit, including ones people edit by hand in the base.

El mismo generador para otros destinos

Sáltate escribir el merge

Datrise aterriza entidades de CRM y SaaS en Airtable con esta misma mecánica, una marca de agua sobre updated-at y columnas tipadas, así que la sentencia de arriba es la que corre por ti. Únete a la lista de espera para acceso anticipado.

Explorar el catálogo de integraciones