Skip to content

🔦 Feature: Add use_field_id parameter support for data retrieval (GET requests) #12716

@z00rd

Description

@z00rd

Please confirm that the feature request does not already exist

  • I confirm there is no existing issue for this feature request.

Use case

Issue #11179 introduced the use_field_id parameter for record creation (POST/PATCH), allowing users to reference fields by their stable IDs instead of field names. This is valuable for
building robust integrations that don't break when field names are changed in the UI.

However, data retrieval endpoints (GET) still return field names as keys in the response. This creates an inconsistency:

  • INSERT/UPDATE: Can use field IDs (c_abc123) via use_field_id=true
  • SELECT/GET: Always returns field names ("Customer Name", "Status")

For ETL pipelines and data integrations, we need the same stability on the read side. When field names change, all downstream code that parses the response breaks. Using field IDs in both
directions would ensure field renames are non-breaking changes.

Suggested solution

Extend the use_field_id query parameter to GET endpoints:

GET /api/v3/data/{base_id}/{table_id}/records?use_field_id=true

Current response (always):

  {
    "records": [
      {
        "id": 1,
        "fields": {
          "Customer Name": "ACME Corp",
          "Status": "Active",
          "Order Date": "2025-12-03"
        }
      }
    ]
  }

Proposed response (with use_field_id=true):

  {
    "records": [
      {
        "id": 1,
        "fields": {
          "c_abc123": "ACME Corp",
          "c_def456": "Active",
          "c_ghi789": "2025-12-03"
        }
      }
    ]
  }

This maintains API consistency with the existing POST/PATCH behavior from #11179 and provides the same stability benefits for data consumers.

Additional context

Scenario:

  1. ETL pipeline creates records using field IDs (via 🔦 Feature: [v3] Support API based record creation using field ID instead of filed name #11179) ✅
  2. ETL pipeline reads records to validate/transform data ❌ (receives field names)
  3. Field name changes in UI
  4. Write operations continue working ✅
  5. Read operations break ❌

Real-world impact:

  • Data pipelines that map Airtable/NocoDB → BigQuery/Snowflake break on every field rename
  • Requires maintaining manual mapping layers (field name → internal schema)
  • Inconsistent API behavior between write and read operations

Version tested: 0.265.1 (self-hosted open-source)

Related: #11179 (completed - write operations only)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions