Uso de filtros JSON en servicios de consulta
Los filtros JSON se pueden utilizar en muchos servicios de consulta. En las siguientes secciones se explica cómo utilizar estos filtros JSON en cualquiera de los servicios de consulta que emplean el parámetro de entrada filter opcional.
Claves y operadores soportados
En los filtros JSON se admiten las siguientes claves y operadores:
select
as
filters
Con los siguientes valores de type (operadores lógicos):
EQ: igual a
NE: no igual a
LT: menor que
LE: menor o igual que
GT: mayor que
GE: mayor o igual que
AND: y
OR: o
IN: en
NOTIN: no en
LIKE: como
NOTLIKE: no como
BETWEEN: entre
NOTBETWEEN: no entre
TAGGED: etiquetado
NOTTAGGED: sin etiqueta
MATCHES: coincide con
NOTMATCHES: no coincide con
MISSINGVALUE: valor faltante
NOTMISSINGVALUE: no falta valor
isCaseSensitive: comparación con distinción entre mayúsculas y minúsculas si es verdadero; se utiliza con EQ, NE, LIKE, NOTLIKE, MATCHES y NOTMATCHES.
sorts
isAscending: clasificación ascendente si es verdadero, clasificación descendente si es falso
isCaseSensitive: clasificación con distinción entre mayúsculas y minúsculas si es verdadero
joins, con los siguientes valores type (tipos de unión):
INNER
LEFT
RIGHT
FULL
dataShapeName: nombre de la definición de datos en la que reside la columna (fieldName)
fieldName: nombre de la columna en la definición de datos
value o values: valor o valores de interés en la base de datos
alias: alias para la definición de datos con la que consulta el servicio de consultas. Cuando se especifica un alias, se debe utilizar alias en las claves select, filters, joins y sorts.
function:
MIN
MAX
COUNT: no se soporta para los campos DATETIME.
AVG
SUM
groupBy
* 
En los siguientes filtros de ejemplo, los campos de Name en PTC.SCA.SCO.JobOrderProcessingResourceRequirement y PTC.SCA.SCO.JobOrder son propiedades personalizadas que se han añadido a esas definiciones de datos. Para utilizar los filtros como se muestra, se deben añadir estos campos a las definiciones de datos.
Al especificar propiedades personalizadas en un filtro JSON, se puede especificar la definición de datos principal del objeto, tal como se muestra en estos ejemplos. No es necesario especificar la definición de datos _AP relacionada que se utiliza para añadir la propiedad personalizada.
select
En una clave select, se pueden seleccionar campos específicos de determinadas definiciones de datos que la consulta debe devolver. Cree una matriz JSON en la que cada objeto especifique dataShapeName y fieldName para un campo que devolverá la consulta. dataShapeName puede ser el nombre de la definición de datos principal (la definición de datos en la que se ejecuta el servicio) o el nombre de otra definición de datos que se incluye en la consulta mediante una unión. Si se especifica alias para una definición de datos, utilice alias siempre que se desee hacer referencia a esa tabla de datos específica en la clave select. Si no se ha definido ningún valor de alias para una definición de datos, la consulta utilizará por defecto un valor de alias único generado para dicha tabla de datos. Si en algún momento no se especifica alias y el JSON hace referencia a la misma definición de datos, se utiliza el mismo valor de alias único generado para esa tabla de datos.
Cuando se utiliza as, la infotable de salida añade un campo para esa clave select utilizando el valor as como el nombre de campo.
Las funciones (MIN, MAX, COUNT, AVG, SUM) se pueden utilizar en una clave select. Aquí encontrará un filtro JSON de ejemplo en el que se incluye la función COUNT.
* 
Si se utiliza una función de agregado en la clave select y hay más de un objeto select en la clave select, también se debe utilizar groupBy en el filtro o la consulta fallará.
Por ejemplo, la siguiente clave select se puede utilizar en un filtro JSON para que el servicio GetJobOrders devuelva el nombre de un requisito de recursos de procesamiento de órdenes de trabajo, el nombre y el ID de una orden de trabajo y el nombre de un recurso de procesamiento:
{
"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"
}
]
}
En el ejemplo anterior, los campos de Name en PTC.SCA.SCO.JobOrderProcessingResourceRequirement y PTC.SCA.SCO.JobOrder son propiedades adicionales que se han añadido a las definiciones de datos.
* 
El servicio BuildSelectFromDataShapes de la cosa PTC.DBConnection.QueryUtils se puede utilizar para crear la clave de selección para las definiciones de datos especificadas. En la siguiente entrada de servicio de ejemplo se obtiene una clave de selección para las definiciones de datos PTC.SCA.SCO.JobOrderPRocessingResourceRequirement, PTC.SCA.SCO.JobORder y PTC.SCA.SCO.ProcessingResource:
{
"dataShapes": [{
"name": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement"
},
{
"name": "PTC.SCA.SCO.JobOrder"
},
{
"name": "PTC.SCA.SCO.ProcessingResource"
}
]
}
filters
La clave filters permite filtrar los resultados de la consulta a registros que coincidan con valores específicos. Puede encadenar varios filtros creando matrices JSON llamadas filters, separando cada filtro con una coma y uniéndolos con el operador AND o OR. Cada filtro especifica dataShapeName, fieldName, type y value o values (para el operador IN). Tanto los filtros únicos y filtros distintos deben agruparse bajo otra clave filters.
dataShapeName puede ser el nombre de la definición de datos principal (la definición de datos en la que se ejecuta el servicio) o el nombre de otra definición de datos que se incluye en la consulta mediante una unión. Si no se especifica dataShapeName para el filtro, se presupone la definición de datos con la que se ejecuta el servicio. Si se especifica alias para una definición de datos, utilice alias siempre que se desee hacer referencia a esa tabla de datos específica en la clave filters. Si no se ha definido ningún valor de alias para una definición de datos, la consulta utilizará por defecto un valor de alias único generado para dicha tabla de datos. Si en algún momento no se especifica alias y el JSON hace referencia a la misma definición de datos, se utiliza el mismo valor de alias único generado para esa tabla de datos.
Por ejemplo, la siguiente clave filters se puede utilizar en un filtro JSON para que el servicio GetHistoricalData devuelva todos los resultados de la tabla de base de datos históricos donde se creó o actualizó un trabajo:
{
"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
La clave sorts permite ordenar los resultados de la consulta en función de un campo de definición de datos específico (dataShapeName y fieldName), ordenar en orden ascendente o descendente (isAscending), y determinar si el filtro distingue entre mayúsculas y minúsculas (isCaseSensitive). Se pueden ordenar varios campos mediante la inclusión de varios objetos de clasificación en la matriz, separados por comas.
dataShapeName puede ser el nombre de la definición de datos principal (la definición de datos en la que se ejecuta el servicio) o el nombre de otra definición de datos que se incluye en la consulta mediante una unión. Si no se especifica dataShapeName, se presupone la definición de datos con la que se ejecuta el servicio. Si se especifica alias para una definición de datos, utilice alias siempre que se desee hacer referencia a esa tabla de datos específica en la clave sorts. Si no se ha definido ningún valor de alias para una definición de datos, la consulta utilizará por defecto un valor de alias único generado para dicha tabla de datos. Si en algún momento no se especifica alias y el JSON hace referencia a la misma definición de datos, se utiliza el mismo valor de alias único generado para esa tabla de datos.
Por ejemplo, la siguiente clave sorts se puede utilizar en un filtro JSON con el servicio GetJobOrders para ordenar los resultados por el nombre del requisito de recursos de procesamiento de órdenes de trabajo en orden ascendente y luego por el nombre de orden de trabajo en orden descendente (suponiendo que el requisito de recursos de procesamiento de órdenes de trabajo se incluya en la consulta mediante una unión).
{
"sorts":[
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name",
"isAscending": true,
"isCaseSensitive": false
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name",
"isAscending": false,
"isCaseSensitive": false
}
]
}
joins
Una unión se utiliza para combinar filas de dos o más definiciones de datos en función de un campo relacionado entre las definiciones de datos. Para utilizar los campos de las definiciones de datos en las claves de selección, clasificación o filtro, incluya las definiciones de datos (distintas de la definición de datos principal) en la consulta mediante una unión.
Cada unión está formada por el tipo de unión (type), el origen (la definición de datos izquierda) y el nombre de campo (sourceDataShapeName y sourceFieldName), y el destino (la definición de datos derecha) y el nombre de campo (targetDataShapeName y targetFieldName).
Utilice sourceAlias y targetAlias para las definiciones de datos de origen y destino de la unión, respectivamente. El valor de targetAlias debe ser exclusivo. sourceAlias debe hacer referencia al valor de alias principal para la consulta o a un valor de targetAlias anterior. Si no se ha definido sourceAlias o targetAlias para una definición de datos, la consulta utilizará por defecto un valor de alias único generado para dicha tabla de datos. Si en algún momento no se especifica soureAlias o targetAlias y el JSON hace referencia a la misma definición de datos, se utiliza el mismo valor de alias único generado para esa tabla de datos.
Se admiten los siguientes tipos de uniones: INNER, LEFT, RIGHT y FULL.
INNER: una unión interna devuelve todos los registros que tienen valores coincidentes en ambas definiciones de datos.
LEFT: una unión izquierda devuelve todos los registros de la definición de datos izquierda (origen) y los registros coincidentes de la definición de datos derecha (destino). Si no hay ninguna coincidencia, el resultado del lado derecho (destino) de la unión es NULL.
RIGHT: una unión derecha devuelve todos los registros de la definición de datos derecha (destino) y los registros coincidentes de la definición de datos izquierda (origen). Si no hay ninguna coincidencia, el resultado del lado izquierdo (origen) de la unión es NULL.
FULL: una unión completa devuelve todos los registros en los que hay una coincidencia en la definición de datos izquierda (origen) o derecha (destino).
Las uniones automáticas se soportan cuando los valores de sourceAlias y targetAlias de la unión son diferentes. Si la unión automática se encuentra en la definición de datos principal, sourceAlias debe coincidir con el valor de alias de la definición de datos principal.
Por ejemplo, la siguiente clave joins se puede utilizar en un filtro JSON para que el servicio GetJobOrders devuelva todos los registros en los que el UID en la orden de trabajo coincide con el campo JobOrderUID del requisito de recursos de procesamiento de órdenes de trabajo y donde el campo ProcessingResourceUID del requisito de recursos de procesamiento de órdenes de trabajo coincide con el campo UID del recurso de procesamiento.
{
"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"
}
]
}
Agrupar por
La clave groupBy permite acumular filas en la salida en filas de resumen basadas en un campo de definición de datos específico (dataShapeName y fieldName). dataShapeName puede ser el nombre de la definición de datos principal (la definición de datos en la que se ejecuta el servicio) o el nombre de otra definición de datos que se incluye en la consulta mediante una unión. Si no se especifica dataShapeName, se presupone la definición de datos con la que se ejecuta el servicio. La clave groupBy se utiliza a menudo con las funciones (MIN, MAX, COUNT, AVG, SUM).
Si se especifica alias para una definición de datos, utilice alias siempre que se desee hacer referencia a esa tabla de datos específica en la clave groupBy. Si no se ha definido ningún valor de alias para una definición de datos, la consulta utilizará por defecto un valor de alias único generado para dicha tabla de datos. Si en algún momento no se especifica alias y el JSON hace referencia a la misma definición de datos, se utiliza el mismo valor de alias único generado para esa tabla de datos.
Por ejemplo, la siguiente clave groupBy se puede utilizar en un filtro JSON para que un servicio de consulta agrupe los resultados por el nombre del tipo de motivo.
{
"groupBy": [
{
"dataShapeName": "PTC.ReasonCode.ReasonType",
"fieldName": "name"
}
}
Ejemplo de filtros JSON
Ejemplo 1: En el siguiente ejemplo se muestra un filtro que se puede utilizar con el servicio GetHistoricalData. Este filtro devuelve todos los resultados de la base de datos de datos históricos donde se creó una orden de trabajo y, a continuación, ordena los resultados en orden ascendente por el momento en que se creó cada orden de trabajo.
{
"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
}
]
}
Ejemplo 2: En el siguiente ejemplo se muestra un filtro que se puede utilizar con el servicio GetJobOrders. Con este filtro:
Para cada resultado, se devuelven Name y ID de la orden de trabajo, Name del recurso de procesamiento relacionado y Name del requisito de recursos de procesamiento de órdenes de trabajo.
Los resultados se filtran solo para los recursos de procesamiento cuyo valor de ID sea WC1.
Los resultados devueltos son para los registros en los que el UID de la orden de trabajo coincide con el campo JobOrderUID del requisito de recursos de procesamiento de órdenes de trabajo y donde el campo ProcessingResourceUID del requisito de recursos de procesamiento de órdenes de trabajo coincide con el campo UID del recurso de procesamiento.
Los resultados se ordenan por Name del requisito de recursos de procesamiento de órdenes de trabajo en orden ascendente y luego por el Name de la orden de trabajo en orden descendente.
{
"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
}
]
}
Ejemplo 3: en el siguiente ejemplo se muestra un filtro que se puede utilizar al consultar en la definición de datos PTC.ReasonCode.ReasonCategory como la definición de datos principal para la consulta. En este filtro se incluyen las claves as, la función COUNT y 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"
}
]
}
Ejemplo 4: en el siguiente ejemplo se muestra un filtro que se puede utilizar al consultar en la definición de datos PTC.ReasonCode.ReasonCategory como la definición de datos principal para la consulta. Este filtro incluye una unión automática con la definición de datos PTC.ReasonCode.ReasonCategory mediante sourceAlias y targetAlias, las teclas as, la función COUNT y 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"
}
]
}
Para obtener más ejemplos sobre el uso de filtros en consultas, consulte Parámetro de consulta para servicios de consulta en el Centro de ayuda de ThingWorx. Nota: los filtros Near y NotNear descritos en ese tema no se admiten en estos filtros JSON.
¿Fue esto útil?