Add¶

POST /api/v1/field_cfg/add

Overview¶

Create Field Management

Body Request Parameters¶

Parameter Name	Type	Required	Description
name	string	Y	Field name. Field names cannot be duplicated within the same field source (fieldSource). 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. If 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 Optional values: ['int', 'float', 'boolean', 'string', 'long']
category	string		Attribute classification, including: System fields (selected by default), Business fields, Other. Allow empty: False Allow empty string: False Optional values: ['system', 'business', 'other']
fieldSource	string		Field source. Example: time Allow empty: False Allow empty string: True Optional 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 to overwrite, false to not overwrite. Example: True Allow empty: False

Parameter Supplementary Description¶

1. Request Parameter Description

Parameter Name	type	Required	Description
name	String	Required	Field name. Field names cannot be duplicated within the same field source (fieldSource).
alias	String	Required	Field alias.
desc	String		Description.
unit	String		Unit information. If fieldType is string, the unit will be set to empty.
fieldType	String		Field type.
fieldSource	String		Field source. Use an empty string to represent generic types.
coverInner	String		Whether to overwrite when the field name is the same as a built-in system field. true to overwrite, false to 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.
To continue creation, coverInner must be set to true. The built-in field with the same name will be hidden.

3. Field Management Usage Instructions

3.1. Field Management provides field descriptions for field queries.
When performing queries with the following functions, if field descriptions need to be returned, fieldTagDescNeeded (positioned at the same level as queries) must be set to true.
A value_desc field (positioned 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 Metrics configuration and the measurements-meta.json file from the Datakit side.

3.2. Field Management provides unit information for queries.

Unit loading for DQL queries (units is added to the series of the query_data result):
When querying Metrics data, the loaded unit information is for custom Metrics fields, overriding the official Metrics fields (from measurements-meta.json).
When querying non-Metrics data, the loaded unit information is as defined in Field Management.

3.3. Instructions for query functions when Field Management provides unit information.

During DQL queries, if the function used is not within the configured unitWhiteFuncs
unitWhiteFuncs contains two types of functions: normal and special.
Description of unitWhiteFuncs functions:

function scope, the unit is not added. For example: count. When using functions from the special category, 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. Field Name Priority Instructions

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