Create Field Management¶

POST /api/v1/field_cfg/add

Overview¶

Create field management

Body Request Parameters¶

Additional Parameter Explanation¶

1. Request Parameter Explanation

For adding unit information, refer to Unit Description

2. Response Parameter Explanation

When the returned content of this interface is need_confirm, it indicates that there already exists a built-in field with the same source and name.
If you wish to continue creating, you must specify coverInner as true, and the existing 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 the following function queries, if you need to return field descriptions, you should specify fieldTagDescNeeded (at the same level as queries) as true.
The series in the response will add a value_desc field (at the same level as values and columns).

Note: The field description for SHOW_FIELD_KEY uses custom metric configuration and datakit side measurements-meta.json

3.2. Field management provides unit information for queries

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

3.3. Query function explanation when field management provides unit information

During dql queries, if the used function is not within the configured unitWhiteFuncs functions, no unit is added, for example: count
unitWhiteFuncs contains two types of functions: normal and special. When using special functions, a fixed suffix "/s" is added to the unit, unit = {"unit": unit, "suffix": "/s"}
unitWhiteFuncs function explanation:

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 generic 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: en' \
-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"
}