Columns¶

Global structure¶

Here is the global structure of a column object:

{
    "key":"bjcM",
    "type":"number",
    "name":"Val",
    "editable":true,
    "width":200,
    "resizable":true,
    "draggable":true,
    "data": // (1)!
        {
            "format":"number",
            "precision":2,
            "enable_precision":false,
            "enable_fill_default_value":false,
            "enable_check_format":false,
            "decimal":"comma",
            "thousands":"no",
            "format_min_value":0,
            "format_max_value":1000
        },
    "permission_type":"",
    "permitted_users":[],
    "permitted_group":[],
    "edit_metadata_permission_type":"",
    "edit_metadata_permitted_users":[],
    "edit_metadata_permitted_group":[],
    "description":null,
    "colorbys":{},
    "editor":
        {
            "key":null,
            "ref":null,
            "props":{},
            "_owner":null
        },
    "formatter":
        {
            "key":null,
            "ref":null,
            "props":{},
            "_owner":null
        }
}

See below for a presentation of data object keys depending on the column type

Columns particularities

Unless other elements, columns don't have an _id, but a key
Link-type columns also have a link id that should not be mistaken with the column key. This value is present in the data object (see below)

Column data¶

The data object keys will depend on the column type and will allow you to define the specific column parameters. Here is a list of the different data keys depending on the column type:

text, email, long-text, image, file, url, creator, ctime, last-modifier, mtime

empty

link

{
    "display_column_key":"qqXZ",
    "table_id":"0000",
    "other_table_id":"XE5U",
    "is_internal_link":true,
    "is_multiple":true,
    "only_adding_new_record":false,
    "is_row_from_view":false,
    "other_view_id":"",
    "link_id":"OSD1",
    "array_type":"text",
    "array_data":null,
    "result_type":"array"
}

number

{
    "format":"custom_currency",
    "precision":2,
    "enable_precision":true,
    "enable_fill_default_value":false,
    "decimal":"comma",
    "thousands":"no",
    "currency_symbol_position":"after",
    "currency_symbol":"p"
}

date

{
    "format":"M/D/YYYY HH:mm"
}

duration

{
    "format":"duration",
    "duration_format":"h:mm"
}

single select, multiple select

{
    "options":
        [
            {
                "name":"Male",
                "id":"783482",
                "color":"#46A1FD",
                "textColor":"#FFFFFF",
                "borderColor":"#3C8FE4"
            },
            {
                "name":"Female",
                "id":"330935",
                "color":"#DC82D2",
                "textColor":"#FFFFFF",
                "borderColor":"#D166C5"
            },
            {
                "name":"Non-binary",
                "id":"147140",
                "color":"#ADDF84",
                "textColor":"#FFFFFF",
                "borderColor":"#9CCF72"
            }
        ],
        "cascade_column_key":"Qvkt",
        "cascade_settings":
            {
                "147140":["783482"],
                "330935":["330935"],
                "783482":["783482"]
            }
}

checkbox

{
    "default_value":false,
    "enable_fill_default_value":false
}

rate

{
    "rate_max_number":5,
    "rate_style_color":"#FF8000",
    "default_value":"",
    "enable_fill_default_value":false
}

formula

{
    "formula":"left({Email},search(\"@\",{Email},1)-1)",
    "operated_columns":["JfP2"],
    "result_type":"string",
    "enable_precision":true,
    "precision":1,
    "thousands":"no"
}

link-formula

{
    "formula":"findmax",
    "result_type":"array",
    "operated_columns":["TaXD"],
    "conditions":[],
    "link_column_key":"TaXD",
    "include_condition":false,
    "condition_conjunction":"And",
    "column_key_in_linked_record":"0000",
    "column_key_for_comparison":"RSjx",
    "level2_linked_table_column_key":null,
    "array_type":"auto-number",
    "array_data":null
}

geolocation

{
    "geo_format":"lng_lat"
}

auto-number

{
    "format":"YYYYMMDD-00",
    "max_used_auto_number":33,
    "digits":2,
    "prefix_type":"date",
    "prefix":"20250909"
}

button

{
    "button_type":"copy_row_to_another_table",
    "button_name":"Copy to Table2",
    "button_color":"#FFFCB5",
    "table_id":"0000"
}

Accessing a particular data object value

This rather long list is not exhaustive, however. If you need to access a specific data value, consult the SeaTable API Reference or create the corresponding column to display the content of its data object.

Get Column(s)¶

getColumnByName

Get the column object of a table, specified by the column name.

base.getColumnByName(table, columnName);

Output Single column object (undefined if column doesn't exist)

Example

const column = base.getColumnByName('Table1', 'Name');

getColumns

Get all columns of a table.

base.getColumns(table);

Output Array of column objects

Example

const columns = base.getColumns('Table1');
columns.forEach((column) => {
    console.log(column.name);
});

listColumns

Get the columns of a table, optionally filtered by view. If no view is specified, all columns are returned.

base.listColumns(tableName, viewName);

Output Array of column objects

Example

const columns = base.listColumns('Table1', 'Default View');

getShownColumns

Get all visible columns of a table in a specific view (hidden columns are excluded). Only available in SeaTable scripts.

base.getShownColumns(table, view);

Output Array of column objects

Example

const columns = base.getShownColumns('Table1', 'Default View');

getColumnsByType

Get all columns of a specific type in a table. See the API Reference for supported column types.

base.getColumnsByType(table, type);

Output Array of column objects (empty array if no match)

Example

const textColumns = base.getColumnsByType('Table1', 'text');

Add Column¶

insertColumn

Add a new column to a table.

base.insertColumn(tableName, columnName, columnType, columnKey='', columnData='');

Example

import { ColumnTypes } from 'seatable-api';

await base.insertColumn('Table1', 'Notes', ColumnTypes.TEXT);

// Insert after a specific column
await base.insertColumn('Table1', 'Notes', ColumnTypes.TEXT, '0000');

// Create a link column
await base.insertColumn('Table1', 'Link1', ColumnTypes.LINK, '', {
    'table': 'Table1',
    'other_table': 'Table2'
});

Rename Column¶

renameColumn

Rename a column, identified by its column key.

base.renameColumn(tableName, columnKey, newColumnName);

Example

await base.renameColumn('Table1', 'kSiR', 'New Name');

Column Settings¶

resizeColumn

base.resizeColumn(tableName, columnKey, newColumnWidth);

Example

await base.resizeColumn('Table1', 'asFV', 500);

freezeColumn

base.freezeColumn(tableName, columnKey, frozen);

Example

await base.freezeColumn('Table1', '0000', true);

moveColumn

Move a column to the right of the target column.

base.moveColumn(tableName, columnKey, targetColumnKey);

Example

await base.moveColumn('Table1', 'loPx', '0000');

modifyColumnType

Change the type of an existing column.

base.modifyColumnType(tableName, columnKey, newColumnType);

Example

import { ColumnTypes } from 'seatable-api';
await base.modifyColumnType('Table1', 'nePI', ColumnTypes.NUMBER);

addColumnOptions

Add options to a single-select or multiple-select column.

base.addColumnOptions(tableName, columnName, options);

Example

await base.addColumnOptions('Table1', 'Status', [
    {"name": "Done", "color": "#73d56e", "textColor": "#000000"},
    {"name": "Open", "color": "#ff8000", "textColor": "#ffffff"},
]);

addColumnCascadeSettings

Add cascade settings to a single-select column, limiting child options based on the parent column's selection.

base.addColumnCascadeSettings(tableName, childColumn, parentColumn, cascadeSettings);

Example

await base.addColumnCascadeSettings('Table1', 'Sub-Category', 'Category', {
    "Electronics": ["Phones", "Laptops"],
    "Furniture": ["Chairs", "Tables"]
});

Delete Column¶

deleteColumn

Delete a column, identified by its column key.

base.deleteColumn(tableName, columnKey);

Example

await base.deleteColumn('Table1', 'bsKL');