Propiedades indexadas
En ThingWorx 9.3 y versiones posteriores, las propiedades se pueden indexar para permitir consultas más rápidas. Solo se deben indexar las propiedades que no cambian con frecuencia. Por ejemplo, números de modelo, números de serie, ciudades o regiones. Cuando se indexa en ThingWorx, los valores de las propiedades se almacenan en el proveedor de persistencia de propiedad, donde la base de datos los indexa para permitir consultas más rápidas al utilizar las API QueryImplementingThingsOptimized y QueryImplementingThingsOptimizedCount.
Si una consulta incluye solo propiedades indexadas, la consulta se ejecuta únicamente como una consulta de base de datos.
Si una consulta contiene una combinación de propiedades indexadas y no indexadas, ThingWorx determina si la consulta se puede beneficiar de realizar una consulta indexada y la realizará. En este escenario, ThingWorx realiza primero la consulta indexada en la base de datos de propiedades para los campos indexados. Una vez generado el conjunto de resultados, ThingWorx realiza una consulta para las propiedades no indexadas en la caché en memoria. Un ejemplo podría ser si se desea consultar todas las cosas que se encuentran en una ciudad determinada (propiedad indexada) con una temperatura (datos de telemetría, no indexables) por encima de un determinado umbral. ThingWorx realizará primero la consulta para la ciudad en la base de datos y, a continuación, realizará la consulta en los datos de telemetría (temperatura) en la caché en memoria.
Si la consulta solicitada no se puede beneficiar de la indexación, ThingWorx realizará una consulta en la caché en memoria.
Aunque consultar la base de datos ofrecerá con mayor frecuencia un rendimiento superior, en algunos casos, que QueryImplementingThingsOptimized no utilice las consultas de indexación funcionará mejor que si se utilizan. Un caso conocido es cuando la consulta de índice devuelve más del 80 % del número total de cosas del modelo. En estos casos, ThingWorx incluye una "sugerencia" en la consulta para forzar que QueryImplementingThingsOptimized no utilice la consulta de índice y solo se realice una consulta en la caché en memoria. Para obtener más información, consulte las secciones Sugerencias y Prácticas recomendadas que se indican a continuación.
La indexación se soporta en las bases de datos de PostgreSQL, MS SQL y Azure SQL. Si se utiliza H2, se puede modelar y crear la aplicación en H2, pero las propiedades no se indexarán y las ventajas de rendimiento no se verán con las API QueryImplementingThingsOptimized y QueryImplementingThingsOptimizedCount.
La creación o actualización de propiedades indexadas tarda más en almacenarse en la base de datos. El uso del servicio QueryImplementingThingsOptimizedWithTotalCount en la propiedad indexada inmediatamente después de las actualizaciones de la propiedad devuelve resultados incompletos o inesperados. Vuelva a ejecutar el servicio QueryImplementingThingsOptimizedWithTotalCount después de 2 segundos para obtener los resultados correctos.
Identificación de las propiedades de la indexación
Tenga en cuenta lo siguiente al determinar si se debe indexar una propiedad:
• La indexación está limitada a los siguientes tipos base de propiedades: STRING, NUMBER, INTEGER, LONG, BOOLEAN y los tipos base que se almacenan como cadenas.
 |
Los siguientes tipos base se almacenan como cadenas: DATETIME, THINGNAME, USERNAME, GROUPNAME, HYPERLINK, IMAGELINK, MASHUPNAME, MENUNAME, DASHBOARDNAME, TEXT, GUID, NOTIFICATIONCONTENTNAME, NOTIFICATIONDEFINITIONNAME, STYLETHEMENAME y THINGGROUPNAME.
|
• Solo se deben tener en cuenta para la indexación las propiedades con valores que no cambian o que no lo hacen con frecuencia. No se deben tener en cuenta las propiedades que cambian con frecuencia. Entre los ejemplos de propiedades para indexar se incluyen números de modelo o números de serie. También se puede tener en cuenta el equipo fijo, la ciudad, el estado o la región.
|
|
Los datos de telemetría nunca se deben indexar.
|
• ¿Es probable que la propiedad se utilice al llamar a QueryImplementingThingsOptimized? También se almacenan todas las propiedades indexadas, por lo que se debe tener en cuenta si la indexación de una propiedad proporcionará ventajas útiles. Las propiedades persistentes suponen una sobrecarga en ThingWorx, por lo que no se deben indexar las propiedades que no se utilizarán para QueryImplementingThingsOptimized.
Configuración de las propiedades indexadas
La configuración Índice se encuentra en la sección de propiedades de las entidades. Consulte Propiedades de cosa para obtener más información.
Límites de bytes de indexación
Debido a las restricciones de longitud de bytes de índice, las propiedades de cadena tienen las siguientes limitaciones:
• Las cadenas se limitan a 1500 bytes al utilizar MS SQL o Azure SQL como proveedor de persistencia. Las cadenas se almacenan en MS SQL y Azure SQL como UTF-16.
• Las cadenas se limitan a 1000 bytes cuando se utiliza PostgreSQL como proveedor de persistencia. Las cadenas se almacenan en PostgreSQL como UTF-8.
• Los valores de cadena que superan la longitud máxima de bytes no se añaden al índice y no aparecerán en las consultas indexadas. Si ocurre esto, se añade un error en el registro de aplicación que indica que el valor era demasiado grande y no se ha indexado. Aunque el valor de la cadena no se indexe, se almacena y se guarda. Las API, como GetPropetyValues, pueden continuar obteniendo el valor almacenado y este estará disponible después de los reinicios. Si le preocupa que un valor de cadena pueda superar el límite máximo de bytes, es posible crear una notificación basada en el evento de cambio de datos.
Soporte de las propiedades por defecto
En la tabla siguiente se enumeran las propiedades que están presentes en todas las cosas y que se soportan para las consultas de índice.
|
Nombre de la propiedad
|
Tipo de propiedad
|
¿Soporta consultas indexadas?
|
|---|---|---|
|
name
|
STRING
|
yes
|
|
Descripción
|
STRING
|
yes
|
|
tags
|
TAGS
|
yes
|
|
isSystemObject
|
BOOLEAN
|
no
|
|
homeMashup
|
STRING
|
no
|
|
avatar
|
IMAGE
|
no
|
|
projectName
|
STRING
|
no
|
|
thingTemplate
|
STRING
|
yes
|
Parámetros de entrada de usuario de QueryImplementingThingsOptimized
Las siguientes operaciones se pueden ejecutar durante la ejecución de QueryImplementingThingsOptimized.
|
Nombre de la operación
|
Notas
|
Estados de optimización potenciales (si se proporcionan en la solicitud y no son nulos)
|
||
|---|---|---|---|---|
|
ResultDefinition
|
Se especifica mediante los parámetros basicPropertyNames y propertyNames en la llamada de API.
• basicPropertyNames: una lista de propiedades básicas que se van a devolver.
• propertyNames: una lista de propiedades de entidad integradas e implementadas que se van a devolver.
|
• Si todas las definiciones de propiedades solicitadas están indexadas, QueryImplementingThingsOptimized ejecuta una consulta de índice para generar el conjunto de resultados.
• Si algunas definiciones de propiedades solicitadas están indexadas y se soporta la operación, QueryImplementingThingsOptimized ejecutará una consulta indexada en las propiedades indexadas y utilizará ese conjunto de resultados para consultar la caché en memoria para las propiedades no indexadas.
• Si ninguna de las definiciones de propiedades solicitadas está indexada o un parámetro es nulo, QueryImplementingThingsOptimized consulta la caché en memoria.
|
||
|
NameMask
|
Un patrón similar a una máscara con el que hacer coincidir los nombres de cosa.
|
NameMask no tiene ningún impacto en el hecho de si QueryImplementingThingsOptimized utiliza una consulta de índice.
|
||
|
NetworkName
|
Nombre de red al que debe pertenecer una cosa de implementación determinada. Se pueden proporcionar sugerencias. Por ejemplo, se pueden proporcionar la profundidad máxima de la red y los nombres de red padre para ayudar a reducir la búsqueda.
|
QueryImplementingThingsOptimized realizará una consulta en la caché en memoria.
|
||
|
Etiquetas
|
Una lista de etiquetas con las que se debe etiquetar la entidad para que se incluya en el resultado.
|
QueryImplementingThingsOptimized utilizará la consulta de índice para las etiquetas.
|
||
|
Offset
|
El desvío para iniciar la consulta, se utiliza para la paginación. Por ejemplo, si hay 200 resultados en la base de datos con un desvío de 5, se devuelven los resultados de 5 a 200 (un total de 195).
|
El desvío no afecta al hecho de si QueryImplementingThingsOptimized utiliza una consulta de índice.
|
||
|
Sort
|
La clasificación que se debe aplicar al resultado final.
|
• Si todas las propiedades definidas en la clasificación están indexadas, QueryImplementingThingsOptimized ejecutará una consulta de índice para generar el conjunto de resultados.
• Si algunas propiedades de la clasificación no están indexadas, QueryImplementingThingsOptimized consultará la caché en memoria.
|
||
|
Query
|
El filtro que se debe aplicar a los registros de resultados.
|
• Si todas las definiciones de propiedades solicitadas están indexadas, QueryImplementingThingsOptimized ejecutará una consulta de índice para generar el conjunto de resultados.
• Si algunas definiciones de propiedades solicitadas están indexadas y se soporta la operación, QueryImplementingThingsOptimized ejecutará una consulta indexada en las propiedades indexadas y utilizará ese conjunto de resultados para consultar la caché en memoria para las propiedades no indexadas.
• Si ninguna de las definiciones de propiedades solicitadas está indexada, QueryImplementingThingsOptimized consultará la caché en memoria.
|
||
|
Límite
|
El número máximo de elementos que se deben incluir en el resultado.
|
El límite no afecta al hecho de si QueryImplementingThingsOptimized utiliza una consulta de índice.
|
Sugerencias
La consulta de índice de base de datos se puede desactivar mediante la inclusión de una sugerencia en el parámetro de consulta de QueryImplementingThingsOptimized.
|
Sugerencia
|
¿Obligatorio?
|
Por defecto
|
Acción
|
|---|---|---|---|
|
optimizationDisabled
|
no
|
No incluida
|
• Si no se especifica una consulta, no se incluye la sugerencia en la consulta o es falsa; QueryImplementingThingsOptimized intentará realizar la consulta como se ha descrito anteriormente.
|
Ejemplo de consulta que no utilizará la consulta de índice, donde TT_1_Boolean1 es una propiedad indexada:
query: {
"optimizationDisabled": true,
"sorts": [
{
"fieldName": "name"
}
],
"filters": {
"type": "EQ",
"fieldName": "TT_1_Boolean1",
"value": true
}
} /* QUERY */ ,
"optimizationDisabled": true,
"sorts": [
{
"fieldName": "name"
}
],
"filters": {
"type": "EQ",
"fieldName": "TT_1_Boolean1",
"value": true
}
} /* QUERY */ ,
Migración del tipo base de propiedad
Se puede cambiar el tipo base de propiedad para las propiedades existentes. Para soportar las propiedades indexadas, existen los siguientes escenarios de migración:
• Si la propiedad tiene un valor definido, ThingWorx intentará convertir el valor de la propiedad al nuevo tipo base. Por ejemplo, si se convierte una propiedad de cadena con el valor "Cadena123" a un entero, el nuevo valor entero será 123. En cambio, si se convierte una propiedad de entero de 123 a una cadena, la propiedad será "123".
• Si no se define el valor de la propiedad y el nuevo tipo base tiene un valor por defecto definido, se utilizará para todas las consultas.
• Si no se ha definido el valor por defecto de la propiedad, ThingWorx utilizará el valor por defecto para el nuevo tipo base. Por ejemplo, los enteros y los números se definen en cero (0) y las cadenas se definen en una cadena vacía ("").
Ejemplos
En las dos tablas siguientes se proporcionan ejemplos de cuándo las consultas utilizarán la consulta de índices. El modelo de ejemplo se detalla en la primera tabla y los comportamientos de ejemplo de QueryImplementingThingsOptimized se detallan en la segunda tabla.
Modelo
En el siguiente modelo se muestra el uso de propiedades indexadas. En el modelo de ejemplo se utiliza una plantilla de cosa con dos cosas basadas en esa plantilla. Esta herencia también se puede lograr mediante una definición de cosa implementada por una plantilla de cosa.
|
Nombre de entidad
|
Tipo de entidad
|
Implementa
|
Nombre de la propiedad
|
Tipo de propiedad
|
¿Propiedad indexada?
|
|---|---|---|---|---|---|
|
TestThingTemplate1
|
ThingTemplate
|
GenericThing
|
p1
|
INTEGER
|
Sí
|
|
p2
|
STRING
|
Sí
|
|||
|
p3
|
INTEGER
|
No
|
|||
|
p4
|
STRING
|
No
|
|||
|
TestThing1
|
Cosa
|
TestThingTemplate1
|
Heredada
|
Heredada
|
Heredada
|
|
TestThing2
|
Cosa
|
TestThingTemplate1
|
Heredada
|
Heredada
|
Heredada
|
|
Escenario
|
Ejemplo
|
¿Se usa la consulta de índice?
|
Comentarios
|
|---|---|---|---|
|
Se soportan todas las operaciones, y el filtro se soporta totalmente.
|
{"sorts":[{"fieldName":"p1"}],"filters":{"type":"And","filters":[{"type":"EQ","fieldName":"p2","value":"12"},
{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Sí
|
Solo se consulta una propiedad indexada, por lo que se utilizará una consulta de índice.
|
|
Se soportan todas las operaciones, y el filtro se soporta parcialmente.
|
{"sorts":[{"fieldName":"p1"}],
"filters":{"type":"And","filters":[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Sí
|
ThingWorx ejecutará una consulta de índice para la propiedad P1 y, a continuación, una consulta de caché en ese conjunto de resultados para P4.
|
|
Se soportan todas las operaciones, y no se soporta el filtro.
|
{"sorts":[{"fieldName":"p1"}],"filters":
{"type":"Or","filters":[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
No
|
ThingWorx realiza una consulta en caché completa debido al filtro O, por lo que una consulta de índice no proporciona ninguna ventaja.
|
|
Se soportan todas las operaciones, sin filtro.
|
{"sorts":[{"fieldName":"p1"}]}
|
No
|
No hay nada que filtrar, por lo que no se realiza una consulta.
|
|
Se soportan algunas operaciones, y el filtro se soporta totalmente.
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"And","filters":
[{"type":"EQ","fieldName":"p2","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Sí
|
Todos los campos filtrados están indexados, por lo que esta consulta utilizará una consulta de índice.
|
|
Se soportan algunas operaciones, y el filtro se soporta parcialmente.
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"And","filters":
[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Sí
|
Es igual que el ejemplo de la fila 2, con la excepción de que la clasificación se encuentra en una propiedad no indexada.
|
|
Se soportan algunas operaciones, y el filtro no se soporta.
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"Or","filters":[{"type":"EQ","fieldName":"p4","value":"12"},
{"type":"EQ","fieldName":"p1","value":"13"}]}} |
No
|
El filtro es el mismo que el del ejemplo de la fila 3, por lo que esta consulta no soporta las consultas de índice.
|
|
Se soportan algunas operaciones, y no se proporciona un filtro.
|
{"sorts":[{"fieldName":"p4"}]}
|
No
|
No hay nada que filtrar, por lo que no se soporta.
|
|
Se consultan las etiquetas, y no se proporciona un filtro.
|
Sí
|
Las consultas en etiquetas se soportan para las consultas de índice.
|
Prácticas recomendadas
• Pruebe el rendimiento de la aplicación para determinar si deben desactivarse las optimizaciones de las consultas para el caso de uso concreto.
• Las consultas de índice serán de mayor rendimiento cuando devuelvan un subconjunto pequeño del modelo. Una búsqueda de una única cosa proporcionará la mayor mejora. Por ejemplo, la consulta de una única cosa por un número de serie proporcionará la mejor mejora de rendimiento.
◦ Si una consulta devuelve el 80 % o más del modelo, utilice una sugerencia para desactivar la consulta de índices.
• El cambio de los tipos base de propiedades es una operación costosa, ya que un cambio en el nivel de plantilla de cosa o de definición de cosa tendrá que propagarse a todas las entidades de la implementación. En los modelos de gran tamaño, se puede tardar bastante tiempo y utilizar muchos recursos.
◦ No modifique los tipos base de propiedades mientras el sistema está realizando la ingesta.
◦ Asegúrese de que el tamaño máximo de cola del proveedor de persistencia sea lo suficientemente grande como para acomodar el número de escrituras de propiedades persistentes que se producirán al añadir propiedades indexadas o al cambiar los tipos base de una propiedad indexada. El tamaño máximo de cola debe ser mayor que el número de escrituras de propiedad. El número de escrituras será igual al número de propiedades modificadas multiplicado por el número de cosas que implementan la propiedad. Por ejemplo, el modelo incluye una plantilla de cosa que se implementa por 10.000 cosas. Si se cambia el tipo base de dos propiedades de esa plantilla, se generarán 20.000 escrituras (2 propiedades x 10.000 cosas) en la cola de escritura de la propiedad de persistencia. El tamaño por defecto del tamaño máximo de cola es de 100.000 escrituras, por lo que en este ejemplo se dispondrá de recursos suficientes para la operación.