通用参考

字段名称冲突处理

在日志上传或者SPL运行期间，基于大小写敏感的处理可能会涉及字段名的冲突，如原始日志中同时存在Method和method字段名；针对不同的场景SPL会使用不同的方式进行字段冲突解决。

为了避免以下情况，建议在原始日志中规范输入的字段。

运行结果中存在冲突

日志服务完整保留字段列表请参见保留字段。SPL读取存储在SLS的LogGroup结构数据作为输入（LogGroup定义详情请参见数据编码方式），如果原始写入日志服务的数据不符合标准LogGroup编码规范，即某些保留字段并未按照标准编码在对应位置，而是放在LogContent中，则SPL在读取此类保留字段策略如下：

• 对于__source__、__topic__、__time__和__time_ns_part__字段，SPL会从标准LogGroup编码结果中读取值，忽略同名的LogContent字段。

• 对于以__tag__: 为前缀的Tag字段，SPL将优先从标准LogGroup编码结果中读取值，未取到再从LogContent中取值。例如对于字段__tag__:ip，优先从LogTag列表中读取key为ip的字段，如果不存在，再从LogContent中的自定义日志字段中读取key为__tag__:ip的 Log 字段。

全文字段__line__

如果在控制台或者GetLogstoreLogs接口中想对原始日志进行过滤，可以使用__line__字段。

示例

• 在日志中搜索关键词error。

* | where __line__ like '%error%'

• 如果日志中有字段名为__line__，需要使用反引号包裹，即 `__line__`来引用日志中的字段。

* | where `__line__` ='20'

新旧值类型不一致

直接保留输入字段原始值。

示例

• 示例1：project重命名字段重名。

  • SPL语句

    * 
    | extend status=cast(status as BIGINT) -- status类型转为BIGINT
    | project code=status -- code旧值类型为VARCHAR，新值为BIGINT，直接保留旧值

  • 输入数据

    status: '200'
    code: 'Success'

  • 输出结果

    code: 'Success'

• 示例2：parse-json提取字段重名。

  • SPL语句

    * 
    | extend status=cast(status as BIGINT) -- status类型转为BIGINT
    | parse-json content -- status旧值类型为BIGINT，新值为VARCHAR，直接保留旧值

  • 输入数据

    status: '200'
    content: '{"status": "Success", "body": "this is test"}'

  • 输出结果

    content: '{"status": "Success", "body": "this is test"}'
    status: 200
    body: 'this is test'

新旧值类型一致

如果输入值为null，直接使用新值填充。否则，由指令中指定的mode参数确定，定义如下表。

示例

• 示例1：project重命名字段重名，且类型相同，mode默认值为overwrite。

  • SPL语句

  * | project code=status -- code新旧值类型均为VARCHAR，根据overwrite引用新值

  • 输入数据

    status: '200'
    code: 'Success'

  • 输出结果

    code: '200'

• 示例2：parse-json提取字段重名，且类型相同，mode默认值为overwrite。

  • SPL语句

    * | parse-json content -- status新旧值类型均为VARCHAR，根据overwrite引用新值

  • 输入数据

    status: '200'
    content: '{"status": "Success", "body": "this is test"}'

  • 输出结果

    content: '{"status": "Success", "body": "this is test"}'
    status: 'Success'
    body: 'this is test'

• 示例3：parse-json提取字段重名，且类型相同，mode指定为preserve。

  • SPL语句

    * | parse-json -mode='preserve' content -- status新旧值类型均为VARCHAR，根据preserve保留旧值

  • 输入数据

    status: '200'
    content: '{"status": "Success", "body": "this is test"}'

  • 输出结果

    content: '{"status": "Success", "body": "this is test"}'
    status: '200'
    body: 'this is test'

数据类型转换

初始类型

除日志时间字段外，数据处理SPL的输入字段的初始数据类型均为VARCHAR。在后续的处理逻辑中，如果涉及到强数据类型时，需要进行数据类型转换。

示例

筛选出状态码为5xx的访问日志时，需要将status字段的类型转为BIGINT之后再进行比较。

* -- status字段的初始类型为VARCHAR
| where cast(status as BIGINT) >= 500 -- 将status字段的类型转为BIGINT，再进行比较

类型保持

在SPL处理数据过程中，使用extend指令对字段进行数据类型转换后，后续的处理逻辑将沿用转换后的数据类型。

示例

* -- Logstore作为输入数据，除时间字段外，所有字段初始类型为VARCHAR
| where __source__='127.0.0.1' -- 对__source__字段进行过滤
| extent status=cast(status as BIGINT) -- 将status字段的类型转为BIGINT
| project status, content
| where status>=500 -- status字段的类型保持为BIGINT，可以直接与数字500做比较

产生null值

SPL处理数据过程中，如下两个场景将产生null值：

1. SPL表达式中使用到的字段在输入数据中不存在时，则将其值视为null值进行计算。

2. SPL表达式计算过程中出现异常，其计算结果即为null值。比如cast类型转换失败、数组越界等。

示例

1. 字段不存在时，计算代入null值。

• SPL语句

* | extend withoutStatus=(status is null)

• 输入数据

# 条目1
status: '200'
code: 'Success'

# 条目2
code: 'Success'

• 输出结果

# 条目1
status: '200'
code: 'Success'
withoutStatus: false

# 条目2
code: 'Success'
withoutStatus: true

2. 计算过程异常，计算结果为null值。

• SPL语句

  *
  | extend code=cast(code as BIGINT) -- code字段转为BIGINT失败
  | extend values=json_parse(values)
  | extend values=cast(values as ARRAY(BIGINT))
  | extend last=arr[10] -- 数组越界

• 输入数据

  status: '200'
  code: 'Success'
  values: '[1,2,3]'

• 输出结果

  status: '200'
  code: null
  values: [1, 2, 3]
  last: null

消除null值

为了消除计算过程中的null值，需使用COALESCE表达式将多个值按优先级联合，获取第一个非null值作为最终计算结果。在所有表达式计算结果都为null时，也可以设置最终默认值。

示例

读取数组最后一个元素，如果数组为空，默认值为0。

• SPL语句

  *
  | extend values=json_parse(values)
  | extend values=cast(values as ARRAY(BIGINT))
  | extend last=COALESCE(values[3], values[2], values[1], 0)

• 输入数据

  # 条目1
  values: '[1, 2, 3]'
  
  # 条目2
  values: '[]'

• 输出结果

  # 条目1
  values: [1, 2, 3]
  last: 3
  
  # 条目2
  values: []
  last: 0