---
title: "Create or update field (upsert)"
method: POST
path: "/tables/fields/{dbId}/{tableId}"
tags: ["Data Dictionary"]
---

# Create or update field (upsert)

`POST /tables/fields/{dbId}/{tableId}`

Create a new field or update an existing field. If field exists, it will be updated. If not, it will be created.

## Path parameters

- `dbId` string, required
- `tableId` string, required

## Request body

- FieldDefinition — Field metadata definition
  - `name` string, required — Field name (required)
  - `label` string — Field label/display name
  - `description` string — Field description
  - `data_type` 'string' | 'integer' | 'float' | 'double' | 'date' | 'boolean' | 'datetime' | 'array' | 'object' | 'null' — Data type (string, integer, float, double, date, boolean, datetime, array, object, null)
  - `column_type` 'dimension' | 'time_period' | 'measure' | 'attribute' | 'indicator_id' | 'indicator_name' | 'geography' | 'observation_value' | 'periodicity' — Semantic column type
  - `field_order` integer — Display order of the field
  - `unit_of_measurement` string — Unit of measurement
  - `format` string — Format specification
  - `time_period_format` string — Time period format (e.g., YYYY, YYYY-MM)
  - `code_list` object[] — Inline code list values
    - `code` union — Code value
      - string
      - number
    - `label` string — Code label
    - `description` string — Code description
  - `code_list_reference` object — External code list reference
    - `id` string — Code list ID
    - `name` string — Code list name
    - `version` string — Code list version
    - `uri` string — Code list URI
    - `note` string — Additional notes
  - `created_at` string, date-time — Creation timestamp
  - `updated_at` string, date-time — Last update timestamp

## Response `200`

successful operation

- object
  - `status` string
  - `field` FieldDefinition — Field metadata definition
    - `name` string, required — Field name (required)
    - `label` string — Field label/display name
    - `description` string — Field description
    - `data_type` 'string' | 'integer' | 'float' | 'double' | 'date' | 'boolean' | 'datetime' | 'array' | 'object' | 'null' — Data type (string, integer, float, double, date, boolean, datetime, array, object, null)
    - `column_type` 'dimension' | 'time_period' | 'measure' | 'attribute' | 'indicator_id' | 'indicator_name' | 'geography' | 'observation_value' | 'periodicity' — Semantic column type
    - `field_order` integer — Display order of the field
    - `unit_of_measurement` string — Unit of measurement
    - `format` string — Format specification
    - `time_period_format` string — Time period format (e.g., YYYY, YYYY-MM)
    - `code_list` object[] — Inline code list values
      - `code` union — Code value
        - string
        - number
      - `label` string — Code label
      - `description` string — Code description
    - `code_list_reference` object — External code list reference
      - `id` string — Code list ID
      - `name` string — Code list name
      - `version` string — Code list version
      - `uri` string — Code list URI
      - `note` string — Additional notes
    - `created_at` string, date-time — Creation timestamp
    - `updated_at` string, date-time — Last update timestamp
  - `action` 'created' | 'updated' — Whether field was created or updated

## Changes

- **2025-12-01** `c9fac12336ea` — 1 info
  - endpoint added
- **2023-12-21** `1451f79c7f04` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/ihsn/apis/data-tables/changes/tables/fields/:dbId/:tableId/post.md)

---

[API](https://skmtc.dev/ihsn/apis/data-tables.md) · [All operations](https://skmtc.dev/ihsn/apis/data-tables/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ihsn/data-tables/revisions/6fb7730a430d/schema)