Create¶

POST /api/v1/field_cfg/add

Overview¶

Create Field Management

Body Request Parameters¶

Parameter Name	Type	Required	Description
name	string	Y	Field name, under 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 Optional values: ['int', 'float', 'boolean', 'string', 'long']
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 the built-in field name, true to overwrite, false not to overwrite Example: True Allow empty: False

Parameter Additional Explanation¶

1. Request Parameter Explanation

Parameter Name	type	Required	Description
name	String	Required	Field name, under 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 empty string for general types
coverInner	String		Whether to overwrite when the field name is the same as the built-in field name, true to overwrite, false not to overwrite

For adding unit information, refer to Unit Explanation

2. Response Parameter Explanation

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 need to continue creating, specify coverInner as true, and the built-in field with the same name will be hidden.

3. Field Management Usage Explanation

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 (at the same level as queries) as true.
The returned series will add 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: For SHOW_FIELD_KEY field descriptions, use custom metric configuration and datakit side measurements-meta.json

3.2. Field Management provides unit information for queries

dql query unit loading (add units to the series of query_data results):
When querying metric data, the loaded unit information is for custom metric fields, overriding the official metric fields (measurements-meta.json)
When querying non-metric data, the loaded unit information is the unit defined in field management

3.3. Field Management query function explanation when providing unit information

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

function range, no unit is added, for example: count the unit is added with a fixed suffix /s, 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 Explanation

4.1. Custom fields take precedence over built-in fields
4.2. Fields with specific sources (fieldSource) take precedence over general field sources

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