Populate ユーティリティの使用

Populate() の詳細

正式には、Populate() クラス・メソッドのシグニチャは以下のようになります。

classmethod Populate(count As %Integer = 10, 
                     verbose As %Integer = 0, 
                     DeferIndices As %Integer = 1, 
                     ByRef objects As %Integer = 0, 
                     tune As %Integer = 1,
                     deterministic As %Integer = 0) as %Integer

以下はその説明です。

• count は、作成する予定のオブジェクト数です。

• verbose では、進行状況メッセージを現在のデバイスに出力するかどうかを指定します。

• DeferIndices では、データの生成後にインデックスを並べ替える (True) か、データの生成中に並べ替えるかを指定します。

• objects は、生成されたオブジェクトを格納する参照渡しの配列です。

• tune では、データの生成後に $SYSTEM.SQL.TuneTable() を実行するかどうかを指定します。これが 0 の場合、このメソッドは $SYSTEM.SQL.TuneTable() を実行しません。これが 1 (既定) の場合、メソッドは、このテーブルに対して $SYSTEM.SQL.TuneTable() を実行します。これが 1 より大きい値の場合、メソッドは、このテーブルと、このクラスの永続スーパークラスによって投影されたテーブルに、$SYSTEM.SQL.TuneTable() を実行します。

• deterministic は、メソッドを呼び出すたびに同じデータを生成するかどうかを指定します。既定では、メソッドを呼び出すたびに異なるデータが生成されます。

Populate() は、実際にデータを生成したオブジェクトの数を返します。

 Set objs = ##class(MyApp.MyClass).Populate(100)
 // objs is set to the number of objects created.
 // objs will be less than or equal to 100

最小長や最大長などの定義された制約の場合、生成されたデータの一部には検証に合格しないものもあるので、個別のオブジェクトは保存されません。この場合、Populate() は、指定されたオブジェクト数よりも少ない数を作成します。

エラーによりオブジェクトが保存されない場合は、これが 1,000 回連続して (正常な保存なしに) 発生すると、Populate() は終了します。

リテラル・プロパティ

このセクションでは、Populate() メソッドが、以下の形式のプロパティに既定でデータを生成する方法について説明します。

Property PropertyName as Type;
Property PropertyName;

Type は、データ型クラスです。

このようなプロパティの場合、Populate() メソッドは、最初に名前を調べます。以下に示すように、一部のプロパティ名は特別に処理されます。

プロパティの名前が上記のいずれにも当てはまらない場合、Populate() メソッドはプロパティ・タイプを調べて、それに適した値を生成します。例えば、プロパティ・タイプが %StringOpens in a new tab の場合、Populate() メソッドはランダムな文字列を生成します (プロパティの MAXLEN パラメータが考慮されます)。別の例として、プロパティ・タイプが %IntegerOpens in a new tab の場合、Populate() メソッドはランダムな整数を生成します (プロパティの MINVAL および MAXVAL パラメータが考慮されます)。

プロパティにタイプがない場合、InterSystems IRIS は、そのプロパティ・タイプを文字列であると見なします。つまり、Populate() メソッドは、その値にランダムな文字列を生成します。

コレクション・プロパティ

このセクションでは、Populate() メソッドが、以下の形式のプロパティに既定でデータを生成する方法について説明します。

Property PropertyName as List of Classname;
Property PropertyName as Array of Classname;

これに該当するプロパティは、以下のようになります。

• 参照されるクラスがデータ型クラスの場合、Populate() メソッドは値のリストまたは配列を (適宜) 生成します。データの生成には、前述したデータ型クラスのロジックが使用されます。

• 参照されるクラスがシリアル・オブジェクトの場合、Populate() メソッドはシリアル・オブジェクトのリストまたは配列を (適宜) 生成します。データの生成には、前述したシリアル・オブジェクトのロジックが使用されます。

• 参照されるクラスが永続クラスの場合、Populate() メソッドは、参照されるクラスに含まれるエクステントのランダム・サンプルを実行し、そのサンプルからランダムに値を選択します。その値を使用してリストまたは配列を (適宜) 生成します。

シリアル・オブジェクトを参照するプロパティ

このセクションでは、Populate() メソッドが、以下の形式のプロパティに既定でデータを生成する方法について説明します。

Property PropertyName as SerialObject;

SerialObject は、%SerialObjectOpens in a new tab を継承するクラスです。

これに該当するプロパティは、以下のようになります。

• 参照されるクラスが %PopulateOpens in a new tab を継承している場合、Populate() メソッドはクラスのインスタンスを作成し、前述のセクションで説明したようにプロパティ値を生成します。

• 参照されるクラスが %PopulateOpens in a new tab を継承していない場合、Populate() メソッドは、そのプロパティの値を生成しません。

永続オブジェクトを参照するプロパティ

このセクションでは、Populate() メソッドが、以下の形式のプロパティに既定でデータを生成する方法について説明します。

Property PropertyName as PersistentObject;

PersistentObject は、%PersistentOpens in a new tab を継承するクラスです。

これに該当するプロパティは、以下のようになります。

• 参照されるクラスが %PopulateOpens in a new tab を継承している場合、Populate() メソッドは参照されるクラスに含まれるエクステントのランダム・サンプルを実行し、そのサンプルからランダムに 1 つの値を選択します。

  そのため、参照されるクラスのデータを最初に生成しておく必要があります。または、他の何らかの方法でクラスのデータを作成します。

• 参照されるクラスが %PopulateOpens in a new tab を継承していない場合、Populate() メソッドは、そのプロパティの値を生成しません。

リレーションシップの詳細は、次のセクションを参照してください。

リレーションシップ・プロパティ

このセクションでは、Populate() メソッドが、以下の形式のプロパティに既定でデータを生成する方法について説明します。

Relationship PropertyName as PersistentObject;

PersistentObject は、%PersistentOpens in a new tab を継承するクラスです。

これに該当するプロパティは、以下のようになります。

• 参照されるクラスが %PopulateOpens in a new tab を継承している場合 ：

  • リレーションシップのカーディナリティが one または parent の場合、Populate() メソッドは参照されるクラスに含まれるエクステントのランダム・サンプルを実行し、そのサンプルからランダムに 1 つの値を選択します。

    そのため、参照されるクラスのデータを最初に生成しておく必要があります。または、他の何らかの方法でクラスのデータを作成します。

  • リレーションシップのカーディナリティが many または children の場合、Populate() メソッドは、このプロパティを無視します。これは、このプロパティの値が、このクラスのエクステントには保存されないためです。

• 参照されるクラスが %PopulateOpens in a new tab を継承していない場合、Populate() メソッドは、そのプロパティの値を生成しません。

非コレクション・プロパティの POPSPEC パラメータを指定する方法

コレクション以外のリテラル・プロパティには、以下のいずれかのバリエーションを使用します。

• POPSPEC="MethodName()" — この場合、Populate() は %PopulateUtilsOpens in a new tab クラスのクラス・メソッド MethodName() を呼び出します。

• POPSPEC=".MethodName()" — この場合、Populate() は生成されるインスタンスのインスタンス・メソッド MethodName() を呼び出します。

• POPSPEC="##class(ClassName).MethodName()" — この場合、Populate() は ClassName クラスのクラス・メソッド MethodName() を呼び出します。

例 ：

Property HomeCity As %String(POPSPEC = "City()");

指定のメソッドに引数として文字列値を渡す必要がある場合は、その文字列を囲む先頭の引用符と末尾の引用符を 2 つ続けます。以下に例を示します。

Property PName As %String(POPSPEC = "Name(""F"")");

また、指定したメソッドが返す値に文字列を追加することもできます。以下に例を示します。

Property JrName As %String(POPSPEC = "Name()_"" jr."" ");

その文字列を囲む先頭の引用符と末尾の引用符は 2 つ続ける必要がある点に注意してください。先頭に文字列を追加することはできません。POPSPEC は、メソッドが先頭になることを想定しているためです。

別の方法については、“SQL テーブル経由で POPSPEC パラメータを指定する方法” も参照してください。

リスト・プロパティの POPSPEC パラメータを指定する方法

プロパティがリテラルまたはオブジェクトのリストである場合は、以下のバリエーションを使用できます。

POPSPEC="basicspec:MaxNo"

以下はその説明です。

• basicspec は、前のセクションに示した基本バリエーションの 1 つです。プロパティがオブジェクトのリストの場合は、basicspec を空のままにしておきます。

• MaxNo は、リストに含まれる項目の最大数です。既定値は 10 です。

例 ：

Property MyListProp As list Of %String(POPSPEC = ".MyInstanceMethod():15");

basicspec は省略できます。以下に例を示します。

Property Names As list of Name(POPSPEC=":3");

以下の例では、複数のデータ型のリストがあります。Colors は文字列のリスト、Kids は永続オブジェクトへの参照リスト、Addresses は埋め込みオブジェクトのリストです。

Property Colors As list of %String(POPSPEC="ValueList("",Red,Green,Blue"")");

Property Kids As list of Person(POPSPEC=":5");

Property Addresses As list of Address(POPSPEC=":3");

Colors プロパティのデータを生成するには、Populate() メソッドで、PopulateUtils クラスの ValueList() メソッドを呼び出します。この例では、引数として、このメソッドにコンマ区切りリストを渡している点に注意してください。Kids では、自動的に参照を生成する指定されたメソッドはありません。Addresses プロパティでは、シリアル Address クラスが %PopulateOpens in a new tab から継承され、データがそのクラスのインスタンスに自動的に入力されます。

配列プロパティの POPSPEC パラメータを指定する方法

リテラルまたはオブジェクトの配列であるプロパティには、以下のバリエーションを使用できます。

POPSPEC="basicspec:MaxNo:KeySpecMethod"

以下はその説明です。

• basicspec は、前出の基本バリエーションの 1 つです。プロパティがオブジェクトの配列の場合は、basicspec を空のままにしておきます。

• MaxNo は、配列内の項目の最大数です。既定値は 10 です。

• KeySpecMethod は、配列のキーに使用する値を生成するメソッドの仕様です。既定は、String() です。これは、InterSystems IRIS が %PopulateUtilsOpens in a new tab の String() メソッドを呼び出すことを意味します。

以下の例では、数種類のデータのタイプと異なる種類のキーの配列を示します。

Property Tix As array of %Integer(POPSPEC="Integer():20:Date()");

Property Reviews As array of Review(POPSPEC=":3:Date()");

Property Actors As array of Actor(POPSPEC=":15:Name()");

Tix プロパティのデータは、PopulateUtils クラスの Integer() メソッドを使用して生成されています。このキーは、PopulateUtils クラスの Date() メソッドを使用して生成されています。Reviews プロパティには、指定されたメソッドがないので、自動的に参照が生成されることになります。またそのキーも、Date() メソッドを使用して生成されます。Actors プロパティには、指定されたメソッドはなく、自動的に参照が生成されます。またそのキーも、PopulateUtils クラスの Name() メソッドを使用して生成されます。

SQL テーブル経由で POPSPEC パラメータを指定する方法

POPSPEC には、ランダムな値を返すメソッドを指定する以外にも、使用する SQL テーブル名と SQL 列名を指定できます。このようにすると、Populate() メソッドは、そのテーブルの列から重複しない列値を返すダイナミック・クエリを作成します。このバリエーションの POPSPEC には、以下の構文を使用します。

POPSPEC=":MaxNo:KeySpecMethod:SampleCount:Schema_Table:ColumnName"

以下はその説明です。

• MaxNo と KeySpecMethod はオプションです。これらは、コレクション・プロパティにのみ適用されます (リストおよび配列についてのサブセクションを参照)。

• SampleCount は、指定の列から取得する非重複値の数です。これを開始点として使用します。この数が、その列に含まれる既存の非重複値の数よりも大きい場合は、すべての値が使用される可能性があります。

• Schema_Table は、テーブルの名前です。

• ColumnName は、列の名前です。

例 ：

Property P1 As %String(POPSPEC=":::100:Wasabi_Data.Outlet:Phone");

この例では、プロパティ P1 は、Wasabi_Data.Outlet テーブルから取得した 100 個の電話番号のリストから、ランダムな値を受け取ります。

データに構造を構築するためのヒント

場合によっては、全体に対して特定の割合にのみ、特定の値を含めることが必要になります。$RANDOM 関数を使用してこれを行うことができます。例えば、この関数を使用して、引数として指定した切り捨てパーセンテージに応じて、True と False をランダムに返すメソッドを定義します。したがって、例えば、10% の場合や 75% の場合に True を返すことができます。

プロパティのデータを生成する場合、このメソッドを使用して、値を割り当てるかどうかを判別します。

 If ..RandomTrue(15) {
    set ..property="something"
 } 

ここに示す例では、レコードの約 15% がこのプロパティに対して指定された値を持つようになります。

この他の場合は、ディストリビューションのシミュレートが必要なこともあります。そのためには、くじ引きシステムをセットアップし、使用します。例えば、値の 1/4 を A に、1/4 を B に、1/2 を C にする必要があるとします。このくじ引きのロジックは、以下のようにすることができます。

1. 1 ～ 100 (両端の値を含む) から 1 つの整数を選択します。

2. その数字が 25 より小さい場合は、値 A を返します。

3. その数字が 25 ～ 49である場合 (両端の値を含む) は、値 B を返します。

4. それ以外の場合は、値 C を返します。