クエリーサービスでの JSON フィルタの使用
JSON フィルタは、多くのクエリーサービスで使用できます。次のセクションでは、オプションの filter 入力パラメータを使用するいずれかのクエリーサービスで、これらの JSON フィルタを使用する方法について説明します。
サポートされるキーと演算子
JSON フィルタでは、以下のキーおよび演算子を使用できます。
• select
◦ as
• filters
◦ 次の type 値 (論理演算子) を使用します。
▪ EQ - 指定値に等しい
▪ NE - 指定値に等しくない
▪ LT - 指定値より小さい
▪ LE - 指定値以下
▪ GT - 指定値より大きい
▪ GE - 指定値以上
▪ AND - 論理積
▪ OR - 論理和
▪ IN - いずれかに一致
▪ NOTIN - いずれかに一致しない
▪ LIKE - 類似
▪ NOTLIKE - 類似しない
▪ BETWEEN - 指定値の間
▪ NOTBETWEEN - 指定値の間ではない
▪ TAGGED - タグ付き
▪ NOTTAGGED - タグなし
▪ MATCHES - 一致
▪ NOTMATCHES - 一致しない
▪ MISSINGVALUE - 欠落している値
▪ NOTMISSINGVALUE - 欠落していない値
◦ isCaseSensitive - true の場合は比較 (大文字と小文字を区別する) を行います。EQ、NE、LIKE、NOTLIKE、MATCHES、および NOTMATCHES とともに使用されます。
• sorts
◦ isAscending - true の場合は昇順並べ替え、false の場合は降順並べ替え
◦ isCaseSensitive - true の場合は大文字小文字を区別する並べ替え
• joins (次の type 値 (結合タイプ) を使用):
◦ INNER
◦ LEFT
◦ RIGHT
◦ FULL
• dataShapeName - 列 (fieldName) が存在するデータシェイプの名前
• fieldName - データシェイプの列の名前
• value または values - データベース内の 1 つまたは複数の目的の値
• alias - クエリーサービスがクエリーを実行しているデータシェイプのエイリアス。エイリアスを指定する場合は、alias を select、filters、joins、および sorts キーで使用する必要があります。
• function:
◦ MIN
◦ MAX
◦ COUNT - DATETIME フィールドではサポートされていません。
◦ AVG
◦ SUM
• groupBy
|
次のフィルタの例では、PTC.SCA.SCO.JobOrderProcessingResourceRequirement と PTC.SCA.SCO.JobOrder の両方の Name フィールドは、これらのデータシェイプに追加されたカスタムプロパティです。フィルタを以下に示すように使用するには、これらのフィールドをデータシェイプに追加する必要があります。
JSON フィルタでカスタムプロパティを指定する場合、次の例に示すように、オブジェクトのプライマリデータシェイプを指定できます。カスタムプロパティを追加ために使用される、関連する _AP データシェイプを指定する必要はありません。
|
Select
select キーを使用すると、特定のデータシェイプから特定のフィールドを選択して、クエリーによって返すことができます。各オブジェクトがクエリーによって返されるフィールドの dataShapeName および fieldName を指定する、JSON 配列を構築します。dataShapeName は、プライマリデータシェイプの名前 (サービスが実行されているデータシェイプ)、または結合によってクエリーに含まれる別のデータシェイプの名前にすることができます。データシェイプに alias が指定されている場合、select キー内でその特定のデータテーブルを参照する際は常に alias を使用します。alias がデータシェイプに定義されていない場合、クエリーはデフォルトでそのデータテーブルに対して生成された一意のエイリアス値を使用します。alias を指定せず、JSON がその同じデータシェイプを参照する場合は常に、そのデータテーブルに対して生成された同じ一意のエイリアス値が使用されます。
as を使用すると、出力インフォテーブルは、フィールド名として as 値を使用してその select キーに対するフィールドを追加します。
関数 (
MIN、
MAX、
COUNT、
AVG、
SUM) は
select キー内で使用できます。
COUNT 関数を含む JSON フィルタの例については、
ここを参照してください。
|
select キーで集計関数を使用していて、select キーに複数の select オブジェクトがある場合は、フィルタでも groupBy を使用する必要があります。使用しない場合、クエリーは失敗します。
|
たとえば、次の select キーを GetJobOrders サービスの JSON フィルタで使用して、ジョブオーダー処理リソース要件の名前、ジョブオーダーの名前と ID、および処理リソースの名前を返すことができます。
{
"select": [
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name"
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name"
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "ID"
},
{
"dataShapeName": "PTC.SCA.SCO.ProcessingResource",
"fieldName": "Name"
}
]
}
上記の例では、PTC.SCA.SCO.JobOrderProcessingResourceRequirement と PTC.SCA.SCO.JobOrder の両方に対する Name フィールドは、データシェイプに追加されたその他のプロパティです。
|
PTC.DBConnection.QueryUtils Thing の BuildSelectFromDataShapes サービスを使用して、指定したデータシェイプの select キーを構築できます。次のサービス入力の例では、PTC.SCA.SCO.JobOrderPRocessingResourceRequirement、PTC.SCA.SCO.JobORder、PTC.SCA.SCO.ProcessingResource データシェイプのための select キーが生成されます:
{ "dataShapes": [{ "name": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement" }, { "name": "PTC.SCA.SCO.JobOrder" }, { "name": "PTC.SCA.SCO.ProcessingResource" } ] }
|
Filters
filters キーを使用すると、特定の値に一致するレコードのクエリー結果をフィルタできます。filters と呼ばれる JSON 配列を作成する、各フィルタをコンマで区切る、およびフィルタを AND または OR 演算子で結合することにより、複数のフィルタをつなぎ合わせることができます。各フィルタは、dataShapeName、fieldName、type、および value または values (IN 演算子の場合) を指定します。次に、単一フィルタおよび複数のフィルタの両方を別の filters キーでグループ化しなければなりません。
dataShapeName は、プライマリデータシェイプの名前 (サービスが実行されているデータシェイプ)、または結合によってクエリーに含まれる別のデータシェイプの名前にすることができます。フィルタに dataShapeName が指定されていない場合、サービスが実行されるデータシェイプが指定されていると見なされます。データシェイプに alias が指定されている場合、filters キー内でその特定のデータテーブルを参照する際は常に alias を使用します。alias がデータシェイプに定義されていない場合、クエリーはデフォルトでそのデータテーブルに対して生成された一意のエイリアス値を使用します。alias を指定せず、JSON がその同じデータシェイプを参照する場合は常に、そのデータテーブルに対して生成された同じ一意のエイリアス値が使用されます。
たとえば、次の filters キーを GetHistoricalData サービスの JSON フィルタで使用して、ジョブオーダーが作成または更新された履歴データのデータベーステーブル内のすべての結果を返すことができます:
{
"filters": {
"filters": [
{
"dataShapeName": "PTC.DBConnection.HistoricalData",
"fieldName": "DataShapeName",
"type": "EQ",
"value": "PTC.SCA.SCO.JobOrder",
"isCaseSensitive": true
},
{
"dataShapeName": "PTC.DBConnection.HistoricalData",
"fieldName": "ReferenceKey",
"type": "IN",
"values": [1,2]
}
],
"type": "AND"
}
}
Sorts
sorts キーを使用すると、特定のデータシェイプフィールド (dataShapeName および fieldName) に基づいてクエリー結果を並べ替えたり、昇順または降順 (isAscending) で並べ替えたり、フィルタで大文字と小文字を区別 (isCaseSensitive) するかどうかを指定できます。配列内に複数の並べ替えオブジェクトをコンマで区切って含めることによって、複数のフィールドに基づいて並べ替えることができます。
dataShapeName は、プライマリデータシェイプの名前 (サービスが実行されているデータシェイプ)、または結合によってクエリーに含まれる別のデータシェイプの名前にすることができます。dataShapeName が指定されていない場合、サービスが実行されるデータシェイプが指定されていると見なされます。データシェイプに alias が指定されている場合、sorts キー内でその特定のデータテーブルを参照する際は常に alias を使用します。alias がデータシェイプに定義されていない場合、クエリーはデフォルトでそのデータテーブルに対して生成された一意のエイリアス値を使用します。alias を指定せず、JSON がその同じデータシェイプを参照する場合は常に、そのデータテーブルに対して生成された同じ一意のエイリアス値が使用されます。
たとえば、次の sorts キーを GetJobOrders サービスの JSON フィルタで使用して、ジョブオーダー処理リソース要件の名前によって結果を昇順に並べ替え、その後、ジョブオーダー名によって降順に並べ替えることができます (ジョブオーダー処理リソース要件が、結合によってクエリーに含まれていると仮定します)。
{
"sorts":[
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name",
"isAscending": true,
"isCaseSensitive": false
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name",
"isAscending": false,
"isCaseSensitive": false
}
]
}
結合
結合を使用して、データシェイプ間の関連フィールドに基づいて、2 つ以上のデータシェイプの行を結合します。選択、並べ替え、またはフィルタのキーでデータシェイプに関するフィールドを使用するには、結合を使用して、それらのデータシェイプ (プライマリデータシェイプ以外) をクエリーに含めるようにします。
各結合は、結合タイプ (type)、ソースまたは左側のデータシェイプとフィールド名 (sourceDataShapeName および sourceFieldName)、およびターゲットまたは右側のデータシェイプとフィールド名 (targetDataShapeName および targetFieldName) から構成されています。
結合のソースおよびターゲットデータシェイプに対して、sourceAlias と targetAlias をそれぞれ使用します。targetAlias は一意でなければなりません。sourceAlias は、クエリーのメイン alias と前の targetAlias のいずれかを参照する必要があります。データシェイプに sourceAlias と targetAlias のいずれも定義されていない場合、クエリーはデフォルトで、そのデータテーブルに対して生成された一意のエイリアス値を使用します。soureAlias と targetAlias のいずれも指定せず、JSON がその同じデータシェイプを参照する場合、そのデータテーブルに対して生成された同じ一意のエイリアス値が使用されます。
INNER、LEFT、RIGHT、および FULL のタイプの結合がサポートされています。
• INNER - 内部結合は、両方のデータシェイプに一致する値を持つすべてのレコードを返します。
• LEFT - 左結合では、左側 (ソース) データシェイプのすべてのレコードと、右側 (ターゲット) データシェイプからの一致するレコードが返されます。一致するものがない場合、結合の右側 (ターゲット) の結果は NULL になります。
• RIGHT - 右結合では、右側 (ターゲット) データシェイプのすべてのレコードと、左側 (ソース) データシェイプからの一致するレコードが返されます。一致するものがない場合、結合の左側 (ソース) の結果は NULL になります。
• FULL - フル結合では、左側 (ソース) または右側 (ターゲット) のデータシェイプのいずれかに一致する、すべてのレコードを返します。
結合の sourceAlias と targetAlias 値が異なる場合、自己結合がサポートされています。自己結合がプライマリデータシェイプ上にある場合、sourceAlias はプライマリデータシェイプの alias 値と一致する必要があります。
たとえば、次の joins キーを GetJobOrders サービスの JSON フィルタで使用して、ジョブオーダーの UID がジョブオーダー処理リソース要件の JobOrderUID フィールドと一致する場合、およびジョブオーダー処理リソース要件の ProcessingResourceUID フィールドが処理リソースの UID フィールドと一致する場合に、すべてのレコードを返すことができます。
{
"joins": [
{
"type": "INNER",
"sourceDataShapeName": "PTC.SCA.SCO.JobOrder",
"sourceFieldName": "UID",
"targetDataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"targetFieldName": "JobOrderUID"
},
{
"type": "INNER",
"sourceDataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"sourceFieldName": "ProcessingResourceUID",
"targetDataShapeName": "PTC.SCA.SCO.ProcessingResource",
"targetFieldName": "UID"
}
]
}
グループ分け
groupBy キーを使用すると、出力内の行を特定のデータシェイプフィールド (dataShapeName および fieldName) に基づいてサマリー行に集約できます。dataShapeName は、プライマリデータシェイプの名前 (サービスが実行されているデータシェイプ)、または結合によってクエリーに含まれる別のデータシェイプの名前にすることができます。dataShapeName が指定されていない場合、サービスが実行されるデータシェイプが指定されていると見なされます。groupBy キーは多くの場合、関数 (MIN、MAX、COUNT、AVG、SUM) で使用されます。
データシェイプに alias が指定されている場合、groupBy キー内でその特定のデータテーブルを参照する際は常に alias を使用します。alias がデータシェイプに定義されていない場合、クエリーはデフォルトでそのデータテーブルに対して生成された一意のエイリアス値を使用します。alias を指定せず、JSON がその同じデータシェイプを参照する場合は常に、そのデータテーブルに対して生成された同じ一意のエイリアス値が使用されます。
たとえば、groupBy キーをクエリーサービスの JSON フィルタで使用すると、理由タイプの名前によって結果をグループ化できます。
{
"groupBy": [
{
"dataShapeName": "PTC.ReasonCode.ReasonType",
"fieldName": "name"
}
}
JSON フィルタの例
例 1: 次の例は、GetHistoricalData サービスで使用できるフィルタを示しています。このフィルタは、ジョブオーダーが作成された履歴データのデータベース内のすべての結果を返し、各ジョブオーダーが作成された時間の結果を昇順に並べ替えます。
{
"filters": {
"filters": [
{
"dataShapeName": "PTC.DBConnection.HistoricalData",
"fieldName": "DataShapeName",
"type": "EQ",
"value": "PTC.SCA.SCO.JobOrder"
},
{
"dataShapeName": "PTC.DBConnection.HistoricalData",
"fieldName": "ReferenceKey",
"type": "EQ",
"value": 1
}
],
"type": "AND"
},
"sorts": [
{
"fieldName": "TimeStamp",
"isAscending": true,
"isCaseSensitive": false
}
]
}
例 2: 次の例は、GetJobOrders サービスで使用できるフィルタを示しています。このフィルタを使用した場合、以下のようになります。
• 各結果について、ジョブオーダーの Name と ID、関連する処理リソースの Name、および関連するジョブオーダー処理リソース要件の Name が返されます。
• 結果は、WC1 の ID 値を持つ処理リソースに対してのみフィルタされます。
• 返される結果は、ジョブオーダーの UID がジョブオーダー処理リソース要件の JobOrderUID フィールドと一致し、ジョブオーダー処理リソース要件の ProcessingResourceUID フィールドが処理リソースの UID フィールドと一致するレコードに対する結果です。
• 結果は、ジョブオーダー処理リソース要件の Name によって昇順に並べ替えられ、次にジョブオーダーの Name によって降順に並べ替えられます。
{
"select": [
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name"
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name"
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "ID"
},
{
"dataShapeName": "PTC.SCA.SCO.ProcessingResource",
"fieldName": "Name"
}
],
"filters": {
"filters": [
{
"dataShapeName": "PTC.SCA.SCO.ProcessingResource",
"fieldName": "ID",
"type": "EQ",
"value": "WC1"
}
],
"type": "AND"
},
"joins": [
{
"type": "INNER",
"sourceDataShapeName": "PTC.SCA.SCO.JobOrder",
"sourceFieldName": "UID",
"targetDataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"targetFieldName": "JobOrderUID"
},
{
"type": "INNER",
"sourceDataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"sourceFieldName": "ProcessingResourceUID",
"targetDataShapeName": "PTC.SCA.SCO.ProcessingResource",
"targetFieldName": "UID"
}
],
"sorts":[
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name",
"isAscending": true,
"isCaseSensitive": false
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name",
"isAscending": false,
"isCaseSensitive": false
}
]
}
例 3: 次の例は、PTC.ReasonCode.ReasonCategory データシェイプに対してクエリーのプライマリデータシェイプとしてクエリーを実行する場合に使用できるフィルタを示しています。このフィルタには、as キー、COUNT 関数、および groupBy が含まれています。
{
"select": [
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"as": "count",
"function": "COUNT"
},
{
"dataShapeName": "PTC.ReasonCode.ReasonType",
"fieldName": "name",
"as": "typeName"
}
],
"joins": [
{
"type": "LEFT",
"sourceDataShapeName": "PTC.ReasonCode.ReasonCategory",
"sourceFieldName": "reasonTypeUid",
"targetDataShapeName": "PTC.ReasonCode.ReasonType",
"targetFieldName": "uid"
}
],
"groupBy": [
{
"dataShapeName": "PTC.ReasonCode.ReasonType",
"fieldName": "name"
}
]
}
例 4: 次の例は、PTC.ReasonCode.ReasonCategory データシェイプに対してクエリーのプライマリデータシェイプとしてクエリーを実行する場合に使用できるフィルタを示しています。このフィルタには、sourceAlias と targetAlias、as キー、COUNT 関数、および groupBy を使用した、PTC.ReasonCode.ReasonCategory データシェイプに対する自己結合が含まれています。
{
"alias": "ReasonCategory1",
"select": [
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"as": "name",
"alias": "ReasonCategory1"
},
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"as": "name2",
"alias": "ReasonCategory2"
},
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"as": "countName",
"function": "COUNT",
"alias": "ReasonCategory1"
}
],
"filters": {
"filters": [
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"type": "EQ",
"value": "Scrap",
"alias": "ReasonCategory1"
}
],
"type": "AND"
},
"joins": [
{
"type": "LEFT",
"sourceDataShapeName": "PTC.ReasonCode.ReasonCategory",
"sourceFieldName": "uid",
"sourceAlias": "ReasonCategory1",
"targetDataShapeName": "PTC.ReasonCode.ReasonCategory",
"targetFieldName": "uid",
"targetAlias": "ReasonCategory2"
},
{
"type": "LEFT",
"sourceDataShapeName": "PTC.ReasonCode.ReasonCategory",
"sourceFieldName": "reasonTypeUid",
"sourceAlias": "ReasonCategory1",
"targetDataShapeName": "PTC.ReasonCode.ReasonType",
"targetFieldName": "uid",
"targetAlias": "ReasonType"
}
],
"groupBy": [
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"alias": "ReasonCategory1"
},
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"alias": "ReasonCategory2"
}
]
}
クエリーでのフィルタの使用に関するその他の例については、
ThingWorx ヘルプセンターの
クエリーサービス用クエリーパラメータ を参照してください。注記 - 前述のトピックで説明している
Near および
NotNear のフィルタは、JSON フィルタではサポートされていません。