색인화된 속성
ThingWorx 9.3 이상에서 속성을 색인화하여 더 빠른 질의를 허용할 수 있습니다. 자주 변경하지 않는 속성만 색인화해야 합니다. 예를 들어, 모델 번호, 일련 번호, 도시 또는 지역입니다. ThingWorx에서 색인화될 때 속성 값은 속성 지속성 공급자에 저장됩니다. 여기서 속성 값은 QueryImplementingThingsOptimized 및 QueryImplementingThingsOptimizedCount API를 사용할 때 더 빠른 질의를 허용하도록 데이터베이스에서 색인화됩니다.
질의에 색인화된 속성만 포함된 경우 해당 질의는 데이터베이스 질의로만 실행됩니다.
질의에 색인화된 속성과 색인화되지 않은 속성이 혼합되어 있는 경우 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을 지속성 공급자로 사용하면 문자열은 1,500바이트로 제한됩니다. 문자열은 MS SQL 및 Azure SQL에 UTF-16으로 저장됩니다.
• PostgreSQL을 지속성 공급자로 사용하면 문자열은 1,000바이트로 제한됩니다. 문자열은 PostgreSQL에 UTF-8로 저장됩니다.
• 최대 바이트 길이를 초과하는 문자열 값은 색인에 추가되지 않으며 색인화된 질의에 나타나지 않습니다. 이 경우 값이 너무 커서 색인화되지 않았음을 나타내는 오류가 응용 프로그램 로그에 추가됩니다. 문자열 값은 색인화되지 않아도 저장되고 지속됩니다. 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
|
페이지 매김에 사용되는 질의 시작 오프셋입니다. 예를 들어, 데이터베이스에 오프셋이 5인 200개의 결과가 있는 경우 5개~ 200개(합계: 195개)의 결과가 반환됩니다.
|
Offset은 QueryImplementingThingsOptimized가 색인 질의를 사용하는지 여부에 영향을 미치지 않습니다.
|
||
|
Sort
|
최종 결과에 적용할 정렬입니다.
|
• 정렬에 정의된 모든 속성이 색인화된 경우 QueryImplementingThingsOptimized는 색인 질의를 실행하여 결과 집합을 생성합니다.
• 정렬의 일부 속성이 색인화되지 않은 경우 QueryImplementingThingsOptimized는 메모리 내 캐시에 대해 질의합니다.
|
||
|
Query
|
결과 기록에 적용할 필터입니다.
|
• 요청된 모든 속성 정의가 색인화된 경우 QueryImplementingThingsOptimized는 색인 질의를 실행하여 결과 집합을 생성합니다.
• 일부 요청된 속성 정의가 색인화되고 작업이 지원되는 경우 QueryImplementingThingsOptimized는 색인화된 속성에 대해 색인화된 질의를 실행하고 해당 결과 집합을 사용하여 색인화되지 않은 속성에 대해 메모리 내 캐시를 질의합니다.
• 요청된 속성 정의 중 어떤 정의도 색인화되지 않은 경우 QueryImplementingThingsOptimized는 메모리 내 캐시를 질의합니다.
|
||
|
Limit
|
결과에 포함할 최대 항목 수입니다.
|
제한은 QueryImplementingThingsOptimized가 색인 질의를 사용하는지 여부에 영향을 미치지 않습니다.
|
힌트
QueryImplementingThingsOptimized의 질의 매개 변수에 힌트를 포함하여 데이터베이스 색인 질의를 비활성화할 수 있습니다.
|
힌트
|
필수 여부
|
기본값
|
작업
|
|---|---|---|---|
|
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
|
Inherited
|
Inherited
|
Inherited
|
|
TestThing2
|
Thing
|
TestThingTemplate1
|
Inherited
|
Inherited
|
Inherited
|
|
시나리오
|
예
|
색인 질의 사용 여부
|
설명
|
|---|---|---|---|
|
모든 작업이 지원되며 필터가 완전히 지원됩니다.
|
{"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"}]}} |
예
|
이는 SORT가 색인화되지 않은 속성에 있다는 점을 제외하고 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번 쓰기이므로 이 예에서는 해당 작업을 위한 충분한 리소스를 갖고 있습니다.