在查詢服務中使用 JSON 篩選器

通用建構區塊 > 資料庫連線建構區塊 > 在查詢服務中使用 JSON 篩選器

在查詢服務中使用 JSON 篩選器

JSON 篩選器可在許多查詢服務中使用。以下幾部份內容說明了如何在使用可選 filter 輸入參數的任意查詢服務中使用這些 JSON 篩選器。

受支援的索引鍵與運算子

JSON 篩選器中支援下列索引鍵與運算子：

• select

◦ as

◦ localizedFieldName

• 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 - 資料庫中的一個或多個相關值

• alias - 查詢服務所查詢之資料形式的別名。指定了別名時，您必須使用 select、filters、joins 與 sorts 索引鍵中的 alias。

• function：

◦ MIN

◦ MAX

◦ COUNT - DATETIME 欄位不支援。

◦ AVG

◦ SUM

• groupBy

• locale

在下列範例篩選器中，PTC.SCA.SCO.JobOrderProcessingResourceRequirement 與 PTC.SCA.SCO.JobOrder 中的 Name 欄位是已新增至資料形式的自訂內容。欲如圖所示使用篩選器，必須將這些欄位新增至資料形式。

在 JSON 篩選器中指定自訂內容時，您可為物件指定主要資料形式，如下列範例所示。您不需要指定用來新增自訂內容的相關 _AP 資料形式。

若需進一步資訊，可參閱將自訂內容新增至資料模型實體。

select

在 select 索引鍵中，您可以從希望查詢所回傳的特定資料形式中選取特定欄位。建構一個 JSON 陣列，其中每個物件會針對查詢所回傳的欄位指定 dataShapeName 與 fieldName。dataShapeName 可以是主要資料形式 (正在執行服務的資料形式) 的名稱，也可以是透過連接包括在查詢中的其他資料形式的名稱。如果為資料形式指定 alias，當您想參考 select 索引鍵中的特定資料表時，請使用 alias。若未針對資料形式定義 alias，查詢預設會針對該資料表使用已產生的唯一別名值。當您未指定 alias 且 JSON 參考相同資料形式時，會針對該資料表使用相同的已產生唯一別名值。

使用 as 時，輸出資料負載會為該 select 索引鍵新增欄位，且使用 as 值作為欄位名稱。

函數 (MIN、MAX、COUNT、AVG、SUM) 可在 select 索引鍵中使用。此處提供了包含 COUNT 函數的 JSON 篩選器範例。

如果在 select 索引鍵中使用彙總函數，且 select 索引鍵中有多個 select 物件，則在篩選器中也必須使用 groupBy，否則查詢會失敗。

例如，可以在 GetJobOrders 服務的 JSON 篩選器中使用下列 select 索引鍵，來回傳工作訂單處理資源需求的名稱、工作訂單的名稱與 ID，以及處理資源的名稱：

在上述範例中，PTC.SCA.SCO.JobOrderProcessingResourceRequirement 與 PTC.SCA.SCO.JobOrder 的 Name 欄位都是新增至資料形式的額外屬性。

PTC.DBConnection.QueryUtils 物件上的 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 參考相同資料形式時，會針對該資料表使用相同的已產生唯一別名值。

例如，可以在 GetHistoricalData 服務的 JSON 篩選器中使用下列 filters 索引鍵，來回傳其中已建立或更新工作订单之歷史資料資料庫表格中的全部結果：

{
"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 參考相同資料形式時，會針對該資料表使用相同的已產生唯一別名值。

例如，可以在 GetJobOrders 服務的 JSON 篩選器中使用下列 sorts 索引鍵，來按工作訂單處理資源需求的名稱以遞增順序排序，然後按工作訂單名稱以遞減順序排序 (假設工作訂單處理資源需求透過連接包括在查詢中)。

{
"sorts":[
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name",
"isAscending": true,
"isCaseSensitive": false
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name",
"isAscending": false,
"isCaseSensitive": false
}
]
}

joins

連接可用於根據資料形式之間的相關欄位合併兩個或多個資料形式所在的列。欲在 select、sort 或 filter 索引鍵中使用資料形式的欄位，請使用連接將這些資料形式 (主要資料形式除外) 包括在查詢中。

每個連接均由連接類型 (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 值。

例如，可以在 GetJobOrders 服務的 JSON 篩選器中使用下列 joins 索引鍵來回傳工作訂單的 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"
}
}

地區設定

locale 鍵可讓您在查詢結果中傳回當地語系化輸出。針對 locale 值，指定您要輸出的地區設定。地區設定值與 Language 表格中的 code 欄位對應。如需詳細資訊，請參閱[link to topic explaining the DB localization functionality, forthcoming]。

指定 locale 鍵時，localizedFieldName 必須在 select 鍵中與 fieldName 和 dataShapename 一起指定，以提供並命名在查詢輸出中用於當地語系化權杖的欄。

例如，您可以在 JSON 篩選器中使用下列 locale 與 select 鍵，以使查詢服務傳回法文的原因代碼名稱。

{
"locale":"fr",
"select":[
{
"fieldName":"displayName_Token",
"dataShapeName":"PTC.ReasonCode.Reason",
"localizedFieldName":"reason_name_localized"
}
],
"filters":{
"filters":[
{
"dataShapeName":"PTC.ReasonCode.Reason",
"fieldName":"name",
"type":"EQ",
"value":"Unknown"
}
],
"type":"AND"
}
}

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。

• 僅針對 ID 值為 WC1 的那些處理資源篩選結果。

• 回傳的結果適用於滿足下列條件的記錄：工作訂單的 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 資料形式時，作為查詢的主要資料形式使用。此篩選器包括 PTC.ReasonCode.ReasonCategory 資料形式的自我連接 (使用 sourceAlias 與 targetAlias、as 索引鍵、COUNT 函數與 groupBy)。

{
"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 說明中心內的查詢服務的查詢參數。註記 - JSON 篩選器不支援該主題中討論的 Near 與 NotNear 篩選器。

這是否有幫助?