Append data to table

Use this API to add data in bulk to an existing table. If you need to add columns, you can also add the configuration information corresponding to the columns in the json saved in the columns file (see Create table API).

Request

# Append (new rows)
curl -vvv -X POST "$API_HOST/open/api/v1/tablenodes/$table_id/rows/append/" \
  -H "Authorization: $access-token" \
  -d "skipFirstRow=false&autoCreateColumn=true" \
  -F "columns=@$file_path" \
  -F "rows=@$csv_file_path"

# Merge mode (update existing rows by indexColumnID)
curl -X POST "$API_HOST/open/api/v1/tablenodes/$table_id/rows/append/" \
  -H "Authorization: $access-token" \
  -F "rows=@data.csv" \
  -F "skipFirstRow=true" \
  -F "indexColumnID=$index_column_id" \
  -F "mergeStrategy=merge"

The request is submitted using a form that contains two fields: columns and rows, which represent the "table column definition" and "data rows" respectively. Refer to the table below for details.

Response body form-data example

Key	Value	Required	Note
skipFirstRow	false	NO	Skip the csv header
autoCreateColumn	false	NO	Create new columns (if a column has no id field in the config file)
columns	read_table_columns.json	YES	Columns configuration file. The columns should keep the same order as columns in csv file.
rows	gd_append.csv	YES	Row data CSV file
indexColumnID	$index_column_id	NO	Index column ID (24-char hex). Enables merge mode when specified — rows matching existing values in this column are updated; unmatched rows are appended as new.
mergeStrategy	merge	NO	Merge strategy, requires indexColumnID. merge — skip null values, only update specified columns. overwrite — replace entire row. Default behavior without this field is standard append (no merge).

column parameters json format description

Key	Type	Description	Required
	array	column list	Y
∟ id	string	column ID	Y, blank if user want to add a new column
∟ name	string	Column Name	Yes if new column
∟ type	string	column type：multiLineText number datetime singleChoice coordinate	Yes if new column
∟ typeOptions	object	column options：When column is number, datetime, or singleChoice	N
∟ format	string	number type：number, percentage, commaNumber	YES：When number type
∟ precision	string	precision: 0-5	YES：When number type
∟ dateFormat	string	date format: year/month/day month/day/year detail	YES：When datetime type
∟ timeFormat	string	time format: hidden 24-hour-clock 12-hour-clock	YES：When datetime type
∟ choices	array	option list: created automatically when empty	YES：When singleChoice type
∟ name	string	option name	YES：When singleChoice type
∟ color	string	option color: use a random color when empty	YES：When singleChoice type

Python example

def table_append_data(access_token, table_id, data, columns_file, data_file):
    url = '%s/open/api/v1/tablenodes/%d/rows/append/' % (API_HOST, table_id)
    files = {'rows': open(data_file, 'rb'),
             'columns': open(columns_file, 'rb')}
    headers = {'Authorization': access_token}
    req = requests.post(url, data=data, headers=headers, files=files)
    return req.json()

# create table using csv
data = {
    'projectID': project['id'],
    'name': 'test-csv-upload',
    'skipFirstRow': True
}
resp = ma.create_table(access_token, data,
                       'data/create_table_columns.json',
                       'data/gd.csv')

table = resp['detail']
resp = ma.read_table(access_token, table['id'], '', '')
with open('data/read_table_columns.json', 'w') as f:
    json.dump(resp['detail']['columns'], f)

data = {
    'skipFirstRow': True,
    'autoCreateColumn': False
}

resp = ma.table_append_data(access_token, table['id'],
                            data,
                            'data/read_table_columns.json',
                            'data/gd.append.csv')

Response

Response body

Description of some key information

Key	Type	Description
detail	object	Response object
∟ id	int64	Table ID
∟addedColumns	array	Added columns (if new columns added)
∟ id	string	Column ID
∟ type	string	Column type
∟typeOptions	object	Column options
∟ isPrimary	boolean	Is primary column
∟appendRowIDs	map	New row IDs (CSV row index → row ID)
∟rowIDMap	map	Row ID mapping (used in merge mode)
∟updatedRowCount	int	Number of rows updated (merge mode)
∟columnIDMap	map	Column ID mapping

Response body example

{
    "code": 0,
    "detail": {
        "id": 980,
        "name": "newName2",
        "type": "table",
        "order": 441,
        "parentID":null,
        "projectID": 264,
        "subscribed":false,
        "published":false,
        "roleInherited":true,
        "createTime": "2022-04-15T06:44:21.506295Z",
        "updateTime": "2022-04-15T06:48:33.243726Z",
        "addedColumns": [
            {
                "id": "625914457cff69c01aed2d71",
                "name": "New-Title1",
                "type": "multiLineText",
                "typeOptions":null,
                "isPrimary":true            }
        ],
        "appendRowIDs": {
            "0": "625931df04b5540935aef0dd",
            "1": "625931df04b5540935aef0de"
        },
        "importErr":null    },
    "extra":null,
    "message": "OK",
    "requestID":null
}