> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.

# create_data_table_field

> Add one column to a data table and get the table back as it now stands — with its full field schema, exactly as get_data_table returns it.

Add one column to a data table, and return the table as it now stands.

The column is created empty on every existing record: this sets no values and
no default. It is added to the table's views, to the scopes reading that table
and to the plans' simulation pipelines, so it is available to a compensation
and to a report straight away — load its values by Excel import from the Qobra
web app, or through Qobra's public API.

The table comes back with its full field schema, exactly as
[`get_data_table`](/mcp_documentation/tools/get_data_table) returns it, so
adding several columns in a row needs no read between them.

A column synced from an integration, and a link to another data table, are set
up on the table's page in the Qobra web app instead, not here.

Available only where the Qobra write tools beta is enabled. Every write is
recorded in the audit trail as the `Qobra MCP` agent.

## Parameters

<Accordion title="Body" defaultOpen>
  <ParamField body="data_table_id" type="string" required>
    Id of the data table to add the column to — the id list\_data\_tables
    returns, or the one create\_data\_table just returned. Never a table name.
  </ParamField>

  <ParamField body="name" type="string" required>
    Display name of the column, as people will read it in Qobra — 'Amount',
    'Closing date', 'Owner', 'Stage'.
  </ParamField>

  <ParamField body="variable_type" type="string" required>
    What the column holds. `amount` is monetary and `percentage` a ratio,
    where 0.15 reads as 15%; `float` is a plain number, for a count or a
    quantity. `user` holds a Qobra user, matched on their email when records
    are imported. `picklist` is one choice out of a fixed list and
    `multipicklist` several — both need `options`. A link to another data
    table is not created here. One of: `float`, `amount`, `percentage`,
    `string`, `picklist`, `multipicklist`, `bool`, `date`, `user`.
  </ParamField>

  <ParamField body="key" type="string">
    The column's stable key: the identifier the public API and an Excel
    import address it by, distinct from the display name. Lowercase and
    underscore-separated, and unique within the table. Omit to derive it from
    the name ('Closing date' gives 'closing\_date').
  </ParamField>

  <ParamField body="options" type="string[]">
    The labels people choose from, for a picklist or a multipicklist
    column — required there, and refused on every other type. These exact
    labels are what a record's value is matched on when rows are imported.
  </ParamField>

  <ParamField body="currency_key" type="string">
    For an amount column, the key of the column each row's currency code is
    read from — a sibling field's key on an imported table, a payload key on
    one fed through Qobra's public API. Not a currency code itself, and
    refused on any other type. Omit it to denominate every row in the company
    currency.
  </ParamField>

  <ParamField body="description" type="string">
    Optional free-text note about what the column holds.
  </ParamField>
</Accordion>

## Response

<Accordion title="Body" defaultOpen>
  <ResponseField name="data_table" type="object">
    The data table the column was added to, with its full field schema as
    get\_data\_table returns it — the new column included. Read it to see the
    table as it now stands. See
    [`get_data_table`](/mcp_documentation/tools/get_data_table) for the field
    breakdown.
  </ResponseField>

  <ResponseField name="field" type="object">
    The column just created — which of `data_table.fields` is the new one, so
    its id is at hand without matching on a name.
  </ResponseField>
</Accordion>