Data table API

Last updated 10/03/2026

For how to call the API, see the calling method described in the Open API document.

Overview

1. The data table API supports some of the data table operations available in the UI, helping you meet the need to automate operations on data tables.

2. The data table API supports the following operations on data tables:

   • Create a data table
   • Update an existing data table
   • Associate a data table with a main property
   • Remove the association between a data table and a main property

3. Create a data table:

You can create a data table that doesn't exist yet, upload a file for the first time, and specify the name and type of each field in the data table.

4. Update an existing data table:

Only updates to the data table's content are supported. Adding or deleting data table fields or changing their types isn't supported.

You can perform a Replacement Update of the entire table's content, or an Incremental Update based on existing data.

5. Associate a data table with a main property:

You can associate an existing data table with a main property to generate dimension table properties.

6. Remove the association between a data table and a main property:

You can remove the association between an associated data table and a main property, which deletes the generated dimension table properties.

Note

• For more details about data tables, see Data tables
• For more details about dimension table properties, see Custom properties and dimension table properties

1. Create a data table

Creating a data table takes two steps:

• Upload the file
• Create the data table using the uploaded file

1.1 Upload a file

The maximum upload file size is 100M. Supported file types are Excel and CSV

Endpoint URL

/open/datatable/uploadFile

Request method

POST

Content-Type

multipart/form-data

Request query parameters

Parameter name	Example	Parameter type	Required	Parameter location	Description
token	xxx	String	Yes		Query key
projectId	0	number	Yes	query	ID of the project that the data table to be created belongs to.
file	"/path/to/my_datatable.xls"	file	Yes	body	multipart/form-data; the uploaded CSV/Excel table. The first column is the primary key

curl --location --request POST 'http://xxx.com/xxx/open/datatable/uploadFile?projectId=390' \
--form 'file=@"/path/to/my_datatable.xls"'

Output parameters

fileId (this fileId is used in the next step, which is creating the data table)

1.2 Create a data table

Endpoint URL

/open/datatable/createDatatable

Request method

POST

Content-Type

application/json

Request query parameters

Parameter name	Parameter type	Required	Parameter location	Description
token	String	Yes		Query key
projectId	number	Yes	query	ID of the project that the data table to be created belongs to.
fileId	string	Yes	body	ID of the uploaded file
datatableName	string	Yes	body	Data table name Must start with a lowercase letter and can contain lowercase letters, numbers, and underscores
datatableColumns	array	Yes	body	The name of each column and its data type Column names must start with a letter, can contain letters, numbers, and underscores "_", and can be up to 50 characters long
columnName	string	Yes		Column name
dataType	string	Yes		Column data type

Code example

curl --location --request POST 'http://xxx.com/xxx/open/datatable/createDatatable?projectId=390' \
--header 'Content-Type: application/json' \
--data-raw '{
    "fileId": "xxxxxxx",
    "datatableName": "xxx",
    "datatableColumns": [
        {
            "columnName": "aaa",
            "dataType": "string"
        }
    ]
}'

Output parameters

Parameter name	Data type	Description
succeededRowCount	number	Successful rows
failedRowCount	number	Failed rows

2. Update an existing data table

Endpoint URL

/open/datatable/updateDatatable

Request method

POST

Content-Type

application/json

Request query parameters

Parameter name	Data type	Required	Parameter location	Description
token	String	Yes		Query key
projectId	number	Yes	query	ID of the project that the data table to be created belongs to.
datatableName	string	Yes	query	Data table name
updateType	enum(INCR_UPDATE/REPL_UPDATE)	Yes	query	Update type. INCR_UPDATE is Incremental Update, and REPL_UPDATE is Replacement Update, which replaces the entire table's content
file	file	Yes	body	multipart/form-data; the uploaded CSV/Excel table. The first column is the primary key

Code example

curl -X POST 'http://xxx.com/open/datatable/updateDatatable?projectId=11&token=YOUR_TOKEN&datatableName=city_dim&updateType=INCR_UPDATE'\
 --form "file=@/path/to/file"

3. Associate a data table with a main property

Endpoint URL

/open/datatable/bindAssociatedProperty

Request method

POST

Content-Type

application/json

Request query parameters

Parameter name	Data type	Required	Parameter location	Description
token	String	Yes		Query key
projectId	Number	Yes	query	ID of the project that the data table to be created belongs to.
datatableName	String	Yes	body	Data table name
associatedPropertyName	String	Yes	body	Associated property name
associatedPropertyTableType	String(user/event)	Yes	body	Associated property type
timestampJoinFormat	Enum	No	body	If the main property is a time type (timestamp), you can bind dimension table properties after granularity calculation based on the timestamp

timestampJoinFormat supports the following granularity types.

Value	Description
DATE_STR_YEAR	The property is formatted as a "yyyy" string before dimension table properties are bound
DATE_STR_MONTH	The property is formatted as "yyyy-MM" before dimension table properties are bound
DATE_STR_DAY	The property is formatted as "yyyy-MM-dd" before dimension table properties are bound
DATE_STR_HOUR	The property is formatted as "yyyy-MM-dd HH" before dimension table properties are bound
DATE_STR_MINUTE	The property is formatted as "yyyy-MM-dd HH:mm" before dimension table properties are bound
DATE_STR_SECOND	The property is formatted as "yyyy-MM-dd HH:mm:ss" before dimension table properties are bound
DATE_STR_MILLISECOND	The property is formatted as "yyyy-MM-dd HH:mm:ss.SSS" before dimension table properties are bound

Code example

curl --location --request POST 'http://xxx.com/xxx/open/datatable/bindAssociatedProperty?projectId=390' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datatableName": "xxxxxxx",
    "associatedPropertyName": "aaa",
    "associatedPropertyTableType": "user",
    "timestampJoinFormat": "DATE_STR_YEAR"
}'

Output parameters

Parameter name	Data type	Description
dimensionProperties	Array
columnName	String	Dimension table property name
selectType	String	Dimension table data type

4. Remove the association between a data table and a main property

Endpoint URL

/open/datatable/unbindAssociatedProperty

Request method

POST

Content-Type

application/json

Request query parameters

Parameter name	Data type	Required	Parameter location	Description
token	String	Yes		Query key
projectId	Number	Yes	query	ID of the project that the data table to be created belongs to.
datatableName	String	Yes	body	Data table name
associatedPropertyName	String	Yes	body	Associated property name
associatedPropertyTableType	String(user/event)	Yes	body	Associated property type

Code example

curl --location --request POST 'http://xxx.com/xxx/open/datatable/unbindAssociatedProperty?projectId=390' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datatableName": "xxxxxxx",
    "associatedPropertyName": "aaa",
    "associatedPropertyTableType": "user"
}'