Create¶

POST /api/v1/field_cfg/add

Overview¶

Create Field Management

Body Request Parameters¶

Parameter Name	Type	Required	Description
name	string	Y	Field name. For the same field source (fieldSource), the field name cannot be duplicated. Allow empty: False Allow empty string: False Max length: 256
alias	string	Y	Field alias. Allow empty: False Allow empty string: False Max length: 256
unit	string		Unit information. When fieldType is string, the unit will be set to empty. Allow empty: False Max length: 256 Allow empty string: True
fieldType	string		Field type. Example: time Allow empty: False Allow empty string: True Allowed values: ['int', 'float', 'boolean', 'string', 'long']
category	string		Attribute classification, includes: system fields (selected by default), business fields, other. Allow empty: False Allow empty string: False Allowed values: ['system', 'business', 'other']
fieldSource	string		Field source. Example: time Allow empty: False Allow empty string: True Allowed values: ['logging', 'object', 'custom_object', 'keyevent', 'tracing', 'rum', 'security', 'network', 'billing']
desc	string		Field description information. Example: Host name Allow empty: False Allow empty string: True Max length: 3000
coverInner	boolean		Whether to overwrite when the added field name is the same as a built-in system field. true means overwrite, false means do not overwrite. Example: True Allow empty: False

Parameter Supplementary Explanation¶

1. Request Parameter Description

Parameter Name	type	Required	Description
name	String	Required	Field name. For the same field source (fieldSource), the field name cannot be duplicated.
alias	String	Required	Field alias.
desc	String		Description.
unit	String		Unit information. When fieldType is string, the unit will be set to empty.
fieldType	String		Field type.
fieldSource	String		Field source. Use an empty string for generic types.
coverInner	String		Whether to overwrite when the field name is the same as a built-in system field. true means overwrite, false means do not overwrite.

For adding unit information, refer to Unit Description

2. Response Parameter Description

When the content returned by this interface is 'need_confirm', it indicates that a built-in field with the same source and name already exists.
If you want to continue creation, you need to set coverInner to true. The built-in field with the same name will be hidden.

3. Usage Instructions for Field Management

3.1. Field Management provides field descriptions for field queries.
When performing query functions like the following, if you need to return field descriptions, you need to specify fieldTagDescNeeded (at the same level as queries) as true.
A value_desc field (at the same level as values and columns) will be added to the returned series.

Function	Field Source/fieldSource
SHOW_TAG_KEY	""
SHOW_OBJECT_HISTORY_FIELD	"object"
SHOW_BACKUP_LOG_FIELD	"logging"
SHOW_PROFILING_FIELD	"tracing"
SHOW_OBJECT_FIELD	"object"
SHOW_LOGGING_FIELD	"logging"
SHOW_EVENT_FIELD	"keyevent"
SHOW_TRACING_FIELD	"tracing"
SHOW_RUM_FIELD	"rum"
SHOW_CUSTOM_OBJECT_FIELD	"custom_object"
SHOW_CUSTOM_OBJECT_HISTORY_FIELD	"custom_object"
SHOW_NETWORK_FIELD	"network"
SHOW_SECURITY_FIELD	"security"
SHOW_UNRECOVERED_EVENT_FIELD	"keyevent"
SHOW_TRACING_METRIC_FIELD	"tracing"
SHOW_RUM_METRIC_FIELD	"rum"
SHOW_NETWORK_METRIC_FIELD	"network"

Note: Field descriptions for SHOW_FIELD_KEY use custom metric configurations and the datakit-side measurements-meta.json.

3.2. Field Management provides unit information for queries.

DQL query unit loading (adds units to the series in the query_data result):
When querying Metrics data, the loaded unit information is for custom metric fields, overriding the official metric fields (measurements-meta.json).
When querying non-Metrics data, the loaded unit information is the unit defined in Field Management.

3.3. Explanation of query functions when Field Management provides unit information.

During DQL queries, if the function used is not within the configured unitWhiteFuncs function
unitWhiteFuncs has two types of functions: normal and special. When using special functions,
unitWhiteFuncs function explanation is as follows:

range, no unit is added, e.g., count. a fixed suffix /s is added to the unit, unit = {"unit": unit, "suffix": "/s"} name="__codelineno-0-1">unitWhiteFuncs: normal: - avg - bottom - top - difference - non_negative_difference - distinct - first - last - max - min - percentile - sum - median - mode - spread - moving_average - abs - cumsum - moving_average - series_sum - round - window special: - derivative - non_negative_derivative - rate - irate

4. Explanation of Field Name Priority

4.1. Custom fields take precedence over built-in fields.
4.2. Fields with a specific source (fieldSource) take precedence over fields with a generic source.

Request Example¶

curl 'https://openapi.guance.com/api/v1/field_cfg/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Accept-Language: zh' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"name":"test_load","alias":"as_load","fieldType":"float","desc":"temp","fieldSource":"","unit":"","coverInner":false}' \
--compressed

Response¶

{
    "code": 200,
    "content": {
        "alias": "as_load",
        "aliasEn": "",
        "createAt": 1735628856,
        "creator": "wsak_xxx",
        "declaration": {
            "business": "",
            "organization": "default_private_organization"
        },
        "deleteAt": -1,
        "desc": "temp",
        "descEn": "",
        "fieldSource": "",
        "fieldType": "float",
        "id": 1791,
        "name": "test_load",
        "status": 0,
        "sysField": 0,
        "unit": "",
        "updateAt": -1,
        "updator": "",
        "uuid": "field_0f95016f7254494da088d878ce586477",
        "workspaceUUID": "wksp_05adf2282d0d47f8b79e70547e939617"
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-5E004BC0-E1E0-459A-8843-6FECBF0353DF"
}