Create¶

POST /api/v1/field_cfg/add

Overview¶

Create a new field configuration.

Body Request Parameters¶

Parameter Name	Type	Required	Description
name	string	Y	Field name. Must be unique within the same field source (fieldSource). Allow Null: False Allow Empty String: False Max Length: 256
alias	string	Y	Field alias. Allow Null: False Allow Empty String: False Max Length: 256
aliasI18n	object		Multilingual field alias. Supported keys: zh/en/zh-hant/id/ja/ko. Allow Null: False
unit	string		Unit information. When fieldType is string, the unit will be cleared. Allow Null: False Max Length: 256 Allow Empty String: True
fieldType	string		Field type. Example: time Allow Null: False Allow Empty String: True Allowed Values: ['text', 'int', 'float', 'boolean', 'string', 'long']
category	string		Attribute category. Includes: System Field (default), Business Field, Other. Allow Null: False Allow Empty String: False Allowed Values: ['system', 'business', 'other']
fieldSource	string		Field source. Example: time Allow Null: False Allow Empty String: True Allowed Values: ['logging', 'object', 'custom_object', 'keyevent', 'tracing', 'rum', 'security', 'network', 'billing']
desc	string		Field description. Example: host name Allow Null: False Allow Empty String: True Max Length: 3000
descI18n	object		Multilingual field description. Supported keys: zh/en/zh-hant/id/ja/ko. Allow Null: False
coverInner	boolean		Whether to override when the field name conflicts with a system built-in field name. true = override, false = do not override. Example: True Allow Null: False

Parameter Supplementary Notes¶

1. Request Parameter Description

Parameter Name	Type	Required	Description
name	String	Required	Field name. Must be unique within the same field source (fieldSource).
alias	String	Required	Field alias.
desc	String		Description.
unit	String		Unit information. When fieldType is string, the unit will be cleared.
fieldType	String		Field type.
fieldSource	String		Field source. Use an empty string for a generic type.
coverInner	String		Whether to override when the field name conflicts with a system built-in field name. true = override, false = do not override.

For adding unit information, refer to Unit Description.

2. Response Parameter Description

When the content returned by this API is need_confirm, it indicates that a built-in field with the same source and name already exists.
To continue creating, specify coverInner as true; the built-in field with the same name will be hidden.

3. Field Management Usage Notes

3.1. Field Management provides field descriptions for field queries.
When performing the following function queries, if you need to return field descriptions, specify fieldTagDescNeeded (field position at the same level as queries) as true.
The returned series will include a value_desc field (at the same level as values and columns).

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 Configuration and DataKit's measurements-meta.json.

3.2. Field Management provides unit information for queries.

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

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

When performing DQL queries, if the function used is not within the configured unitWhiteFuncs
unitWhiteFuncs contains two types of functions: normal and special. When a
unitWhiteFuncs function description:

range, the unit is not added, e.g., count. special function is used, the unit is appended with a fixed suffix /s, e.g., 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. Field Name Priority Description

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"
}