Proprietà indicizzate
In ThingWorx 9.3 e versioni successive è possibile indicizzare le proprietà per rendere più rapide le interrogazioni. È consigliabile indicizzare solo le proprietà che non cambiano di frequente, ad esempio, numeri di modello, numeri di serie, città o regioni. Quando vengono indicizzati in ThingWorx, i valori delle proprietà vengono memorizzati nel provider di persistenza proprietà, dove vengono indicizzati dal database per permettere interrogazioni più rapide quando si utilizzano le API QueryImplementingThingsOptimized e QueryImplementingThingsOptimizedCount.
Se include solo proprietà indicizzate, un'interrogazione viene eseguita esclusivamente come interrogazione di database.
Se invece include una combinazione di proprietà indicizzate e non indicizzate, ThingWorx determina se un'interrogazione indicizzata può essere vantaggiosa e, in caso affermativo, procede alla relativa esecuzione. In questo scenario ThingWorx esegue prima l'interrogazione indicizzata dal database delle proprietà per ottenere i campi indicizzati. Una volta generato l'insieme di risultati, esegue un'interrogazione sulla cache in memoria per ottenere le proprietà non indicizzate. Un esempio potrebbe essere l'interrogazione su tutti gli oggetti che si trovano in una determinata città (proprietà indicizzata) con una temperatura (dati di telemetria non indicizzabili) al di sopra di una determinata soglia. ThingWorx esegue prima l'interrogazione sul database per ottenere la città, quindi la esegue sui dati di telemetria (temperatura) nella cache in memoria.
Se l'indicizzazione non comporta alcun vantaggio per l'interrogazione richiesta, ThingWorx interroga la cache in memoria.
Sebbene l'interrogazione sul database spesso offra prestazioni superiori, in alcuni casi si ottengono risultati migliori se QueryImplementingThingsOptimized non utilizza le interrogazioni di indicizzazione. Un esempio noto è quando l'interrogazione dell'indice restituisce più dell'80% del numero totale di oggetti nel modello. Per questi esempi, ThingWorx include un "suggerimento", che indica all'interrogazione di imporre a QueryImplementingThingsOptimized di non utilizzare l'interrogazione dell'indice e di eseguire l'interrogazione solo sulla cache in memoria. Per ulteriori informazioni, vedere le sezioni Suggerimenti e Best Practice di seguito.
L'indicizzazione è supportata nei database PostgreSQL, MS SQL e Azure SQL. In H2 è possibile modellare e creare l'applicazione, ma le proprietà non vengono indicizzate e non si ottiene un'ottimizzazione delle prestazioni con le API QueryImplementingThingsOptimized e QueryImplementingThingsOptimizedCount.
È necessario un po' di tempo prima che le proprietà indicizzate diventino persistenti nel database dopo che sono state create o aggiornate. L'utilizzo del servizio QueryImplementingThingsOptimizedWithTotalCount sulla proprietà indicizzata subito dopo gli aggiornamenti delle proprietà restituisce risultati incompleti o imprevisti. Rieseguire il servizio QueryImplementingThingsOptimizedWithTotalCount dopo 2 secondi per ottenere i risultati corretti.
Identificazione delle proprietà per l'indicizzazione
Quando si stabilisce se indicizzare una proprietà, tenere presente quanto segue:
• L'indicizzazione è limitata ai seguenti tipi di base di proprietà: STRING, NUMBER, INTEGER, LONG, BOOLEAN e tutti i tipi di base memorizzati come stringhe.
 |
I tipi di base seguenti sono memorizzati come stringhe: DATETIME, THINGNAME, USERNAME, GROUPNAME, HYPERLINK, IMAGELINK, MASHUPNAME, MENUNAME, DASHBOARDNAME, TEXT, GUID, NOTIFICATIONCONTENTNAME, NOTIFICATIONDEFINITIONNAME, STYLETHEMENAME e THINGGROUPNAME.
|
• Devono essere considerate per l'indicizzazione solo le proprietà con valori che non cambiano di frequente o che non cambiano affatto. Le proprietà che cambiano spesso non devono essere considerate. Esempi di proprietà da indicizzare includono numeri di modello o numeri di serie. Per l'attrezzatura fissa, è possibile considerare anche città, stato o regione.
|
|
I dati di telemetria non devono mai essere indicizzati.
|
• Ci sono probabilità che la proprietà venga utilizzata durante la chiamata a QueryImplementingThingsOptimized? Tutte le proprietà indicizzate vengono rese anche persistenti, pertanto è necessario valutare se l'indicizzazione di una proprietà comporta dei vantaggi. Le proprietà persistenti impongono un overhead in ThingWorx, pertanto non è consigliabile indicizzare le proprietà che non verranno utilizzate per QueryImplementingThingsOptimized.
Configurazione delle proprietà indicizzate
L'impostazione dell'Indice si trova nella sezione delle proprietà per le entità. Per ulteriori informazioni, vedere Proprietà degli oggetti.
Limiti di byte di indicizzazione
A causa dei vincoli di lunghezza di byte dell'indice, le proprietà di stringa presentano le limitazioni seguenti:
• Le stringhe sono limitate a 1500 byte quando si utilizza MS SQL o Azure SQL come provider di persistenza. Le stringhe vengono memorizzate in MS SQL e Azure SQL come UTF-16.
• Le stringhe sono limitate a 1000 byte quando si utilizza PostgreSQL come provider di persistenza. Le stringhe vengono memorizzate in PostgreSQL come UTF-8.
• I valori stringa che superano la lunghezza massima di byte non vengono aggiunti all'indice e non vengono visualizzati nelle interrogazioni indicizzate. In questo caso, nel log applicazioni viene aggiunto un errore che indica che il valore è troppo grande e non è stato indicizzato. Anche se il valore stringa non è indicizzato, viene comunque memorizzato e reso persistente. Le API, ad esempio GetPropetyValues, possono comunque recuperare il valore memorizzato, che sarà disponibile dopo il riavvio. Se si teme che un valore stringa possa superare il limite massimo di byte, si può creare una notifica basata sull'evento di modifica dei dati.
Supporto delle proprietà di default
Nella tabella seguente sono elencate le proprietà presenti in tutti gli oggetti e supportate per l'interrogazione dell'indice.
|
Nome proprietà
|
Tipo di proprietà
|
Supporta le interrogazioni indicizzate?
|
|---|---|---|
|
name
|
STRING
|
sì
|
|
description
|
STRING
|
sì
|
|
tags
|
TAGS
|
sì
|
|
isSystemObject
|
BOOLEAN
|
no
|
|
homeMashup
|
STRING
|
no
|
|
avatar
|
IMAGE
|
no
|
|
projectName
|
STRING
|
no
|
|
thingTemplate
|
STRING
|
sì
|
Parametri di input utente QueryImplementingThingsOptimized
Durante l'esecuzione di QueryImplementingThingsOptimized, è possibile eseguire le operazioni descritte di seguito.
|
Nome operazione
|
Note
|
Stati di ottimizzazione potenziali (se forniti su richiesta e non null)
|
||
|---|---|---|---|---|
|
ResultDefinition
|
Specificata tramite i parametri basicPropertyNames e propertyNames nella chiamata API.
• basicPropertyNames - Elenco di proprietà di base da restituire.
• propertyNames - Elenco di proprietà di entità integrate e di implementazione da restituire.
|
• Se tutte le definizioni di proprietà richieste sono indicizzate, QueryImplementingThingsOptimized esegue un'interrogazione dell'indice per generare l'insieme di risultati.
• Se alcune definizioni di proprietà richieste sono indicizzate e l'operazione è supportata, QueryImplementingThingsOptimized esegue un'interrogazione indicizzata sulle proprietà indicizzate e utilizza tale insieme di risultati per interrogare la cache in memoria per ottenere le proprietà non indicizzate.
• Se nessuna delle definizioni di proprietà richieste è indicizzata o un parametro è NULL, QueryImplementingThingsOptimized interroga la cache in memoria.
|
||
|
NameMask
|
Schema simile a una maschera per la corrispondenza dei nomi di oggetto.
|
NameMask non influisce in alcun modo sull'utilizzo di un'interrogazione dell'indice da parte di QueryImplementingThingsOptimized.
|
||
|
NetworkName
|
Nome di rete a cui deve appartenere un determinato oggetto di implementazione. È possibile fornire suggerimenti. Ad esempio, si può semplificare la ricerca fornendo la profondità max della rete e i nomi della rete padre.
|
QueryImplementingThingsOptimized interroga la cache in memoria.
|
||
|
Tag
|
Elenco di tag da applicare all'entità per includerla nel risultato.
|
QueryImplementingThingsOptimized usa l'interrogazione dell'indice per ottenere i tag.
|
||
|
Offset
|
L'offset per l'avvio dell'interrogazione, utilizzato per l'impaginazione. Ad esempio, se nel database sono presenti 200 risultati con un offset pari a 5, vengono restituiti i risultati da 5 a 200 (per un totale di 195).
|
L'offset non influisce in alcun modo sull'utilizzo di un'interrogazione dell'indice da parte di QueryImplementingThingsOptimized.
|
||
|
Sort
|
L'ordinamento da applicare al risultato finale.
|
• Se tutte le proprietà definite nell'ordinamento sono indicizzate, QueryImplementingThingsOptimized esegue un'interrogazione dell'indice per generare l'insieme di risultati.
• Se alcune proprietà dell'ordinamento non sono indicizzate, QueryImplementingThingsOptimized esegue un'interrogazione sulla cache in memoria.
|
||
|
Query
|
Il filtro da applicare ai record dei risultati.
|
• Se tutte le definizioni di proprietà richieste sono indicizzate, QueryImplementingThingsOptimized esegue un'interrogazione dell'indice per generare l'insieme di risultati.
• Se alcune definizioni di proprietà richieste sono indicizzate e l'operazione è supportata, QueryImplementingThingsOptimized esegue un'interrogazione indicizzata sulle proprietà indicizzate e utilizza il rispettivo insieme di risultati per interrogare la cache in memoria per ottenere le proprietà non indicizzate.
• Se nessuna delle definizioni di proprietà richieste è indicizzata, QueryImplementingThingsOptimized interroga la cache in memoria.
|
||
|
Limit
|
Numero massimo di elementi da includere nel risultato.
|
Limit non influisce in alcun modo sull'utilizzo di un'interrogazione dell'indice da parte di QueryImplementingThingsOptimized.
|
Suggerimenti
È possibile disattivare l'interrogazione dell'indice del database includendo un suggerimento nel parametro di interrogazione di QueryImplementingThingsOptimized.
|
Suggerimento
|
Obbligatorio?
|
Default
|
Azione
|
|---|---|---|---|
|
optimizationDisabled
|
no
|
Non incluso
|
• Se non è stata specificata un'interrogazione, il suggerimento non è incluso nell'interrogazione o è false, QueryImplementingThingsOptimized tenterà di eseguire un'interrogazione come descritto in precedenza.
|
Esempio di interrogazione che non utilizza l'interrogazione dell'indice, dove TT_1_Boolean1 è una proprietà indicizzata:
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 */ ,
Migrazione del tipo di base delle proprietà
È possibile modificare il tipo di base per le proprietà esistenti. Per supportare le proprietà indicizzate, sono disponibili gli scenari di migrazione seguenti:
• Se per la proprietà è impostato un valore, ThingWorx tenterà di convertire il valore della proprietà nel nuovo tipo di base. Ad esempio, se si converte una proprietà stringa con valore "String123" in un valore intero, il valore del nuovo numero intero sarà 123. Viceversa, se si converte una proprietà numero intero di 123 in una stringa, la proprietà sarà "123".
• Se il valore della proprietà non è impostato e per il nuovo tipo di base è definito un valore di default, tale valore verrà utilizzato per tutte le interrogazioni.
• Se non è definito il valore di default della proprietà, ThingWorx utilizza il valore di default per il nuovo tipo di base. Ad esempio, numeri interi e numeri sono impostati su zero (0) e le stringhe sono impostate su una stringa vuota ("").
Esempi
Nelle due tabelle seguenti sono riportati esempi di casi in cui le interrogazioni utilizzano l'interrogazione dell'indice. Nella prima tabella è descritto in dettaglio il modello di esempio, mentre nella seconda i comportamenti di esempio di QueryImplementingThingsOptimized.
Modello
Il modello seguente illustra l'utilizzo di proprietà indicizzate. Il modello di esempio utilizza un modello di oggetto con due oggetti basati sul modello. Si può ottenere questa eredità anche utilizzando una thing shape implementata da un modello di oggetto.
|
Nome entità
|
Tipo di entità
|
Implementa
|
Nome proprietà
|
Tipo di proprietà
|
Proprietà indicizzata?
|
|---|---|---|---|---|---|
|
TestThingTemplate1
|
ThingTemplate
|
GenericThing
|
p1
|
INTEGER
|
Sì
|
|
p2
|
STRING
|
Sì
|
|||
|
p3
|
INTEGER
|
No
|
|||
|
p4
|
STRING
|
No
|
|||
|
TestThing1
|
Thing
|
TestThingTemplate1
|
Inherited
|
Inherited
|
Inherited
|
|
TestThing2
|
Thing
|
TestThingTemplate1
|
Inherited
|
Inherited
|
Inherited
|
|
Scenario
|
Esempio
|
Interrogazione indice utilizzata?
|
Commenti
|
|---|---|---|---|
|
Sono supportate tutte le operazioni e il filtro è pienamente supportato.
|
{"sorts":[{"fieldName":"p1"}],"filters":{"type":"And","filters":[{"type":"EQ","fieldName":"p2","value":"12"},
{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Sì
|
Viene eseguita un'interrogazione su una proprietà indicizzata, pertanto viene utilizzata un'interrogazione di indice.
|
|
Tutte le operazioni sono supportate e il filtro è supportato parzialmente.
|
{"sorts":[{"fieldName":"p1"}],
"filters":{"type":"And","filters":[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Sì
|
ThingWorx esegue un'interrogazione di indice per la proprietà P1 e quindi un'interrogazione della cache sull'insieme di risultati per P4.
|
|
Sono supportate tutte le operazioni e il filtro non è supportato.
|
{"sorts":[{"fieldName":"p1"}],"filters":
{"type":"Or","filters":[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
No
|
ThingWorx esegue un'interrogazione completa della cache per la presenza del filtro OR, pertanto un'interrogazione di indice non offre alcun vantaggio.
|
|
Sono supportate tutte le operazioni, nessun filtro.
|
{"sorts":[{"fieldName":"p1"}]}
|
No
|
Non c'è nulla da filtrare, pertanto non viene eseguita un'interrogazione.
|
|
Sono supportate alcune operazioni e il filtro è pienamente supportato.
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"And","filters":
[{"type":"EQ","fieldName":"p2","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Sì
|
Tutti i campi filtrati sono indicizzati, pertanto l'interrogazione utilizza un'interrogazione di indice.
|
|
Sono supportate alcune operazioni e il filtro è supportato parzialmente.
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"And","filters":
[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Sì
|
Si tratta dello stesso esempio della riga 2, con la differenza che SORT si trova in una proprietà non indicizzata.
|
|
Sono supportate alcune operazioni, il filtro non è supportato.
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"Or","filters":[{"type":"EQ","fieldName":"p4","value":"12"},
{"type":"EQ","fieldName":"p1","value":"13"}]}} |
No
|
Il filtro è uguale all'esempio della riga 3, pertanto questa interrogazione non supporta le interrogazioni di indice.
|
|
Sono supportate alcune operazioni, non viene specificato un filtro.
|
{"sorts":[{"fieldName":"p4"}]}
|
No
|
Non c'è nulla da filtrare, pertanto non è supportato.
|
|
Vengono interrogati i tag, non viene specificato un filtro.
|
Sì
|
Sono supportate le interrogazioni sui tag per l'interrogazione dell'indice.
|
Best practice
• Verificare le prestazioni dell'applicazione per determinare se le ottimizzazioni delle interrogazioni devono essere disattivate per il caso di utilizzo specifico.
• Le interrogazioni di indice sono più performanti quando restituiscono un piccolo sottoinsieme del modello. La ricerca di un singolo oggetto comporta il livello massimo di miglioramento. Ad esempio, l'interrogazione di un singolo oggetto in base a un numero di serie determina il massimo livello di miglioramento delle prestazioni.
◦ Se un'interrogazione restituisce almeno l'80% del modello, utilizzare un suggerimento per disattivare l'interrogazione dell'indice.
• La modifica dei tipi di base delle proprietà è un'operazione costosa perché una modifica a livello di modello di oggetto o di thing shape dovrà propagarsi a tutte le entità di implementazione. Nei modelli di grandi dimensioni questo potrebbe richiedere molto tempo e un quantitativo di risorse notevole.
◦ Non modificare i tipi di base delle proprietà mentre il sistema esegue l'operazione di inserimento.
◦ Assicurarsi che la dimensione massima della coda del provider di persistenza sia sufficiente per contenere il numero di scritture di proprietà persistenti che si verificano quando si aggiungono proprietà indicizzate o si modificano tipi di base di una proprietà indicizzata. La dimensione massima della coda deve essere maggiore del numero di scritture della proprietà. Il numero di scritture sarà uguale al numero di proprietà modificate moltiplicato per il numero di oggetti che implementano la proprietà. Ad esempio, se il modello include un modello di oggetto implementato da 10.000 oggetti, modificando il tipo di base per due proprietà su tale modello, si genereranno 20.000 scritture (2 proprietà X 10.000 oggetti) nella coda di scrittura della proprietà di persistenza. Il valore di default di Dimensione max coda è 100.000 scritture, pertanto in questo esempio le risorse sono sufficienti per l'operazione.