カタログ

概要

CatalogはDroongaクラスタの設定を管理するためのJSONデータです。Droongaクラスタは1つ以上のdatasetsからなり、datasetはその他の部分からなります。それらは全てcatalogに記述し、クラスタ内の全てホストで共有しなければなりません。

使い方

この versioncatalog は Droonga 1.0.0 以降で有効です。

書式

{
  "version": <Version number>,
  "effectiveDate": "<Effective date>",
  "datasets": {
    "<Name of the dataset 1>": {
      "nWorkers": <Number of workers>,
      "plugins": [
        "Name of the plugin 1",
        ...
      ],
      "schema": {
        "<Name of the table 1>": {
          "type"             : <"Array", "Hash", "PatriciaTrie" or "DoubleArrayTrie">
          "keyType"          : "<Type of the primary key>",
          "tokenizer"        : "<Tokenizer>",
          "normalizer"       : "<Normalizer>",
          "columns" : {
            "<Name of the column 1>": {
              "type"         : <"Scalar", "Vector" or "Index">,
              "valueType"    : "<Type of the value>",
              "vectorOptions": {
                "weight"     : <Weight>,
              },
              "indexOptions" : {
                "section"    : <Section>,
                "weight"     : <Weight>,
                "position"   : <Position>,
                "sources"    : [
                  "<Name of a column to be indexed>",
                  ...
                ]
              }
            },
            "<Name of the column 2>": { ... },
            ...
          }
        },
        "<Name of the table 2>": { ... },
        ...
      },
      "fact": "<Name of the fact table>",
      "replicas": [
        {
          "dimension": "<Name of the dimension column>",
          "slicer": "<Name of the slicer function>",
          "slices": [
            {
              "label": "<Label of the slice>",
              "volume": {
                "address": "<Address string of the volume>"
              }
            },
            ...
          }
        },
        ...
      ]
    },
    "<Name of the dataset 2>": { ... },
    ...
  }
}

詳細

Catalog 定義

以下のキーと値のペアを持つオブジェクト。

パラメータ

version
概要
カタログファイルのバージョン番号。
2. (このページに記述されている仕様はこの値が2のときのみ有効です)
既定値
なし。これは必須のパラメータです。
継承可能性
不可。
effectiveDate
概要
このカタログが有効になる時刻。
W3C-DTF でフォーマットされたタイムゾーン付きの時刻。
既定値
なし。これは必須のパラメータです。
継承可能性
不可。
datasets
概要
データセットの定義。

データセット名をキーとし、dataset 定義 を値とするオブジェクト。

既定値
なし。これは必須のパラメータです。
継承可能性
不可。
nWorkers
概要
データベースインスタンス毎にspawnされるワーカの数。
整数。
既定値
0 (ワーカー無し。全ての処理がマスタープロセス内で行われます)
継承可能性
可。datasetvolumeの定義でオーバライドできます。

A version 2 catalog effective after 2013-09-01T00:00:00Z, with no datasets:

{
  "version": 2,
  "effectiveDate": "2013-09-01T00:00:00Z",
  "datasets": {
  }
}

Dataset 定義

以下のキーと値のペアを持つオブジェクト。

パラメータ

plugins
概要
このデータセットにおいて有効にするプラグイン名文字列の配列。
文字列の配列。
既定値
なし。これは必須のパラメータです。
継承可能性
可。datasetvolumeの定義でオーバライドできます。
schema
概要
テーブルとそのカラムの定義。
テーブル名をキーとし、table 定義を値とするオブジェクト。
既定値
なし。これは必須のパラメータです。
継承可能性
可。datasetvolumeの定義でオーバライドできます。
fact
概要
fact テーブルの名前。datasetが複数のsliceに格納される場合、schemaパラメータで定義されたテーブルの中から、1つfact tableを選択する必要があります。
文字列。
既定値
なし。
継承可能性
可。datasetvolumeの定義でオーバライドできます。
replicas
概要
互いに複製されるボリュームの集合。
volume 定義の配列。
既定値
なし。これは必須のパラメータです。
継承可能性
不可。

データベースインスタンスに1つにつき4ワーカーを持ち、プラグインgroongacrudsearchを使用するデータセット:

{
  "nWorkers": 4,
  "plugins": ["groonga", "crud", "search"],
  "schema": {
  },
  "replicas": [
  ]
}

Table 定義

以下のキーと値のペアを持つオブジェクト。

パラメータ

type
概要
テーブルのキーを管理するためのデータ構造を指定する。
以下のうちいずれかの値。
既定値
"Hash"
継承可能性
不可。
keyType
概要
テーブルにおけるキーのデータ型。type"Array"の場合は指定してはいけません。
以下のデータ型のうちのいずれか。
既定値
なし。キーを持つテーブルでは指定が必須です。
継承可能性
不可。
tokenizer
概要
語彙表として使われるテーブルにおける、文字列型の値を分割するために使うトークナイザーの種類を指定します。keyType"ShortText"である場合にのみ有効です。
以下のトークナイザー名のうちのいずれか。
既定値
なし。
継承可能性
不可。
normalizer
概要
キーの値を正規化・制限するノーマライザーの種類を指定します。keyType"ShortText"である場合にのみ有効です。
以下のノーマライザー名のうちのいずれか。
既定値
なし。
継承可能性
不可。
columns
概要
テーブルのカラムの定義。
Value
An object keyed by the name of the column with value the column definition.
既定値
なし。
継承可能性
不可。

例1: Hashテーブル

ShortText型のキーを持つHashテーブルで、カラムは無いもの:

{
  "type": "Hash",
  "keyType": "ShortText",
  "columns": {
  }
}
例2: PatriciaTrieテーブル

TokenBigramトークナイザとNormalizerAutoノーマライザを利用するPatriciaTrieテーブル

{
  "type": "PatriciaTrie",
  "keyType": "ShortText",
  "tokenizer": "TokenBigram",
  "normalizer": "NormalizerAuto",
  "columns": {
  }
}

Column 定義

An object with the following key/value pairs.

パラメータ

type
Abstract
Specifies the quantity of data stored as each column value.
Value
Any of the followings.
Default value
"Scalar"
継承可能性
不可。
valueType
Abstract
Data type of the column value.
Value
Any of the following data types or the name of another table defined in the same dataset. When a table name is assigned, the column acts as a foreign key references the table.
既定値
なし。これは必須のパラメータです。
継承可能性
不可。
vectorOptions
概要
データベースインスタンスの場所を指定します。
Value
An object which is a vectorOptions definition
Default value
{} (Void object).
継承可能性
不可。
indexOptions
概要
データベースインスタンスの場所を指定します。
Value
An object which is an indexOptions definition
Default value
{} (Void object).
継承可能性
不可。

例1: スカラー型カラム

ShortTextを格納するスカラー型のカラム:

{
  "type": "Scalar",
  "valueType": "ShortText"
}
例2: ベクター型カラム

A vector column to store ShortText values with weight:

{
  "type": "Scalar",
  "valueType": "ShortText",
  "vectorOptions": {
    "weight": true
  }
}
例3: インデックスカラム

Storeテーブルのaddressカラムをインデックスするカラム:

{
  "type": "Index",
  "valueType": "Store",
  "indexOptions": {
    "sources": [
      "address"
    ]
  }
}

vectorOptions 定義

以下のキーと値のペアを持つオブジェクト。

パラメータ

weight
Abstract
Specifies whether the vector column stores the weight data or not. Weight data is used for indicating the importance of the value.
Value
A boolean value (true or false).
Default value
false.
継承可能性
不可。

Store the weight data.

{
  "weight": true
}

indexOptions 定義

以下のキーと値のペアを持つオブジェクト。

パラメータ

section
Abstract
Specifies whether the index column stores the section data or not. Section data is typically used for distinguishing in which part of the sources the value appears.
Value
A boolean value (true or false).
Default value
false.
継承可能性
不可。
weight
Abstract
Specifies whether the index column stores the weight data or not. Weight data is used for indicating the importance of the value in the sources.
Value
A boolean value (true or false).
Default value
false.
継承可能性
不可。
position
Abstract
Specifies whether the index column stores the position data or not. Position data is used for specifying the position where the value appears in the sources. It is indispensable for fast and accurate phrase-search.
Value
A boolean value (true or false).
Default value
false.
継承可能性
不可。
sources
Abstract
Makes the column an inverted index of the referencing table’s columns.
Value
An array of column names of the referencing table assigned as valueType.
既定値
なし。
継承可能性
不可。

Store the section data, the weight data and the position data. Index name and address on the referencing table.

{
  "section": true,
  "weight": true,
  "position": true
  "sources": [
    "name",
    "address"
  ]
}

Volume 定義

概要
データセットを構成する単位。データセットは1つ、もしくは複数のボリュームからなります。ボリュームは単一のデータベースインスタンスか、slices の集合で構成されます。ボリュームが単一のデータベースインスタンスから構成される場合は、addressパラメータを指定しなければなりません。このとき、それ以外のパラメータを指定してはいけません。そうでない場合は、dimensionslicerslicesが必須で、他は指定してはいけません。
以下のキーと値のペアを持つオブジェクト。

パラメータ

address
概要
データベースインスタンスの場所を指定します。
以下の書式の文字列。
${host_name}:${port_number}/${tag}.${name}
  • host_name: データベースのインスタンスを保持するホストの名前。
  • port_number: データベースのインスタンスのためのポート番号。
  • tag: データベースのインスタンスのタグ名。タグ名には.を含めることはできません。ホスト名とポート番号のペアごとに、複数のタグを使うことができます。
  • name: データベースのインスタンスの名前。あるホスト名・ポート番号・タグ名の3つの組み合わせごとに、複数のインスタンス名を使うことができます。
既定値
なし。
継承可能性
不可。
dimension
概要
fact表の中でレコードをスライスする次元を指定します。fact表の’_key’またはcolumnsからスカラー型のカラムを選択します。dimensionを参照してください。
文字列。
既定値
"_key"
継承可能性
可。datasetvolumeの定義でオーバライドできます。
slicer
概要
dimensionカラムをsliceする関数。
スライサー関数の名前。
既定値
"hash"
継承可能性
可。datasetvolumeの定義でオーバライドできます。

slicesの集合からなるボリュームを定義するためには、レコードを複数のスライスに振り分けるための方法を決める必要があります。

sliceで指定されたスライサー関数と、スライサー関数への入力として与えられるdimensionで指定されたカラム(またはキー)によって、それが決まります。

スライサーは以下の3種類に分けられます:

比例尺度
比例尺度スライサーは、個々のデータを指定された比率で、_keyのハッシュ値などに基づいて振り分けます。 この種類のスライサー:
  • hash
順序尺度
順序尺度スライサーは、個々のデータを順序のある値(時間、整数、{High, Middle, Low}など)に基づいて振り分けます。 この種類のスライサー:
  • (未実装)
名義尺度
名義尺度スライサーは、個々のデータをカテゴリを示す名義(国名、郵便番号、色など)で振り分けます。 この種類のスライサー:
  • (未実装)
slices
概要
データを格納するスライスの定義。
slice 定義の配列。
既定値
なし。
継承可能性
不可。

例1: 単一のインスタンス

“localhost:24224/volume.000”にあるボリューム:

{
  "address": "localhost:24224/volume.000"
}
Example 2: 複数のスライス

3つのスライスから構成され、_keyに対してratio-scaledなスライサー関数hashを適用してレコードを分散させるボリューム

{
  "dimension": "_key",
  "slicer": "hash",
  "slices": [
    {
      "volume": {
        "address": "localhost:24224/volume.000"
      }
    },
    {
      "volume": {
        "address": "localhost:24224/volume.001"
      }
    },
    {
      "volume": {
        "address": "localhost:24224/volume.002"
      }
    }
  ]

Slice 定義

概要
スライスの定義。スライスされたデータの範囲と、それを保存するボリュームを指定する。
以下のキーと値のペアを持つオブジェクト。

パラメータ

weight
概要
スライス内での割り当て量を指定します。slicerが atio-scaledの場合のみ有効。
数値。
既定値
1
継承可能性
不可。
label
概要
slicer が返す具体的な値。 slicerがnominal-scaledの場合のみ有効。
Value
A value of the dimension column data type. When the value is not provided, this slice is regarded as else; matched only if all other labels are not matched. Therefore, only one slice without label is allowed in slices.
既定値
なし。
継承可能性
不可。
boundary
概要
slicerの返す値と比較可能な具体的な値。slicerがordinal-scaledの場合のみ有効。
Value
A value of the dimension column data type. When the value is not provided, this slice is regarded as else; this means the slice is open-ended. Therefore, only one slice without boundary is allowed in a slices.
既定値
なし。
継承可能性
不可。
volume
概要
スライスに対応するデータを格納するボリューム。

volume 定義オブジェクト

既定値
なし。
継承可能性
不可。

例1: Ratio-scaled

ratio-scaledなスライサーのためのスライス、重みは1

{
  "weight": 1,
  "volume": {
  }
}
例2: Nominal-scaled

nominal-scaledなスライサーのためのスライス、ラベルは "1"

{
  "label": "1",
  "volume": {
  }
}
例3: Ordinal-scaled

ordinal-scaledなスライサーに対するスライス、境界値は100:

{
  "boundary": 100,
  "volume": {
  }
}

実際の例

基本的な使い方のチュートリアルに登場するカタログを参照してください。