索引內容
在 ThingWorx 9.3 及更新版本中，可以索引內容以允許更快查詢。只應索引不經常變更的內容。例如，型號、序號、城市或地區。當在 ThingWorx 中索引時，內容值會儲存在內容持續性提供者中，在此情況下，它們會由資料庫進行索引，以允許在使用 QueryImplementingThingsOptimized 與 QueryImplementingThingsOptimizedCount 時更快查詢。
如果查詢僅包括索引內容，查詢只會以資料庫查詢的方式執行。
如果查詢中包含索引與非索引內容的混合，ThingWorx 會決定查詢是否可以從執行索引查詢中獲益，並且也將這樣做。在此情況下，ThingWorx 會先從內容資料庫針對索引的欄位執行索引查詢。產生結果集之後，ThingWorx 會針對記憶體中的快取執行非索引內容的查詢。這有一個可能的例子，就是如果您想要查詢位於特定城市 (索引內容) 中溫度 (遙測資料 - 非索引) 高於特定臨界值的所有物件ThingWorx 會先從資料庫中執行城市的查詢，然後對記憶體中的快取執行遙測資料 (溫度) 查詢。
如果請求的查詢無法從索引中受益，ThingWorx 會針對記憶體中的快取進行查詢。
儘管針對資料庫進行查詢經常可以提供優異的效能，但在某些情況下，不使用 QueryImplementingThingsOptimized 的索引查詢會比使用更好。一個已知的例子是，當索引查詢傳回模型中的物件總數超過 80% 時。針對這些情況，ThingWorx 包括查詢的「提示」，可強制 QueryImplementingThingsOptimized 不要使用索引查詢，而只從記憶體中的快取查詢。如需其他資訊，請參閱以下的提示與最佳作法部份。
PostgreSQL、MS SQL 與 Azure SQL 資料庫都支援索引。如果您使用 H2，您可以在 H2 上建模及建立應用程式，但不會索引內容，而且不會在 QueryImplementingThingsOptimized 與 QueryImplementingThingsOptimizedCount API 上看到效能優勢。
索引內容建立或更新后，需一段時間后才能保存至資料庫。內容更新後立即對索引內容使用 QueryImplementingThingsOptimizedWithTotalCount 服務會傳回不完整或非預期的結果。2 秒後重新執行 QueryImplementingThingsOptimizedWithTotalCount 服務以獲得正確的結果。
識別索引的內容
決定是否索引內容時，請考慮下列事項：
• 索引僅限於下列內容基礎類型：STRING、NUMBER、INTEGER、LONG、BOOLEAN，以及儲存為字串的任何基礎類型。
 |
下列基礎類型會儲存為字串：DATETIME、THINGNAME、USERNAME、GROUPNAME、HYPERLINK、IMAGELINK、MASHUPNAME、MENUNAME、DASHBOARDNAME、TEXT、GUID、NOTIFICATIONCONTENTNAME、NOTIFICATIONDEFINITIONNAME、STYLETHEMENAME 與 THINGGROUPNAME。
|
• 只有值不會頻繁變更或完全不會變更的內容才應考慮索引。不應考慮頻繁變更的內容。索引內容的範例包括型號或序號。針對固定設備、城市、州或地區，則也可以考慮。
|
|
絕不應索引遙測資料。
|
• 呼叫 QueryImplementingThingsOptimized 時是否可能會使用內容？所有索引內容也會持續存在，因此也應考慮索引內容是否會提供實用的優點。持續屬性會增加 ThingWorx 的負擔，因此不應索引將不會用於 QueryImplementingThingsOptimized 的內容。
配置索引內容
「索引」設定位於實體的內容部份中。如需詳細資訊，請參閱物件內容。
索引位元組限制
由於索引位元組長度的條件約束，字串內容有下列限制：
• 當使用 MS SQL 或 Azure SQL 作為持續性提供者時，字串會限制為1500個位元組。字串會以 UTF-16 儲存在 MS SQL 與 Azure SQL 中。
• 使用 PostgreSQL 作為持續性提供者時，字串限制為 1000 個位元組。字串會以 UTF-8 儲存在 PostgreSQL 中。
• 超過最大位元組長度的字串值不會新增至索引，且不會顯示在索引查詢中。如果發生此情況，會在應用程式記錄檔中新增錯誤，指出值太大且未索引。雖然不會索引字串值，但會儲存該值並保持持續。GetPropetyValues 等 API 仍可擷取儲存的值，且值將在重新啟動後可用。如果您擔心字串值可能超過最大位元組限制，則可以建立在資料變更事件上建立的通知。
預設內容的支援
下表列出了存在於所有物件上且支援索引查詢的內容。
|
內容名稱
|
內容類型
|
是否支援索引查詢？
|
|---|---|---|
|
name
|
STRING
|
是
|
|
description
|
STRING
|
是
|
|
tags
|
TAGS
|
是
|
|
isSystemObject
|
BOOLEAN
|
否
|
|
homeMashup
|
STRING
|
否
|
|
avatar
|
IMAGE
|
否
|
|
projectName
|
STRING
|
否
|
|
thingTemplate
|
STRING
|
是
|
QueryImplementingThingsOptimized 使用者輸入參數
執行 QueryImplementingThingsOptimized 時可執行下列操作。
|
操作名稱
|
註記
|
可能的最佳化狀態 (如果在請求上提供且非 null)
|
||
|---|---|---|---|---|
|
ResultDefinition
|
透過 API 呼叫上的 basicPropertyNames 與 propertyNames 參數指定。
• basicPropertyNames - 要傳回的基本內容清單。
• propertyNames - 內建及實行要傳回之實體內容的清單。
|
• 若已索引所有請求的內容定義，QueryImplementingThingsOptimized 會執行索引查詢以產生結果集。
• 若已對某些請求的內容定義執行索引，且支援此操作，QueryImplementingThingsOptimized 將會針對索引內容執行索引查詢，並使用該結果集來在記憶體中快取查詢非索引內容。
• 若未索引任何請求的內容定義，或參數為 NULL，則 QueryImplementingThingsOptimized 會查詢記憶體中快取。
|
||
|
NameMask
|
與物件名稱進行比對的類似遮罩的模式。
|
NameMask 對 QueryImplementingThingsOptimized 是否使用索引查詢沒有任何影響。
|
||
|
NetworkName
|
指定實行物件必須屬於的網路名稱。可以提供提示。例如，您可以提供網路最大深度與父網路名稱，以協助縮小搜尋範圍。
|
QueryImplementingThingsOptimized 會針對記憶體中快取進行查詢。
|
||
|
Tags
|
實體必須標記才能包括在結果中的標籤清單。
|
QueryImplementingThingsOptimized 會針對標籤使用索引查詢。
|
||
|
Offset
|
要開始查詢的位移，用於分頁。例如，如果資料庫中有 200 個結果的位移為 5，會傳回 5 至 200 的結果 (總數為 195)。
|
位移對 QueryImplementingThingsOptimized 是否使用索引查詢沒有任何影響。
|
||
|
Sort
|
要套用至最終結果的排序。
|
• 如果在排序中定義的所有內容皆已索引，QueryImplementingThingsOptimized 將會執行索引查詢以產生結果集。
• 若未索引排序中的某些內容，QueryImplementingThingsOptimized 將會針對記憶體中快取進行查詢。
|
||
|
Query
|
要套用至結果記錄的篩選器。
|
• 若已索引所有請求的內容定義，QueryImplementingThingsOptimized 將會執行索引查詢以產生結果集。
• 若已對某些請求的內容定義執行索引，且支援此操作，QueryImplementingThingsOptimized 將會針對索引內容執行索引查詢，並使用該結果集來在記憶體中快取查詢非索引內容。
• 若未索引任何請求的內容定義，QueryImplementingThingsOptimized 將會查詢記憶體中的快取。
|
||
|
Limit
|
要包括在結果中的最大項目數。
|
Limit 對 QueryImplementingThingsOptimized 是否使用索引查詢沒有任何影響。
|
提示
可以在 QueryImplementingThingsOptimized 的查詢參數中包括提示來禁用的資料庫索引查詢。
|
Hint
|
是否必要？
|
預設
|
動作
|
|---|---|---|---|
|
optimizationDisabled
|
否
|
未包括
|
• 若未指定查詢、提示未包括在查詢中或為 false，QueryImplementingThingsOptimized 將會嘗試如上所述查詢。
|
將不會使用索引查詢的查詢範例，其中 TT_1_Boolean1 是索引內容：
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 */ ,
內容基礎類型移轉
您可以變更現有內容的內容基礎類型。為支援索引內容，存在下列移轉情況：
• 如果內容具有設定值，ThingWorx 會嘗試將內容值轉換為新的基礎類型。例如，如果將值為 "String123" 的字串內容轉換為整數，則新整數值將為 123。相反地，如果將 123 的整數內容轉換為字串，內容將會是 "123"。
• 若未設定內容值，且新基礎類型具有已定義的預設值，則其將用於所有查詢。
• 若未定義內容預設值，ThingWorx 會使用新基礎類型的預設值。例如，整數與數字會設定為零 (0)，且字串會設定為空白字串 ("")。
範例
以下兩個表格提供查詢將使用索引查詢的範例。第一個表格中詳細說明了範例模型，第二個表格則詳細說明了 QueryImplementingThingsOptimized 的範例行為。
模型
下列模型展示了索引內容的用法。範例模型使用物範本，其中包含以該範本為基礎的兩個物件。使用由物範本實行的物形式也可以達成此繼承結果。
|
實體名稱
|
實體類型
|
實行
|
內容名稱
|
內容類型
|
內容已索引？
|
|---|---|---|---|---|---|
|
TestThingTemplate1
|
ThingTemplate
|
GenericThing
|
p1
|
INTEGER
|
是
|
|
p2
|
STRING
|
是
|
|||
|
p3
|
INTEGER
|
否
|
|||
|
p4
|
STRING
|
否
|
|||
|
TestThing1
|
Thing
|
TestThingTemplate1
|
繼承的
|
繼承的
|
繼承的
|
|
TestThing2
|
Thing
|
TestThingTemplate1
|
繼承的
|
繼承的
|
繼承的
|
|
情況
|
範例
|
索引查詢已使用？
|
註解
|
|---|---|---|---|
|
支援所有操作，且完全支援篩選器。
|
{"sorts":[{"fieldName":"p1"}],"filters":{"type":"And","filters":[{"type":"EQ","fieldName":"p2","value":"12"},
{"type":"EQ","fieldName":"p1","value":"13"}]}} |
是
|
只查詢索引內容，因此這將會使用索引查詢。
|
|
支援所有操作，且部份支援篩選器。
|
{"sorts":[{"fieldName":"p1"}],
"filters":{"type":"And","filters":[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
是
|
ThingWorx 將針對內容 P1 執行索引查詢，然後針對 P4 的該結果集快取查詢。
|
|
支援所有操作，且不支援篩選器。
|
{"sorts":[{"fieldName":"p1"}],"filters":
{"type":"Or","filters":[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
否
|
ThingWorx 會因 OR 篩選器而執行完整快取查詢，因此索引查詢不會提供任何好處。
|
|
支援所有操作，無篩選器。
|
{"sorts":[{"fieldName":"p1"}]}
|
否
|
沒有可篩選的內容，因此不會執行查詢。
|
|
支援某些操作，且完全支援篩選器。
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"And","filters":
[{"type":"EQ","fieldName":"p2","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
是
|
索引所有篩選的欄位，因此此查詢將會使用索引查詢。
|
|
支援某些操作，且部份支援篩選器。
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"And","filters":
[{"type":"EQ","fieldName":"p4","value":"12"},{"type":"EQ","fieldName":"p1","value":"13"}]}} |
是
|
這與列 2 中的範例相同，但例外是排序在非索引內容上。
|
|
支援某些操作，且不支援篩選器。
|
{"sorts":[{"fieldName":"p4"}],"filters":{"type":"Or","filters":[{"type":"EQ","fieldName":"p4","value":"12"},
{"type":"EQ","fieldName":"p1","value":"13"}]}} |
否
|
篩選器與列 3 中的範例相同，因此此查詢不支援索引查詢。
|
|
支援某些操作，且不提供篩選器。
|
{"sorts":[{"fieldName":"p4"}]}
|
否
|
沒有要篩選的內容，因此這不受支援。
|
|
會查詢標籤，不提供篩選器。
|
是
|
索引查詢支援對標籤的查詢。
|
最佳實務
• 測試應用程式的效能，確定是否應針對您的特定使用案例禁用查詢最佳化。
• 當索引查詢傳回模型的小子集時，這些查詢的效能最佳。搜尋單一物件將會提供最大的改善效果。例如，按序號查詢單一物件將會提供最佳效能改善效果。
◦ 如果查詢傳回模型的 80% 或更多內容，請使用提示來禁用索引查詢。
• 變更內容基礎類型是一項成本很高的操作，因為物範本或物形式層級的變更將必須傳播至所有實行實體。在大型模型上，這可能會花費大量的時間與資源。
◦ 當系統正在執行擷取時，請勿修改內容基礎類型。
◦ 請確保持續性提供者的最大佇列大小足夠大，可容納新增索引內容或變更索引內容基礎類型時將會發生的持續內容寫入數。最大佇列大小應大於內容寫入數。寫入數將等於修改的內容數乘以實行該內容的物件數。例如，您的模型包括由 10,000 個物件實行的物範本。如果您變更該範本上兩個內容的基礎類型，則會對持續性內容寫入佇列產生 20,000 次寫入 (2 個內容 X 10,000 個物件)。最大佇列大小的預設大小為 100,000 次寫入，因此在此範例中，您將會有足夠的資源可以操作。