常用构建基块 > 数据库连接构建基块 > 在查询服务中使用 JSON 筛选器
在查询服务中使用 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 - 数据库中的一个或多个相关值
• alias - 查询服务在查询时所依据的数据形状的别名。如果指定了别名，则必须在 select、filters、joins 和 sorts 键中使用 alias。
• function：
◦ MIN
◦ MAX
◦ COUNT - DATETIME 字段不支持。
◦ AVG
◦ SUM
• groupBy
* 
在以下示例筛选器中，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"
}
}
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 筛选器。
这对您有帮助吗?