在查询服务中使用 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 键中,可以从由查询返回的特定数据形状中选择特定字段。构造一个 JSON 数组,其中每个对象对于查询返回的字段指定 dataShapeName 和 fieldName。dataShapeName 可以是主要数据形状 (即正在执行服务的数据形状) 的名称,也可以是通过连接包含在查询中的另一个数据形状的名称。如果为数据形状指定了 alias,则可以随时使用 alias 在 select 键内引用该特定数据表。如果没有为数据形状定义 alias,则查询将默认使用针对该数据表生成的唯一别名值。只要未指定 alias,且 JSON 引用了此数据形状,都会使用为该数据表生成的唯一别名值。
使用 as 时,输出信息表会通过将 as 值用作字段名称为该 select 键添加字段。
函数 (
MIN、
MAX、
COUNT、
AVG 和
SUM) 可在
select 键中使用。
此处提供了一个 JSON 筛选器示例,其中包含
COUNT 函数。
|
如果在 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 事物的 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 的 JSON 数组将多个筛选器串在一起,各个筛选器之间用逗号分隔,并通过 AND 或 OR 运算符对其进行连接。每个筛选器指定一个 dataShapeName、fieldName、type 以及 value 或 values (用于 IN 运算符)。然后必须在另一个 filters 键下将单一和多个筛选器分成一组。
dataShapeName 可以是主要数据形状 (即正在执行服务的数据形状) 的名称,也可以是通过连接包含在查询中的另一个数据形状的名称。如果没有为筛选器指定 dataShapeName,则假定为正在执行服务的数据形状。如果为数据形状指定了 alias,则可以随时使用 alias 在 filters 键内引用该特定数据表。 如果没有为数据形状定义 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 键用于根据特定的数据形状字段 (dataShapeName 和 fieldName) 对查询结果进行排序,排序可以是升序或降序 (isAscending),并可控制筛选器是否区分大小写 (isCaseSensitive)。您可以包括数组中的多个排序对象 (以逗号分隔) 来对多个字段进行排序。
dataShapeName 可以是主要数据形状 (即正在执行服务的数据形状) 的名称,也可以是通过连接包含在查询中的另一个数据形状的名称。如果未指定 dataShapeName,则假定为正在执行服务的数据形状。如果为数据形状指定了 alias,则可以随时使用 alias 在 sorts 键内引用该特定数据表。 如果没有为数据形状定义 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
}
]
}
连接
连接用于根据数据形状之间的相关字段,将两个或多个数据形状中的行组合在一起。要在选择、排序或筛选键中使用有关数据形状的字段,请通过连接将这些数据形状 (而非主要数据形状) 包括在查询中。
每个连接都由连接类型 (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,则可以随时使用 alias 在 groupBy 键内引用该特定数据表。 如果没有为数据形状定义 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 键后,必须在 select 键中指定 localizedFieldName,同时指定 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。
• 仅对 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 数据形状执行查询时使用,其中所述数据形状作为查询的主要数据形状。此筛选器包括针对 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 筛选器。