1 Alfresco クエリアクセラレータ
- 1.1 運用の概要
- 1.2 プロパティをインストールする
  - 1.2.1 プロパティの例
- 1.3 構成
- 1.4 クエリセット構成例
  - 1.4.1 例１
  - 1.4.2 例２
- 1.5 クエリセットと TMDQ クエリ
- 1.6 クエリセットのステータスとキャッシング
- 1.7 ログの記録

Alfresco クエリアクセラレータ

クエリアクセラレータは、非常に大規模なコンテンツリポジトリにおいて、選択されたクエリを最適化するためのメカニズムです。この機能は、人が文書を作成する従来のコラボレーション型のコンテンツ管理システムではなく、他のシステムから文書を自動的にインポートする、数億ノードの大規模トランザクションの展開に対応するために使用することをお勧めします。トランザクションの展開では、通常、ケース ID のほか、一連の関連文書を識別する1つまたは2つのプロパティがあります。

管理者は、プロパティとアスペクトの組み合わせをquery setとして定義することで、Transactional Metadata Query（TMDQ）や Solr に代わる、さらに高速な機能をサポートできます。プロパティは、複数のタイプまたはアスペクトに含めることができます。共通の検索プロパティまたはアスペクトを持つクエリであれば、1つのクエリセットで複数のクエリを高速化できます。異なる検索プロパティまたはアスペクトを持つクエリに対応するために、複数の異なるクエリセットを作成することも可能です。

このパフォーマンスを実現するには、非正規化データベーステーブルとインデックスのための追加スペースを確保する必要があるほか、データの取得と更新のために必要最小限の時間を割く必要があります。このことから、ある決断が導き出されます。つまり、クエリセットに多くのプロパティを含めたり、クエリセットを多数作成したりすることは、コストがかさむばかりか、一般的にデータモデルの設計に何らかの問題があると示唆されるため、避けるべきであると判断できます。

運用の概要

クエリセットは、既存の Alfresco リポジトリに適用できます。たとえば、7.0.0にアップグレードされ、既に数億もの文書を格納しているシステムに、クエリセットを適用することができます。
複数のクエリセット（0個以上、ただし通常は10個以下）を定義できます。各クエリセットは独自の名前を持ちます。クエリセットを新しいバージョンに置き換えたり、完全に削除したりすることも可能です。定義には、各ノードに適用されるプロパティまたはアスペクト、必要であれば（一部のデータベースでは）複合インデックスのカラムの順序を含めることができます。クエリセットは JSON ファイルで定義します。
管理者は、管理コンソールでクエリセットの更新を実行します。新しいクエリセットを追加する、既存のクエリセットを置き換える、完全に削除する場合でも、再起動や停止を必要とせず、通常業務に大きな影響を与えることはありません。alfresco.log には、進捗状況を反映したメッセージが記録されます。新しいクエリセットが特定されると、システムはバックグラウンドで非正規化テーブルへのデータの読み込みを開始します。また、新しいバージョンのクエリセットが作成されると、テーブルへのデータの読み込みが完了する前に読み込みを中止します。実装では、クエリセットを識別し、旧バージョンが必要かを識別して、クエリセットを削除できることを通知するメッセージを alfresco.log に出力する必要があります。
非正規化テーブルが作成され、データの読み込みが完了すると、自動的に利用が開始されます。
クエリアクセラレータは、アトミックな（トランザクションの整合性が保たれた）結果を提供します。
クエリアクセラレータは、Enterprise 版でのみ提供されている機能です。

プロパティをインストールする

queryAccelerator.enabled プロパティを true に設定してクエリアクセラレータを有効にします。
queryAccelerator.config.dir プロパティを設定してクエリアクセラレータの構成ファイルの場所を定義します。
各データ読み込みバッチの大きさを定義します。

プロパティの例

queryAccelerator.enabled=true
queryAccelerator.config.dir=shared/classes/alfresco/extension/querysets
queryAccelerator.populator.workerBatchSize=5000

開発で Docker Compose を使用している場合、実行中の ACS リポジトリのコンテナにクエリセット定義をコピーする必要があります。その方法の1つとして、次のコマンドを使用します。

docker cp custom_queryset.json <alfresco container>:/usr/local/tomcat/shared/classes/alfresco/extension/querysets/

Kubernetes 環境では、ConfigMaps を使用してクエリセット定義を追加できます。この場合、JSON ファイルから ConfigMap を作成し、ボリュームを介して ACS リポジトリのポッドにマウントする必要があります。

kubectl create configmap custom-queryset-config --from-file=name_of_a_file.json

必要なボリュームはすぐに使える状態で提供されており、ConfigMap custom-queryset-config 内のファイルは /usr/local/tomcat/shared/classes/alfresco/extension/querysets/ にマウントされます。

注意：（ Kubernetes の文書より）：mountPath の場所にファイルがある場合、それらは削除されます。

構成

以下の情報を使用して、クエリアクセラレータの構成を行います。クエリセット構成は、高速なクエリに対応するために作成される非正規化テーブルを定義します。

属性	説明

属性	説明
バージョン version	クエリセットのバージョン。
名前 name	テーブル名。実際のデータベーステーブル名には、先頭に「alf_qs_」、末尾に「_v＋バージョン」が付きます。つまり、クエリセットの名前が「test1」で、バージョンが「1」の場合、実際のデータベーステーブル名は「alf_qs_test1_v1」となります。
プロパティ properties	非正規化テーブルに表示されるプロパティのコレクション。プロパティは、name 属性（プロパティの名前）と isIndex 属性（テーブル上の関連するカラムにインデックスを付ける必要があることを示す）から構成されています。
アスペクト aspects	非正規化テーブルに表示されるアスペクトのコレクション。テーブルには、アスペクトごとにブール値のカラムがあります。このブール値は、ノードにこれらのアスペクトが適用されているかどうかを示します。アスペクトは、name 属性（アスペクトの名前）と isIndex 属性（テーブル上の関連するカラムにインデックスを付ける必要があることを示す）から構成されています。
複合インデックス compositeIndexes	テーブル用に作成される複合インデックスのコレクション。複合インデックスは、属性名がインデックス名、属性値がクエリセットのプロパティ名またはアスペクト名のコレクションである属性で構成されます。

クエリセット名とバージョンの最大長は、使用するデータベースシステムのテーブル名の長さの最大値から9を引いた値です。Postgres の場合、テーブル名の長さの最大値は63バイトなので、クエリセット内の名前とバージョンの最大長は54バイトとなります。
アスペクトの否定を含むクエリは、高速化する必要はありません。
MLTEXT 型のプロパティはサポートしていません。この型のプロパティが含まれていると、WARN メッセージが記録され、当該プロパティは無視され、対応する非正規化テーブルは、このプロパティを除外して作成されます。
非正規化テーブルには、コンテンツタイプの名前を持つ alf_type カラムがあります。
アスペクトが使用されている場合、1つ以上のアスペクトを持つノードのみが非正規化テーブルに含まれることになります。このため、あるアスペクトが存在しないことを確認するためのクエリは、クエリアクセラレータを使用せず、標準エンジンで実行されます。
構成で定義された監査可能なプロパティ（cm:creator、cm:created、cm:modifier、cm:modified、cm:accessed）は無視されます。このタイプのデータは常に利用可能であり、対応する非正規化テーブルに格納する必要はありません。
構成で定義された以下の型のプロパティは無視されます。これらのプロパティは既に非正規化テーブルに含まれているため、構成に含まれていると WARN メッセージが記録されます。
- cm:owner
- cm:noderef
- sys:node-dbid
- sys:node-uuid
queryAccelerator.config.dirディレクトリからファイルを読み取る場合、ファイルは英数字順に読み取られます。つまり、0101-coyote.json は、0102-coyote.json や 0201-acme.json よりも前に読み取られることになります。

クエリセット構成例

例１

この最初の例は、意図的にシンプルにしていますが、どのようなシステムでも動作するはずなので、システムの動作の基本を理解するのに役立ちます。

ACSノードのプロパティ：

テーブルのエントリ：

node_id	owner_id	alf_type	cm_name	cm_author	cm_titled

node_id	owner_id	alf_type	cm_name	cm_author	cm_titled
887	3	24	demo1.txt	Joe Bloggs	true

例２

次の例では、システム内の少なくとも1つのノードに DublinCore アスペクトが適用されている必要があります。このアスペクトは、デフォルトでシステムの一部をなします。ノードが存在しない場合は、不明なプロパティエラーが報告されます。

ACSノードのプロパティとアスペクト：

テーブルのエントリ：

node_id	owner_id	alf_type	cm_name	cm_publisher	cm_titled	cm_dublincore

node_id	owner_id	alf_type	cm_name	cm_publisher	cm_titled	cm_dublincore
918	3	24	demo2	Egmont	true	true

クエリセットと TMDQ クエリ

ここでは、TMDQ を置き換えるクエリセットの作成方法を例に説明します。
次の TMDQ は、アスペクトが DublinCore（cm:dublincore）、公開元（cm:publisher）が「Hachette Livre」、型（cm:type）が「Action」である文書（cm:content）をすべて選択します。

次のクエリセットであれば、上記の TMDQ に対応できます。また、システム内の1つ以上のノードに DublinCore アスペクトが適用されている必要があります。

クエリセットのステータスとキャッシング

非正規化テーブルには、ステータスがあります。以下がその例です。

Name	Version	State	Notes

Name	Version	State	Notes
tableA	1	OBSOLETE	Should be removed
tableA	2	RETIRED	Can be removed
tableA	3	LIVE	Currently being used
tableA	4	INPROGRESS	Created but not fully populated yet, so cannot be used
tableA	5	NEW	Seen but population of denormalized data has not started

通常、NEW から INPROGRESS への移行は、ほぼすぐに行われます。

ログの記録

現在、管理コンソールによって示されるのは、更新が検出されたかどうかのみです。クエリセット構成の全体像をより詳細に把握するには、DEBUG のログを使用する必要があります。

クエリセットの更新が実行されたが、更新がなかった場合のログ：

クエリセットの更新が開始された場合のログ：

クエリエンジンの詳細なログを取得することも可能です。次の例に示すように、これらの詳細なログは、DEBUG レベルを有効にすることにより、クエリに基づき、クエリセットの選択プロセスに関する情報を提供します。

クエリがエンジンに受け入れられた場合のログ：

クエリがエンジンに拒否された場合のログ：

クエリセットの削除

管理コンソールで削除を実行すると、クエリセットを削除できます。クエリセットを削除した後に更新を実行する必要ありませんが、該当する JSON 構成ファイルを、構成ディレクトリから手動で削除する必要があります。

更新の際、JSON 構成ファイルは、内部のクエリセットレジストリと比較されます。レジストリ内で、当該クエリセットと同じ tableName を持つ JSON 構成ファイルがない場合、警告が記録されます。非正規化データベーステーブルは削除されません。

クエリセットの更新

クエリセットの JSON 構成の properties、aspects、compositeIndexes を変更することにより、クエリセットを更新または置換できます。
その後、クエリセットの JSON 構成内のバージョンを更新し、管理コンソールでクエリセットの更新を実行する必要があります。

これにより、旧バージョンのクエリセットを置き換える処理が開始されます。

新しいバージョンのクエリセットが、内部のクエリセットレジストリに追加されます。
新しいバージョンの非正規化テーブルが作成されます。
新しいバージョンに置き換わるまでの間、旧バージョンの非正規化テーブルが使用され続けます。
新しいバージョンの非正規化テーブルにデータが読み込まれます。 Alfresco のインストールの規模によって、データの読み込みにかなりの時間がかかる場合があります。
データ読み込み完了後の動作：
- クエリセットは、LIVE としてフラグ設定されます。
- 旧バージョンのクエリセットは、RETIRED としてフラグ設定されます。
- 管理コンソールの [クエリセットを削除]ボタンを使用して旧バージョンの非正規化テーブルを手動で削除できるようになります。

重要：クエリセット構成を編集して名前を変更し、クエリセットの更新を要求した場合、システムはこれを元のクエリセットの破棄と新しいクエリの作成とみなします。

管理コンソールによるクエリセットの更新

クエリセットは、管理コンソールで更新することができます。

左側のメニューからクエリアクセラレータを選択します。

2. 更新クエリセットボタンをクリックします。

queryAccelerator.config.dirで定義されたフォルダ（通常は shared/classes/alfresco/extension/querysets ）にあるクエリセットに更新があった場合、次のように表示されます。

クエリセットに更新がなかった場合は、次のように表示されます。

管理コンソールによるクエリセットの削除

クエリセットは、管理コンソールで削除することができます。

クエリアクセラレータページで、クエリセット名とバージョンのテキストフィールドを入力します。
クエリセットを削除ボタンをクリックします。

クエリセットが正常に削除されると、次のように表示されます。

一致するクエリセットが見つからない場合は、次のように表示されます。