複数のリソースが集まり、Droongaネットワークを構成します。それらのリソースを カタログ に記述しなければいけません。ネットワーク上のすべてのノードは同じカタログを共有します。
このドキュメントはカタログについて説明します。
今のところ、カタログを書くことも書いたカタログをすべてのノードで共有することも手動で行う必要があります。
近い将来、カタログを生成するユーティリティープログラムを提供する予定です。さらにその後、Droongaネットワークは自動でカタログの管理やカタログの配布を行うようになる予定です。
このセクションではカタログに出てくる用語を説明します。
カタログはネットワーク内のリソースを表現するデータの集まりです。
ゾーンはファームの集まりです。同じゾーン内のファームはお互いに近くに配置することが期待されています。例えば、同じホスト内、同じスイッチ内、同じネットワーク内といった具合です。
ファームはDroongaエンジンのインスタンスです。DroongaエンジンはFluentdのプラグインfluent-plugin-droongaとして実装されています。
1つの fluentd プロセスは複数のDroongaエンジンを持てます。 fluentd.conf に droonga タイプの match エントリーを1つ以上追加すると、 fluentd プロセスは同じ数のDroongaエンジンのインスタンスを生成します。
ファームは複数のワーカーと1つのジョブキューを持ちます。ファームはリクエストをジョブキューに投入します。ワーカーはジョブキューからリクエストを取り出します。
データセットは論理テーブルの集まりです。論理テーブルは1つのデータセットに所属しなければいけません。
各データセットの名前は同じDroongaネットワーク内で重複してはいけません。
論理テーブルはパーティションされた1つ以上の物理テーブルで構成されます。論理テーブルは物理レコードを持ちません。物理テーブルから物理レコードを返します。
1つの論理テーブルを1つ以上の物理テーブルにどうやってパーティションするかをカスタマイズできます。例えば、パーティションキーやパーテション数をカスタマイズできます。
物理テーブルはGroongaデータベースのテーブルです。Groongaのテーブルに物理レコードを保存します。
リングはパーティションセットの集まりです。データセットは必ず1つのリングを持ちます。データセットはリング上に論理テーブルを作ります。
Droongaエンジンは物理テーブル上にあるレコードを1つ以上のパーティションセットに複製します。
パーティションセットはパーティションの集まりです。1つのパーティションセットは同じDroongaネットワーク内のすべての論理テーブルのすべてのレコードを保存します。言い換えると、データセットは1つのパーティションセットの中でパーティションされます。
1つのパーティションセットは他のパーティションセットの複製です。
将来、Droongaエンジンは1つ以上のパーティションセット内でのパーティションをサポートするかもしれません。古いデータと新しいデータで異なるパーティションサイズを使うことができるので便利でしょう。通常、古いデータは小さく、新しいデータは大きくなります。大きなデータに大きなパーティションサイズを使うのは妥当なことです。
1つのパーティションは1つのGroongaデータベースに対応します。0個以上の物理テーブルを持ちます。
Droonga Engine can be extended by writing plugin scripts. In most cases, a series of plugins work cooperatively to achieve required behaviors. So, plugins are organized by behaviors. Each behavior can be attached to datasets and/or tables by adding “plugins” section to the corresponding entry in the catalog.
More than one plugin can be assigned in a “plugins” section as an array. The order in the array controls the execution order of plugins when adapting messages. When adapting an incoming message, plugins are applied in forward order whereas those are applied in reverse order when adapting an outgoing message.
Consider the following case:
Catalog is written as a JSON file. Its file name is catalog.json.
Here is a catalog.json for the above case:
{
"version": 1,
"effective_date": "2013-06-05T00:05:51Z",
"zones": ["localhost:23003/farm0", "localhost:23003/farm1"],
"farms": {
"localhost:23003/farm0": {
"device": "disk0",
"capacity": 1024
},
"localhost:23003/farm1": {
"device": "disk1",
"capacity": 1024
}
},
"datasets": {
"Wiki": {
"workers": 4,
"plugins": ["groonga", "crud", "search"],
"number_of_replicas": 2,
"number_of_partitions": 2,
"partition_key": "_key",
"date_range": "infinity",
"ring": {
"localhost:23004": {
"weight": 10,
"partitions": {
"2013-07-24": [
"localhost:23003/farm0.000",
"localhost:23003/farm1.000"
]
}
},
"localhost:23005": {
"weight": 10,
"partitions": {
"2013-07-24": [
"localhost:23003/farm1.001",
"localhost:23003/farm0.001"
]
}
}
}
}
}
}
Here are descriptions about parameters in catalog.json.
versionIt is a format version of the catalog file.
Droonga Engine will change catalog.json format in the
future. Droonga Engine can provide auto format update feature with the
information.
The value must be 1.
This is a required parameter.
Example:
{
"version": 1
}
effective_dateIt is a date string representing the day the catalog becomes effective.
The date string format must be W3C-DTF.
This is a required parameter.
Note: fluent-plugin-droonga 0.8.0 doesn’t use this value yet.
Example:
{
"effective_date": "2013-11-29T11:29:29Z"
}
zonesZones is an array to express proximities between farms.
Farms are grouped by a zone, and zones can be grouped by another zone recursively.
Zones make a single tree structure, expressed by nested arrays.
Farms in a same branch are regarded as relatively closer than other farms.
e.g.
When the value of zones is as follows,
[["A", ["B", "C"]], "D"]
it expresses the following tree.
/\
/\ D
A /\
B C
This tree means the farm “B” and “C” are closer than “A” or “D” to each other.
You should make elements in a zones close to each other, like in the
same host, in the same switch, in the same network.
This is an optional parameter.
Note: fluent-plugin-droonga 0.8.0 doesn’t use this value yet.
Example:
{
"zones": [
["localhost:23003/farm0",
"localhost:23003/farm1"],
["localhost:23004/farm0",
"localhost:23004/farm1"]
]
}
TODO: Discuss about the call of this parameter. This seems completely equals to the list of keys of farms.
farmsIt is an array of Droonga Engine instances.
TODO: Improve me. For example, we have to describe relations of nested farms, ex. children.
Farms correspond with fluent-plugin-droonga instances. A fluentd process may have multiple farms if more than one match entry with type droonga appear in the “fluentd.conf”. Each farm has its own job queue. Each farm can attach to a data partition which is a part of a dataset.
This is a required parameter.
Example:
{
"farms": {
"localhost:23003/farm0": {
"device": "/disk0",
"capacity": 1024
},
"localhost:23003/farm1": {
"device": "/disk1",
"capacity": 1024
}
}
}
datasetsA dataset is a set of tables which comprise a single logical table virtually. Each dataset must have a unique name in the network.
ringring is a series of partitions which comprise a dataset. replica_count, number_of_partitons and time-slice factors affect the number of partitions in a ring.
workersworkers is an integer number which specifies the number of worker processes to deal with the dataset.
If 0 is specified, no worker is forked and all operations are done in the master process.
number_of_partitionsnumber_of_partition is an integer number which represents the number of partitions divided by the hash function. The hash function which determines where each record resides the partition in a dataset is compatible with memcached.
date_rangedate_range determines when to split the dataset. If a string “infinity” is assigned, dataset is never split by time factor.
number_of_replicasnumber_of_replicas represents the number of replicas of dataset maintained in the network.