Dimension table API
For how to call the API, see the calling method described in the Open API document.
1. Create a dimension table
- The request body is the dimension table content. For details, see the configuration of the dimension table creation parameter
createParam - The default maximum file size is 200M
Endpoint URL
/open/dict-create?token=xxx&projectId=0
Request method
POST
Content-Type
text/csv
Request query parameters
| Parameter name | Example value | Parameter type | Required | Description |
|---|---|---|---|---|
| token | xxx | String | Yes | Query key |
| projectId | 0 | Integer | Yes | Project ID |
| createParam | {"mainColumn":{"property":{"columnName":"channel","tableType":"event"}},"columns":[{"property":{"columnName":"channel_id","selectType":"string"}},{"property":{"columnName":"channel_name","columnDesc":"Channel type","selectType":"string"}}]} | String | Yes | Description of the dimension columns to create |
Configuration of the dimension table creation parameter createParam
Create dimension table properties
Here the main field is channel, which corresponds to the first column channel in the dimension table. The dimension table property to add is channel_name
1. Dimension table example
- The dimension table data uses CSV format. The first column is the associated field and isn't created as a dimension table property. The columns from the second column on are the dimension table properties to add
- The first row of the data contains field names, and data starts from the second row
channel,channel_name
1,Longteng Zone 1
2,Longteng Zone 2
3,Longteng Zone 3
2. createParam example (creates the above dimension table for the channel field of the event table)
In the columns list, the order of elements must match the order of the columns in the dimension table data, and the names must match too. The first element (corresponding to the associated first column) can have the same name as the parent element or a different one (if different, it must start with a letter and contain only letters, numbers, and underscores).
{
"mainColumn": {
"property": {
"columnName": "channel",
"tableType": "event",
"timestampJoinFormat": null
}
},
"columns": [
{
"property": {
"columnName": "channel",
"selectType": "number"
}
},
{
"property": {
"columnName": "channel_name",
"columnDesc": "Channel type",
"selectType": "string"
}
}
]
}
3. createParam field descriptions
mainColumn node (describes the main field used to create the dimension table)
| Property name | Property description |
|---|---|
| property | Main property (both physical properties and custom properties are supported) |
| columnName | Field name of the main property |
| tableType | Type of the table the main property belongs to. event: event property; user: user property |
| timestampJoinFormat | 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 |
columns list (describes the dimension fields)
In the columns list, the order of elements must match the order of the columns in the dimension table data.
| Property name | Property description |
|---|---|
| property | Property list of the dimension field |
| columnName | Dimension field name |
| columnDesc | Dimension field description, that is, the display name of the field (optional) |
| selectType | Dimension field type: number (numeric), bool (Boolean), string (string), datetime (date), array_string (list; primary key column only, not allowed for other columns) |
4. Creation result
After the dimension table is created, you can find the dimension table property named channel@channel_name
Success response example
{
"data": {
"duplcatedMainKeyColumns": ["activity_type@type_test"],
"duplcatedMainKeyLineNum": 2,
"mainKeyErrorColumns": ["activity_type@type_test"],
"mainKeyErrorLineNum": 3,
"successLineNum": 27,
"totalLineNum": 40,
"typeErrorColumns": ["numwrong_test", "boolwrong_test"],
"typeErrorLineNum": 8
},
"return_code": 0,
"return_message": "success"
}
| $$Parameter name | Example value | Parameter type | Description |
|---|---|---|---|
| return_code | 0 | Integer | Return code |
| return_message | success | String | Return message |
| data | - | Object | Returned result |
| data.duplcatedMainKeyColumns | ["activity_type@type_test"] | List | Column names with duplicate associated main field values |
| data.duplcatedMainKeyLineNum | 2 | Integer | Number of rows with duplicate associated main field values (automatically discarded) |
| data.mainKeyErrorColumns | ["activity_type@type_test"] | List | Column names whose associated main field failed to parse |
| data.mainKeyErrorLineNum | 3 | Integer | Number of rows whose associated main field failed to parse (automatically discarded) |
| data.successLineNum | 27 | Integer | Number of successful rows |
| data.totalLineNum | 40 | Integer | Total rows |
| data.typeErrorColumns | ["numwrong_test", "boolwrong_test"] | List | Column names with type errors in other fields |
| data.typeErrorLineNum | 8 | Integer | Number of rows with type errors in other fields (set to null) |
Error response example
{
"return_code": -1008,
"return_message": "The uploaded file size cannot exceed 209715200 bytes"
}
| Parameter name | Example value | Parameter type | Description |
|---|---|---|---|
| return_code | -1100 | Integer | Return code |
| return_message | The uploaded file size cannot exceed 209715200 bytes | String | Return message |
curl example
curl --header 'Content-Type: text/csv' --data-binary '@test.csv' 'http://ta2:8992/open/dict-create?token=YOUR_TOKEN&projectId=377&createParam=%7B%22mainColumn%22%3A%7B%22property%22%3A%7B%22columnName%22%3A%22channel%22%2C%22tableType%22%3A%22event%22%7D%7D%2C%22columns%22%3A%5B%7B%22property%22%3A%7B%22columnName%22%3A%22channel_id%22%2C%22selectType%22%3A%22string%22%7D%7D%2C%7B%22property%22%3A%7B%22columnName%22%3A%22channel_name%22%2C%22columnDesc%22%3A%22%E6%B8%A0%E9%81%93%E7%B1%BB%E5%9E%8B%22%2C%22selectType%22%3A%22string%22%7D%7D%5D%7D'