Simple Log Service:一般リファレンス

フィールド名の競合の取り扱い

ログのアップロードまたは SPL 実行中に、大文字小文字を区別する処理によりフィールド名の競合が発生することがあります。たとえば、生ログに Method および method の両方のフィールドが含まれている場合などです。SPL では、シナリオに応じてこれらの競合を異なる方法で解決します。

このような状況を回避するには、生ログ内のフィールド名を標準化することを推奨します。

出力結果における競合

予約フィールドの完全な一覧については、「予約フィールド」をご参照ください。SPL は、入力として LogGroup 構造からデータを読み込みます。LogGroup の定義の詳細については、「データエンコーディング」をご参照ください。Simple Log Service に書き込まれる生データが標準の LogGroup 形式でエンコードされていない場合、一部の予約フィールドが標準の場所ではなく LogContent に格納されることがあります。SPL はこれらの予約フィールドを以下のように処理します：

• __source__、__topic__、__time__、および __time_ns_part__ フィールドについては、SPL が標準の LogGroup 構造から値を読み取り、LogContent 内の同名フィールドは無視します。

• __tag__: プレフィックスを持つタグフィールドについては、SPL がまず標準の LogGroup 構造から値を読み取ろうと試みます。値が見つからない場合、LogContent から読み取ります。たとえば、__tag__:ip フィールドの場合、SPL はまず LogTag リストからキー ip を持つフィールドを読み取ろうと試みます。該当するフィールドが存在しない場合、SPL は LogContent のカスタムログフィールドからキー __tag__:ip を持つログフィールドを読み取ります。

全文検索のための __line__ フィールド

コンソールでの生ログのフィルター処理、または GetLogstoreLogs API オペレーションの使用時に、__line__ フィールドを使用できます。

例

• ログ内にキーワード error を検索します。

  * | where __line__ like '%error%'

• ログに `__line__` という名前のフィールドが含まれている場合、バックティックで囲んで参照します。

  * | where `__line__` ='20'

古い値と新しい値のデータ型が不一致の場合

入力フィールドの元の値が保持されます。

例

• 例 1：project 命令で名前を変更したフィールドが競合している場合

  • SPL 文

    * 
    | extend status=cast(status as BIGINT) -- status フィールドの型を BIGINT に変換します。
    | project code=status -- 新しい値の型（BIGINT）が古い値の型（VARCHAR）と異なるため、古い値が保持されます。

  • 入力データ

    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 命令で名前を変更したフィールドが競合しており、型も一致しています。デフォルトモードは overwrite です。

  • SPL 文

  * | project code=status -- code の古い型と新しい型はどちらも VARCHAR です。overwrite モードに基づき、新しい値が使用されます。

  • 入力データ

    status: '200'
    code: 'Success'

  • 出力結果

    code: '200'

• 例 2：parse-json 命令で抽出されたフィールドが競合しており、型も一致しています。デフォルトモードは 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 命令で抽出されたフィールドが競合しており、型も一致しています。モードは 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__ フィールドでフィルター処理します。
| extend status=cast(status as BIGINT) -- status フィールドの型を BIGINT に変換します。
| project status, content
| where status>=500 -- status フィールドの型は BIGINT のままなので、数値 500 と直接比較できます。

null 値の生成

SPL のデータ処理中、null 値は以下の 2 つのシナリオで生成されます：

1. SPL 式で使用されるフィールドが入力データに存在しない場合、計算時にその値は null として扱われます。

2. SPL 式の計算中に例外が発生した場合、結果は null になります。たとえば、キャスト型変換が失敗した場合や、配列のインデックスが範囲外の場合などです。

例

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

シングルクォート

シングルクォートは文字列リテラルを囲むために使用されます。文字列リテラルにシングルクォートが含まれる場合、それをエスケープするために追加のシングルクォートを使用する必要があります。

ダブルクォート

ダブルクォートはフィールド名を囲むために使用されます。フィールド名にダブルクォートが含まれる場合、それをエスケープするために追加のダブルクォートを使用する必要があります。