Indizierte Eigenschaften
In ThingWorx 9.3 und höher können Eigenschaften indiziert werden, um Abfragen zu beschleunigen. Es sollten nur solche Eigenschaften indiziert werden, die selten geändert werden. Beispiel: Modellnummern, Seriennummern, Städte oder Regionen. In ThingWorx indizierte Eigenschaftswerte werden im Eigenschaft-Persistenzanbieter gespeichert. Hier werden sie von der Datenbank indiziert, um schnellere Abfragen mit den APIs QueryImplementingThingsOptimized und QueryImplementingThingsOptimizedCount zu ermöglichen.
Wenn eine Abfrage nur indizierte Eigenschaften enthält, wird die Abfrage ausschließlich als Datenbankabfrage ausgeführt.
Wenn eine Abfrage eine Kombination aus indizierten und nicht indizierten Eigenschaften enthält, bestimmt ThingWorx, ob eine indizierte Abfrage Vorteile bringen würde, und führt diese dann ggf. aus. In diesem Szenario führt ThingWorx zuerst die indizierte Abfrage aus der Eigenschaftendatenbank für die indizierten Felder aus. Nachdem dieser Ergebnissatz generiert wurde, führt ThingWorx eine Abfrage für die nicht indizierten Eigenschaften im Cache im Arbeitsspeicher aus. Dies geschieht beispielsweise, wenn Sie alle Dinge abfragen möchten, die sich in einer bestimmten Stadt (indizierte Eigenschaft) befinden und eine Temperatur (Telemetriedaten – nicht indizierbar) über einem bestimmten Schwellenwert aufweisen. ThingWorx fragt zuerst die Stadt aus der Datenbank ab und führt dann die Abfrage für die Telemetriedaten (Temperatur) im Cache im Arbeitsspeicher aus.
Wenn eine Indexierung für die angeforderte Abfrage keine Vorteile bringt, fragt ThingWorx den Cache im Arbeitsspeicher ab.
Während Datenbankabfragen in den meisten Fällen sehr leistungsstark sind, gibt es auch Fälle, in QueryImplementingThingsOptimized ohne Indexierungsabfragen besser funktioniert als mit. Ein bekannter Fall ist eine Indexabfrage, die mehr als 80 % der Gesamtzahl der Dinge im Modell zurückgibt. Für diese Fälle schließt ThingWorx einen "Hinweis" in die Abfrage ein, um QueryImplementingThingsOptimized zu zwingen, keine Indexabfragen zu verwenden und nur den Cache im Arbeitsspeicher abzufragen. Weitere Informationen finden Sie in den nachfolgenden Abschnitten Hinweise und Optimale Vorgehensweisen.
Indexierung wird für PostgreSQL-, MS SQL- und Azure SQL-Datenbanken unterstützt. Wenn Sie H2 verwenden, können Sie Ihre Anwendung in H2 modellieren und erstellen, es werden jedoch keine Eigenschaften indiziert und keine Leistungsvorteile in den APIs QueryImplementingThingsOptimized und QueryImplementingThingsOptimizedCount erzielt.
Es dauert eine Weile, bis indizierte Eigenschaften nach Ihrer Erstellung oder Aktualisierung in der Datenbank persistent sind. Die Verwendung des Dienstes QueryImplementingThingsOptimizedWithTotalCount für die indizierte Eigenschaft unmittelbar nach deren Aktualisierung gibt unvollständige oder unerwartete Ergebnisse zurück. Führen Sie den Dienst QueryImplementingThingsOptimizedWithTotalCount nach 2 Sekunden erneut aus, um richtige Ergebnisse zu erhalten.
Eigenschaften für die Indexierung identifizieren
Berücksichtigen Sie bei der Überlegung, ob eine Eigenschaft indiziert werden sollte, die folgenden Punkte:
• Die Indexierung ist auf die folgenden Basistypen von Eigenschaften beschränkt: STRING, NUMBER, INTEGER, LONG, BOOLEAN und alle Basistypen, die als Zeichenfolgen gespeichert werden.
 |
Die folgenden Basistypen werden als Zeichenfolgen gespeichert: DATETIME, THINGNAME, USERNAME, GROUPNAME, HYPERLINK, IMAGELINK, MASHUPNAME, MENUNAME, DASHBOARDNAME, TEXT, GUID, NOTIFICATIONCONTENTNAME, NOTIFICATIONDEFINITIONNAME, STYLETHEMENAME und THINGGROUPNAME.
|
• Für die Indexierung sollten nur Eigenschaften mit Werten berücksichtigt werden, die sich selten oder überhaupt nicht ändern. Eigenschaften, die sich häufig ändern, sollten nicht berücksichtigt werden. Beispiele für zu indizierende Eigenschaften sind Modellnummern oder Seriennummern. Für fest installierte Ausrüstung können auch Stadt, Bundesland oder Region berücksichtigt werden.
|
|
Telemetriedaten sollten nie indiziert werden.
|
• Wird die Eigenschaft wahrscheinlich beim Aufruf von QueryImplementingThingsOptimized verwendet? Alle indizierten Eigenschaften werden auch persistent gemacht, sodass darüber nachgedacht werden sollte, ob die Indexierung einer Eigenschaft von praktischem Nutzen ist. Eigenschaften persistent zu machen bedeutet einen Mehraufwand für ThingWorx, daher sollten Eigenschaften, die nicht für QueryImplementingThingsOptimized verwendet werden, nicht indiziert werden.
Indizierte Eigenschaften konfigurieren
Die Einstellung Index befindet sich im Abschnitt mit Eigenschaften für Entitäten. Weitere Informationen finden Sie unter Dingeigenschaften.
Byte-Grenzwerte für die Indexierung
Aufgrund von Längenbeschränkungen für Index-Bytes gelten für STRING-Eigenschaften die folgenden Einschränkungen:
• Zeichenfolgen sind auf 1500 Byte begrenzt, wenn MS SQL oder Azure SQL als Persistenzanbieter verwendet wird. Zeichenfolgen werden in MS SQL und Azure SQL als UTF-16 gespeichert.
• Zeichenfolgen sind auf 1000 Byte begrenzt, wenn PostgreSQL als Persistenzanbieter verwendet wird. Zeichenfolgen werden in PostgreSQL als UTF-8 gespeichert.
• Zeichenfolgenwerte, die die maximale Byte-Länge überschreiten, werden nicht zum Index hinzugefügt und nicht in indizierten Abfragen angezeigt. In diesem Fall wird im Anwendungsprotokoll ein Fehler hinzugefügt, der angibt, dass der Wert zu groß war und nicht indiziert wurde. Der Zeichenfolgenwert wird zwar nicht indiziert, aber gespeichert und persistent gemacht. APIs wie GetPropetyValues können den gespeicherten Wert trotzdem abrufen, und der Wert ist nach Neustarts verfügbar. Wenn Sie Bedenken haben, dass ein Zeichenfolgenwert möglicherweise den Byte-Maximalwert überschreitet, können Sie eine Benachrichtigung erstellen, die auf dem Datenänderungsereignis basiert.
Unterstützung für Standardeigenschaften
In der folgenden Tabelle sind die Eigenschaften aufgeführt, die für alle Dinge vorhanden sind und für Indexabfragen unterstützt werden.
|
Eigenschaftenname
|
Eigenschaftstyp
|
Unterstützt indizierte Abfragen?
|
|---|---|---|
|
Name
|
STRING
|
ja
|
|
Beschreibung
|
STRING
|
ja
|
|
tags
|
TAGS
|
ja
|
|
isSystemObject
|
BOOLEAN
|
nein
|
|
homeMashup
|
STRING
|
nein
|
|
avatar
|
IMAGE
|
nein
|
|
projectName
|
STRING
|
nein
|
|
thingTemplate
|
STRING
|
ja
|
Benutzereingabeparameter für QueryImplementingThingsOptimized
Die folgenden Operationen können bei Ausführung von QueryImplementingThingsOptimized ausgeführt werden.
|
Operationsname
|
Hinweise
|
Potenzielle Optimierungsstatus (falls in der Anfrage angegeben und nicht NULL)
|
||
|---|---|---|---|---|
|
ResultDefinition
|
Durch die Parameter basicPropertyNames und propertyNames im API-Aufruf angegeben
• basicPropertyNames – eine Liste der zurückzugebenden grundlegenden Eigenschaften
• propertyNames – eine Liste der integrierten Eigenschaften und Eigenschaften der implementierenden Entität, die zurückgegeben werden sollen
|
• Wenn alle angeforderten Eigenschaftsdefinitionen indiziert sind, führt QueryImplementingThingsOptimized eine Indexabfrage aus, um den Ergebnissatz zu generieren.
• Wenn einige angeforderte Eigenschaftsdefinitionen indiziert sind und die Operation unterstützt wird, führt QueryImplementingThingsOptimized eine indizierte Abfrage für die indizierten Eigenschaften aus und verwendet den zugehörigen Ergebnissatz, um den Cache im Arbeitsspeicher nach den nicht indizierten Eigenschaften abzufragen.
• Wenn keine der angeforderten Eigenschaftsdefinitionen indiziert ist oder ein Parameter NULL ist, fragt QueryImplementingThingsOptimized den Cache im Arbeitsspeicher ab.
|
||
|
NameMask
|
Ein maskenähnliches Muster, mit dem Dingnamen abgeglichen werden sollen
|
NameMask hat keine Auswirkung darauf, ob QueryImplementingThingsOptimized eine Indexabfrage verwendet.
|
||
|
NetworkName
|
Ein Netzwerkname, zu dem ein bestimmtes implementierendes Ding hören muss. Hinweise können angegeben werden. Sie können beispielsweise die maximale Netzwerktiefe und Eltern-Netzwerknamen angeben, um die Suche einzugrenzen.
|
QueryImplementingThingsOptimized fragt den Cache im Arbeitsspeicher ab.
|
||
|
Tags
|
Eine Liste von Tags, mit denen das Element gekennzeichnet sein muss, um in das Ergebnis eingeschlossen zu werden
|
QueryImplementingThingsOptimized verwendet die Indexabfrage für Tags.
|
||
|
Offset
|
Der Versatz für den Start der Abfrage; wird für die Paginierung verwendet. Wenn beispielsweise 200 Ergebnisse in der Datenbank vorliegen und ein Versatz von 5 angegeben ist, werden die Ergebnisse 5 bis 200 (also insgesamt 195) zurückgegeben.
|
Der Versatz hat keine Auswirkung darauf, ob QueryImplementingThingsOptimized eine Indexabfrage verwendet.
|
||
|
Sort
|
Die Sortierung, die auf das endgültige Ergebnis angewendet werden soll
|
• Wenn alle in der Sortierung definierten Eigenschaften indiziert sind, führt QueryImplementingThingsOptimized eine Indexabfrage aus, um den Ergebnissatz zu generieren.
• Wenn einige Eigenschaften in der Sortierung nicht indiziert sind, fragt QueryImplementingThingsOptimized den Cache im Arbeitsspeicher ab.
|
||
|
Query
|
Der Filter, der auf die Ergebnisdatensätze angewendet werden soll
|
• Wenn alle angeforderten Eigenschaftsdefinitionen indiziert sind, führt QueryImplementingThingsOptimized eine Indexabfrage aus, um den Ergebnissatz zu generieren.
• Wenn einige angeforderte Eigenschaftsdefinitionen indiziert sind und die Operation unterstützt wird, führt QueryImplementingThingsOptimized eine indizierte Abfrage für die indizierten Eigenschaften aus und verwendet den zugehörigen Ergebnissatz, um den Cache im Arbeitsspeicher nach den nicht indizierten Eigenschaften abzufragen.
• Wenn keine der angeforderten Eigenschaftsdefinitionen indiziert ist, fragt QueryImplementingThingsOptimized den Cache im Arbeitsspeicher ab.
|
||
|
Limit
|
Die maximale Anzahl von Elementen, die in das Ergebnis eingeschlossen werden sollen.
|
"Limit" hat keine Auswirkung darauf, ob QueryImplementingThingsOptimized eine Indexabfrage verwendet.
|
Hinweise
Datenbank-Indexabfragen können deaktiviert werden, indem ein Hinweis in den Abfrageparameter von QueryImplementingThingsOptimized eingeschlossen wird.
|
Hinweis
|
Erforderlich?
|
Standard
|
Aktion
|
|---|---|---|---|
|
optimizationDisabled
|
nein
|
Nicht eingeschlossen
|
• Wenn keine Abfrage angegeben und der Hinweis nicht in die Abfrage eingeschlossen oder falsch ist, versucht QueryImplementingThingsOptimized, die Abfrage wie oben beschrieben auszuführen.
|
Beispiel für eine Abfrage, die keine Indexabfrage verwendet, wobei TT_1_Boolean1 eine indizierte Eigenschaft ist:
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 */ ,
Migration des Eigenschaften-Basistyps
Sie können den Eigenschaften-Basistyp für vorhandene Eigenschaften ändern. Zur Unterstützung indizierter Eigenschaften gibt es die folgenden Migrationsszenarien:
• Wenn die Eigenschaft einen festgelegten Wert aufweist, versucht ThingWorx, den Eigenschaftswert in den neuen Basistyp zu konvertieren. Wenn Sie beispielsweise eine STRING-Eigenschaft mit dem Wert "String123" in eine Ganzzahl konvertieren, lautet der neue Ganzzahlwert 123. Umgekehrt gilt: Wenn Sie die INTEGER-Eigenschaft 123 in eine Zeichenfolge konvertieren, lautet die Eigenschaft "123".
• Wenn der Eigenschaftswert nicht festgelegt und für den neuen Basistyp ein Standardwert definiert ist, wird dieser für alle Abfragen verwendet.
• Wenn der Standardwert der Eigenschaft nicht definiert ist, verwendet ThingWorx den Standardwert für den neuen Basistyp. Beispielsweise werden Ganzzahlen und Zahlen auf null (0) und Zeichenfolgen auf eine leere Zeichenfolge ("") festgelegt.
Beispiele
Die beiden folgenden Tabellen enthalten Beispiele dafür, wann in Abfragen die Indexabfrage verwendet wird. Die erste Tabelle enthält die Details des Beispielmodells und die zweite Tabelle die Beispielverhaltensweisen von QueryImplementingThingsOptimized.
Modell
Das folgende Modell veranschaulicht die Verwendung indizierter Eigenschaften. Das Beispielmodell verwendet eine Dingvorlage mit zwei Dingen, die auf dieser Vorlage basieren. Diese Vererbung kann auch mit einer Dingform erreicht werden, die von einer Dingvorlage implementiert wird.
|
Entitätsname
|
Entitätstyp
|
Implementiert
|
Eigenschaftenname
|
Eigenschaftstyp
|
Eigenschaft indiziert?
|
|---|---|---|---|---|---|
|
TestThingTemplate1
|
ThingTemplate
|
GenericThing
|
p1
|
INTEGER
|
Ja
|
|
p2
|
STRING
|
Ja
|
|||
|
p3
|
INTEGER
|
Nein
|
|||
|
p4
|
STRING
|
Nein
|
|||
|
TestThing1
|
Thing
|
TestThingTemplate1
|
Geerbt
|
Geerbt
|
Geerbt
|
|
TestThing2
|
Thing
|
TestThingTemplate1
|
Geerbt
|
Geerbt
|
Geerbt
|
|
Szenario
|
Beispiel
|
Indexabfrage verwendet?
|
Kommentare
|
|---|---|---|---|
|
Alle Operationen werden unterstützt, und der Filter wird vollständig unterstützt.
|
{"sorts":[{"fieldName":"p1"}],"filters":{"type":"And","filters":[{"type":"EQ","fieldName":"p2","value":"12"},
{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Ja
|
Es wird nur eine indizierte Eigenschaft abgefragt, daher wird hier eine Indexabfrage verwendet.
|
|
Alle Operationen werden unterstützt, und der Filter wird teilweise unterstützt.
|
{"sorts":[{"fieldName":"p1"}],
"filters":{"type":"And","filters":[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Ja
|
ThingWorx führt eine Indexabfrage für die Eigenschaft P1 und dann eine Cache-Abfrage für diesen Ergebnissatz für P4 aus.
|
|
Alle Operationen werden unterstützt, und der Filter wird nicht unterstützt.
|
{"sorts":[{"fieldName":"p1"}],"filters":
{"type":"Or","filters":[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Nein
|
ThingWorx führt aufgrund des ODER-Filters eine vollständige Cache-Abfrage aus, sodass eine Indexabfrage keinen Vorteil bietet.
|
|
Alle Operationen werden unterstützt, kein Filter.
|
{"sorts":[{"fieldName":"p1"}]}
|
Nein
|
Es gibt nichts zu filtern, sodass keine Abfrage ausgeführt wird.
|
|
Einige Operationen werden unterstützt, und der Filter wird vollständig unterstützt.
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"And","filters":
[{"type":"EQ","fieldName":"p2","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Ja
|
Alle gefilterten Felder sind indiziert, daher verwendet diese Abfrage eine Indexabfrage.
|
|
Einige Operationen werden unterstützt, und der Filter wird teilweise unterstützt.
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"And","filters":
[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Ja
|
Dies entspricht dem Beispiel in Zeile 2, mit der Ausnahme, dass die Sortierung für eine nicht indizierte Eigenschaft ausgeführt wird.
|
|
Einige Operationen werden unterstützt, der Filter wird nicht unterstützt.
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"Or","filters":[{"type":"EQ","fieldName":"p4","value":"12"},
{"type":"EQ","fieldName":"p1","value":"13"}]}} |
Nein
|
Der Filter entspricht dem Beispiel in Zeile 3, daher unterstützt diese Abfrage keine Indexabfragen.
|
|
Einige Operationen werden unterstützt, es wird kein Filter angegeben.
|
{"sorts":[{"fieldName":"p4"}]}
|
Nein
|
Es gibt nichts zu filtern, daher wird dies nicht unterstützt.
|
|
Tags werden abgefragt, es wird kein Filter angegeben.
|
Ja
|
Tag-Abfragen werden für Indexabfragen unterstützt.
|
Optimale Vorgehensweisen
• Testen Sie die Leistung Ihrer Anwendung, um zu ermitteln, ob Abfrageoptimierungen für Ihren speziellen Anwendungsfall deaktiviert werden sollten.
• Indexabfragen sind am leistungsstärksten, wenn sie eine kleine Untermenge des Modells zurückgeben. Eine Suche nach einem einzelnen Ding bringt die größte Verbesserung. Beispielsweise bietet das Abfragen eines einzelnen Dings anhand einer Seriennummer die beste Leistungsverbesserung.
◦ Wenn eine Abfrage 80 % oder mehr des Modells zurückgibt, verwenden Sie einen Hinweis, um Indexabfragen zu deaktivieren.
• Das Ändern von Eigenschaften-Basistypen ist eine aufwendige Operation, da eine Änderung auf Ebene der Dingvorlage oder Dingform auf alle implementierenden Entitäten übertragen werden muss. Bei großen Modellen kann dies sehr viel Zeit und Ressourcen in Anspruch nehmen.
◦ Ändern Sie die Eigenschaften-Basistypen nicht, während das System gerade eine Erfassung ausführt.
◦ Stellen Sie sicher, dass die maximale Warteschlangengröße des Persistenzanbieters groß genug ist, um die Anzahl von Schreibvorgänge für persistente Eigenschaften zu unterstützen, die beim Hinzufügen indizierter Eigenschaften oder beim Ändern von Basistypen einer indizierten Eigenschaft ausgeführt werden. Die maximale Warteschlangengröße sollte größer sein als die Anzahl der Schreibvorgänge von Eigenschaften. Die Anzahl der Schreibvorgänge ist gleich der Anzahl der geänderten Eigenschaften multipliziert mit der Anzahl der Dinge, die diese Eigenschaft implementieren. Beispiel: Ihr Modell enthält eine Dingvorlage, die von 10.000 Dingen implementiert wird. Wenn Sie den Basistyp für zwei Eigenschaften in dieser Vorlage ändern, generieren Sie 20.000 Schreibvorgänge (2 Eigenschaften x 10.000 Dinge) in die Schreibwarteschlange für Persistenzeigenschaften. Standardmäßig ist die maximale Warteschlangengröße auf 100.000 Schreibvorgänge festgelegt, daher verfügen Sie für dieses Beispiel über ausreichende Ressourcen für die Operation.