レコードをメタデータインスタンスにリンクする

このガイドでは、レコードをメタデータインスタンスにリンクする方法について説明します。Manufacturing Data Engine（MDE）は、メタデータバケットの instance_id をレコードに書き込むことで、レコードをメタデータインスタンスにリンクします。ただし、パーサーの proto レコードで instance_id を直接設定することはありません。代わりに、MDE は、proto レコードで指定した入力に基づいて instance_id を自動的に解決します。MDE には、instance_id で解決する 2 つの方法があります。

メタデータインスタンスの自然キー別。
メタデータインスタンス値別。

自然キーによるメタデータ instance_id の解決

メタデータバケット内の各メタデータインスタンスには元のキーがあり、元のキーに対して複数のインスタンスが存在する場合があります。パーサーの proto レコードで自然キーを指定することで、レコードを自然キーの最新のメタデータインスタンスに関連付けることができます。MDE は、指定した自然キーの最新のインスタンスを取得し、インスタンスの instance_id をレコードに挿入します。

たとえば、バケット番号 1 の machine というレコードメタデータバケットに次のメタデータインスタンスがあるとします。

[
  {
    "instance_id": "a614e25d-fded-41c3-9a56-3222cd30070d",
    "bucket_number": "1",
    "bucket_name": "machine",
    "bucket_version": "1",
    "natural_key": "m-234",
    "instance": {
      "machineName": "CNC Mill"
    },
    "created_timestamp": "2023-06-27 20:00:29.603000 UTC"
  },
  {
    "instance_id": "6cfdf894-2fb6-4951-82c6-c4eada587529",
    "bucket_number": "1",
    "bucket_name": "machine",
    "bucket_version": "1",
    "natural_key": "m-234",
    "instance": {
      "machineName": "5 Axis CNC Mill"
    },
    "created_timestamp": "2023-06-28 20:00:29.632000 UTC"
  }
]

次のソースメッセージをサンプルとして使用します。

{
  "sensor": "rotation-speed-sensor",
  "machine": "m-234",
  "timestamp": "1687973092857",
  "value": 1200
}

次の Whistle スクリプト:

package mde

[
    {
        tagName: $root.machine + "-" + $root.sensor;
        data: {
            numeric: $root.value;
        };
        timestamps: {
            eventTimestamp: $root.timestamp;
        }
        cloudMetadata: [{
            bucketReference: {
                bucketName: "machine";
                version: 1;
            }
            naturalKey: $root.machine
        }]
    }
]

次の proto レコードが生成されます。

[
  {
    "tagName": "m-234-rotation-speed-sensor",
    "data": {
      "numeric": 1200
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    },
    "cloudMetadata": [
      {
        "bucketReference": {
          "bucketName": "machine",
          "number": 1
        },
        "naturalKey": "m-234"
      }
    ]
  }
]

MDE が proto レコードの処理を完了すると、BigQuery で次のレコード（行）が生成されます（BigQuery シンクとメタデータの実体化が有効になっている場合）。

[
  {
    "id": "6e008960-7f25-4418-899c-75b05c3d3186",
    "tag_name": "m-234-rotation-speed-sensor",
    "type_version": "1",
    "event_timestamp": "2023-06-28 17:24:52.526000 UTC",
    "value": "1200",
    "embedded_metadata": {},
    "materialized_cloud_metadata": {
      "machine": {
        "machineName": "5 Axis CNC Mill"
      }
    },
    "cloud_metadata_ref": {
      "machine": {
        "instance_id": "6cfdf894-2fb6-4951-82c6-c4eada587529"
      }
    },
    "event_timestamp": "2023-06-28 17:24:53.526000 UTC",
    "source_message_id": "8511923697775002"
  }
]

インスタンス値によるメタデータ `instance_id` の解決

または、パーサーの proto レコードでメタデータインスタンスオブジェクト全体を指定して、レコードを自然キーの最新のメタデータインスタンスに関連付けることもできます。必要に応じて、自然キーを指定できます。自然キーを省略すると、MDE はバケットタイプに基づいて自然キーを推測します。

タグバケットのメタデータインスタンス値を指定し、自然キーを省略すると、MDE はタグ名を自然キーとして自動的に使用します。
レコード バケットのメタデータインスタンス値を指定し、自然キーを省略すると、MDE はインスタンスオブジェクトのハッシュ値を自然キーとして自動的に使用します。

パーサーで proto レコードを構築すると、MDE は、指定されたメタデータインスタンスオブジェクトと、指定された自然キーの最新のメタデータインスタンスオブジェクトを比較します。

インスタンスオブジェクトが同一の場合、MDE はレコードに、自然キーの最新のメタデータインスタンスの instance_id を挿入します。

インスタンスオブジェクトが同一でない場合、MDE は proto レコードによって提供されるメタデータインスタンスを使用して、指定された自然キーの新しいメタデータインスタンスを作成します。MDE は、新しく作成されたインスタンスの instance_id をレコードに挿入します。

インスタンス値でメタデータ instance_id を解決することは、エッジソースが完全修飾メッセージを配信する場合に特に便利です。このメタデータインスタンスの解決方法を使用すると、既存のインスタンスを参照できるだけでなく、新しいメタデータインスタンスを動的に作成することもできます。

既存のインスタンスを値で参照する

バケット番号 1 の asset という名前のタグメタデータバケット内のメタデータインスタンスの例:

[
  {
    "instance_id": "a614e25d-fded-41c3-9a56-3222cd30070d",
    "bucket_number": "1",
    "bucket_name": "asset",
    "bucket_version": "1",
    "natural_key": "s-446-pressure",
    "instance": {
      "machineName": "Stamping M. 446"
    },
    "created_timestamp": "2023-06-27 20:00:29.603000 UTC"
  },
  {
    "instance_id": "6cfdf894-2fb6-4951-82c6-c4eada587529",
    "bucket_number": "1",
    "bucket_name": "asset",
    "bucket_version": "1",
    "natural_key": "s-446-pressure",
    "instance": {
      "machineName": "Stamping Machine 446"
    },
    "created_timestamp": "2023-06-28 20:00:29.632000 UTC"
  }
]

次のソースメッセージがあるとします。

{
  "sensor": "pressure",
  "machine": "s-446",
  "timestamp": "1687973092857",
  "machineName": "Stamping Machine 446",
  "value": 24
}

次の Whistle スクリプト:

package mde

var tagName: $root.machine + "-" + $root.sensor;

[
    {
        tagName: tagName;
        data: {
            numeric: $root.value;
        };
        timestamps: {
            eventTimestamp: $root.timestamp;
        }
        cloudMetadata: [{
            bucketReference: {
                bucketName: "asset";
                version: 1;
            }
            instance: {
              // optional. Since bucketReference points to a tag bucket, if omitted, the natural is inferred to be tagName
              naturalKey: tagName
              attributes: {
                machineName: $root.machineName;
              }
            }
        }]
    }
]

Whistle スクリプトを適用すると、次の proto レコードが生成されます。

[
  {
    "tagName": "s-446-pressure",
    "data": {
      "numeric": 24
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    },
    "cloudMetadata": [
      {
        "bucketReference": {
          "bucketName": "asset",
          "number": 1
        },
        "naturalKey": "s-446-pressure",
        "attributes": {
          "machineName": "Stamping Machine 446"
        }
      }
    ]
  }
]

MDE が proto レコードの処理を完了すると、BigQuery で次のレコード（行）が生成されます（BigQuery シンクとメタデータマテリアライズが有効になっている場合）。

[
  {
    "id": "6e008960-7f25-4418-899c-75b05c3d3186",
    "tag_name": "s-446-pressure",
    "type_version": "1",
    "event_timestamp": "2023-06-28 17:24:52.526000 UTC",
    "value": "24",
    "embedded_metadata": {},
    "materialized_cloud_metadata": {
      "asset": {
        "machineName": "Stamping Machine 446"
      }
    },
    "cloud_metadata_ref": {
      "asset": {
        "instance_id": "6cfdf894-2fb6-4951-82c6-c4eada587529"
      }
    },
    "event_timestamp": "2023-06-28 17:24:53.526000 UTC",
    "source_message_id": "8511923697775002"
  }
]

値による新しいインスタンスの作成

proto レコードで指定されたメタデータインスタンスが、指定された自然キーの最新のメタデータインスタンスと同一でない場合、MDE は新しいインスタンスを作成します。

バケットの instanceOverwriteMode 設定を使用して、新しいインスタンスの作成方法を構成できます。

instanceOverwriteMode が true に設定されている場合、新しいインスタンスは proto レコードで指定されたインスタンスオブジェクトから作成されます。新しいインスタンスは、バケットのスキーマ検証に合格すると、メタデータバケットに保存されます。
instanceOverwriteMode が false に設定されている場合、新しいインスタンスは、自然キーの最新のインスタンスと proto レコードで指定されたインスタンスオブジェクトをマージすることで作成されます。結果のオブジェクトは、バケットのスキーマ検証に合格した場合、メタデータバケットに新しいメタデータインスタンスとして保存されます。

たとえば、バケット番号 1 の asset という名前のタグメタデータバケットに次のメタデータインスタンスがあるとします。

[
  {
    "instance_id": "a614e25d-fded-41c3-9a56-3222cd30070d",
    "bucket_number": "1",
    "bucket_name": "asset",
    "bucket_version": "1",
    "natural_key": "s-446-pressure",
    "instance": {
      "machineName": "Stamping M. 446"
    },
    "created_timestamp": "2023-06-27 20:00:29.603000 UTC"
  }
]

次のソースメッセージ:

{
  "sensor": "pressure",
  "machine": "s-446",
  "timestamp": "1687973092857",
  "machineName": "Stamping Machine 446",
  "value": 24
}

次の Whistle スクリプトを使用します。

package mde

var tagName: $root.machine + "-" + $root.sensor;

[
    {
        tagName: tagName;
        data: {
            numeric: $root.value;
        };
        timestamps: {
            eventTimestamp: $root.timestamp;
        }
        cloudMetadata: [{
            bucketReference: {
                bucketName: "asset";
                number: 1;
            }
            instance: {
              // optional. Since bucketReference points to a tag bucket, if omitted, the natural is inferred to be tagName
              naturalKey: tagName
              attributes: {
                machineName: $root.machineName;
              }
            }
        }]
    }
]