EntitySelection
エンティティセレクションとは、同じ データクラス に所属する一つ以上の エンティティ への参照を格納しているオブジェクトのことです。 エンティティセレクションは、データクラスから 0個、1個、あるいは X個のエンティティを格納することができます (X はデータクラスに格納されているエンティティの総数です)。
.all()
、.query()
などの DataClass
クラス の関数や、.and()
、orderBy()
など EntitySelection
クラス自身の関数を用いて、既存のセレクションからエンティティセレクションを作成することができます 。 また、dataClass.newSelection()
関数または Create entity selection
コマンドを使用して、空のエンティティセレクションを作成することもできます。
概要
Create entity selection
Create entity selection ( dsTable : Table { ; settings : Object } ) : 4D.EntitySelection
引数 | タイプ | 説明 | |
---|---|---|---|
dsTable | Table | -> | エンティティセレクションの元となるカレントセレクションが属する 4Dデータベースのテーブル |
settings | Object | -> | ビルドオプション: context |
戻り値 | 4D.EntitySelection | <- | 指定したテーブルに対応するデータクラスのエンティティセレクション |
説明
Create entity selection
コマンドは、dsTable で指定したテーブルに対応するデータクラスの 追加可能な 新規エンティティセレクションを、同テーブルのカレントセレクションに基づいてビルドして返します。
ソートされたカレントセレクションの場合、順列のある エンティティセレクションが作成されます (カレントセレクションの並び順が受け継がれます)。 カレントセレクションがソートされていない場合、順列のないエンティティセレクションが作成されます。
ds
において dsTable が公開されていない場合には、エラーが返されます。 リモートデータストアの場合は、このコマンドは使用できません。
任意の settings には、以下のプロパティを持つオブジェクトを渡せます:
プロパティ | タイプ | 説明 |
---|---|---|
context | Text | エンティティセレクションに適用されている 最適化コンテキスト のラベル。 |
例題
var $employees : cs.EmployeeSelection
ALL RECORDS([Employee])
$employees:=Create entity selection([Employee])
// $employees エンティティセレクションには、
// Employee データクラスの全エンティティへの参照が格納されています
参照
USE ENTITY SELECTION
USE ENTITY SELECTION (entitySelection)
引数 | タイプ | 説明 | |
---|---|---|---|
entitySelection | EntitySelection | -> | エンティティセレクション |
説明
USE ENTITY SELECTION
コマンドは、entitySelection 引数で指定したデータクラスに合致するテーブルのカレントセレクションを、エンティティセレクションの中身に応じて更新します。
リモートデータストア の場合は、このコマンドは使用できません。
このコマンドは、4Dのカレントセレクションが ORDAクエリの力を活用するためのものです。 パフォーマンス上の理由により、シングルユーザーの 4D と 4D Server では、このコマンドは entitySelection をカレントセレクションと直結します。 そのため、このコマンドに受け渡した entitySelection をその後に再利用したり変更したりすることは避けなければなりません。
USE ENTITY SELECTION
の呼び出し後、更新された (空でない) カレントセレクションの最初のレコードがカレントレコードとなりますが、それはメモリ内にはロードされません。 カレントレコードのフィールド値を使用するには、USE ENTITY SELECTION
コマンドの後に LOAD RECORD
コマンドを使用します。
例題
var $entitySel : cs.EmployeeSelection
$entitySel:=ds.Employee.query("lastName = :1";"M@") // $entitySel は Employee データクラスにリレートされています
REDUCE SELECTION([Employee];0)
USE ENTITY SELECTION($entitySel) // Employee テーブルのカレントセレクションが更新されます
[index]
履歴
リリース | 内容 |
---|---|
17 | 追加 |
[index] : 4D.Entity
説明
EntitySelection[index]
記法を使用すると、標準のコレクションシンタックスを使用してエンティティセレクション内のエンティティにアクセスすることができます。取得したいエンティティの位置を index に渡します。
対応するエンティティはデータストアから再読み込みされる点に注意してください。
index には、0 と .length
-1 の範囲内で数値を指定することができます。
- index が範囲外だった場合、エラーが返されます。
- index がドロップされたエンティティに対応していた場合、Null値が返されます。
EntitySelection[index]
は代入不可の式です。これは、.lock()
や .save()
などの関数において、編集可能なエンティティ参照として使用することはできない、ということを意味します。 エンティティを操作するには、戻り値を変数などの代入可能な式に割り当てる必要があります。 例:
$sel:=ds.Employee.all() // エンティティセレクションを作成
// 無効なコード:
$result:=$sel[0].lock() //動作しません
$sel[0].lastName:="Smith" //動作しません
$result:=$sel[0].save() //動作しません
// 有効なコード:
$entity:=$sel[0] //OK
$entity.lastName:="Smith" //OK
$entity.save() //OK
例題
var $employees : cs.EmployeeSelection
var $employee : cs.EmployeeEntity
$employees:=ds.Employee.query("lastName = :1";"H@")
$employee:=$employees[2] // $employees エンティティセレクションの3番目のエンティティがデータベースからリロードされます。
.attributeName
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.attributeName : Collection
.attributeName : 4D.EntitySelection
説明
データクラス属性はすべてエンティティセレクションのプロパティとして利用可能で、エンティティセレクション内の属性値の "投影" を返します。 戻り値は、属性の種類 (kind が storage
あるいは relation
) によって、コレクションあるいは新しいエンティティセレクションのどちらかになります。
- attributeName で指定した属性がストレージ型の場合:
.attributeName
は attributeName と同じ型の値のコレクションを返します。 - attributeName で指定した属性がリレートエンティティ型の場合:
.attributeName
は attributeName と同じ型のリレート値の新規エンティティセレクションを返します。 重複し ているエンティティは取り除かれます (返されるのは順列なしのエンティティセレクションです)。 - attributeName で指定した属性がリレートエンティティズ型の場合:
.attributeName
は attributeName と同じ型のリレート値の新規エンティティセレクションを返します。 重複しているエンティティは取り除かれます (返されるのは順列なしのエンティティセレクションです)。
エンティティセレクションのプロパティとしてリレーション属性が使用されると、返される結果は、たとえ返されるエンティティが一つだけだとしても、常に新しいエンティティセレクションとなります。 エンティティが何も返ってこない場合には、返されるのは空のエンティティセレクションです。
属性がエンティティセレクション内に存在しない場合、エラーが返されます。
例題 1
ストレージ値の投影:
var $firstNames : Collection
$entitySelection:=ds.Employee.all()
$firstNames:=$entitySelection.firstName // firstName は文字列型です
返されるのは文字列のコレクションとなります。例:
[
"Joanna",
"Alexandra",
"Rick"
]
例題 2
リレートエンティティの投影:
var $es; $entitySelection : cs.EmployeeSelection
$entitySelection:=ds.Employee.all()
$es:=$entitySelection.employer // employer は Companyデータクラスにリレートされています
返されるオブジェクトは、重複してるもの (あれば) を取り除いた、Company のエンティティセレクションで す。
例題 3
リレートエンティティズの投影:
var $es : cs.EmployeeSelection
$es:=ds.Employee.all().directReports // directReports は Employee データクラスにリレートされています
返されるオブジェクトは、重複してるもの (あれば) を取り除いた、Employee のエンティティセレクションです。
.add()
履歴
リリース | 内容 |
---|---|
19 R7 | entitySelection パラメーターをサポート |
18 R5 | 追加可能なエンティティセレクションのみをサポート |
17 | 追加 |
.add( entity : 4D.Entity ) : 4D.EntitySelection
.add( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection
引数 | タイプ | 説明 | |
---|---|---|---|
entity | 4D.Entity | -> | エンティティセレクションに追加するエンティティ |
entitySelection | 4D.EntitySelection | -> | エンティティセレクションに追加するエンティティセレクション |
戻り値 | 4D.EntitySelection | -> | 追加した entity または entitySelection を含むエンティティセレクション |
説明
.add()
関数は、entity または entitySelection で渡したエンティティを対象のエンティティセレクションに追加し、編集されたエンティティセレクションを返します。
このコマンドは、元のエンティティセレクションを変更します。
エンティティセレクションは 追加可能 のものでなければなりません。つまり .newSelection()
あるいは Create entity selection
などで作成されたものでなければならないということです。そうでない場合、.add()
はエラーを返します。 共有可能なエンティティセレクションはエンティティの追加を受け付けないからです。 詳細については 共有可能/追加可能なエンティティセレクション を参照ください。
エンティティの追加
- エンティティセレクションが順列ありの場合、entity 引数のエンティティはセレクションの最後に追加されます。 同じエンティティへの参照がそのエンティティセレクションにすでに所属していた場合、エンティティは重複することになり、同エンティティの新しい参照が追加されます。
- エンティティセレクションが順列なしの場合、entity 引数のエンティティはセレクションの不特定の場所へ追加され、順番付けはされません。
エンティティセレクションの追加
- 元のエンティティセレクションが順列ありの場合、entitySelection 引数のエンティティセレクションはセレクションの最後に追加されます。 entitySelection 内の同じエンティティへの参照が元のエンティティセレクションにすでに所属していた場合、エンティティは重複することになり、同エンティティの新しい参照が追加されます。
- エンティティセレクションが順列なしの場合、順列ありに変更されます。
詳細については、エンティティセレクションの順列あり/順列なし を参照ください。
編集されたエンティティセレクションが関数から返されるため、関数の呼び出しをつなげることができます。
entity 引数のエンティティとエンティティセレクションが同じデータクラスに属していない場合、エラーが発生します。 追加するエンティティが Null であった場合には、エラーは発生しません。
例題 1
var $employees : cs.EmployeeSelection
var $employee : cs.EmployeeEntity
$employees:=ds.Employee.newSelection()
$employee:=ds.Employee.new()
$employee.lastName:="Smith"
$employee.save()
$employees.add($employee) //The $employee entity is added to the $employees entity selection
例題 2
関数の呼び出しをつないでいくことができます:
var $sel : cs.ProductSelection
var $p1;$p2;$p3 : cs.ProductEntity
$p1:=ds.Product.get(10)
$p2:=ds.Product.get(11)
$p3:=ds.Product.get(12)
$sel:=ds.Product.newSelection()
$sel:=$sel.add($p1).add($p2).add($p3)
例題 3
ユーザーインターフェースにおいて、2つのリストがあるとします。 ユーザーは 1つ目のリストのアイテムを複数選択し、それらを 2つ目のリストに追加します。
$sellist2:=$sellist2.add($sellist1)
.and()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.and( entity : 4D.Entity ) : 4D.EntitySelection
.and( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection
引数 | タイプ | 説明 | |
---|---|---|---|
entity | 4D.Entity | -> | 交差するエンティティ |
entitySelection | 4D.EntitySelection | -> | 交差するエンティティセレクション |
戻り値 | 4D.EntitySelection | <- | AND論理演算子による共通部分の結果を格納する新しいエンティティセレクション |
説明
.and()
関数は、エンティティセレクションと entity あるいは entitySelection 引数をAND論理演算子を使用して結合します。戻り値は、エンティティセレクションと引数の両方から参照されているエンティティのみを格納した、順列なしの新規エンティティセレクションです。
- entity 引数を渡した場合、引数のエンティティをエンティティセレクションと結合させることになります。 エンティティがエンティティセレクションに属している場合、そのエンティティのみを格納する新しいエンティティセレクションが返されます。 そうでない場合、空のエンティティセレクションが返されます。
- entitySelection 引数を渡した場合、二つのエンティティセレクションを結合させることになります。 両方のセレクションから参照されているエンティティのみを格納する新しいエンティティセレクションが返されます。 重複するエンティティがなかった場合、空のエンティティセレクションが返されます。
順列ありと順列なしのエンティティセレクション を比較することができます。 返されるセレクションは常に順列なしのものになります。
元のエンティティセレクションあるいは entitySelection 引数が空であった場合、あるいはentity 引数が Null であった場合、空のエンティティセレクションが返されます。
元のエンティティセレクションおよび引数が同じデータクラスのものでない場合、エラーが返されます。
例題 1
var $employees; $result : cs.EmployeeSelection
var $employee : cs.EmployeeEntity
$employees:=ds.Employee.query("lastName = :1";"H@")
// $employees エンティティセレクションには、主キー710のエンティティと
// その他のエンティティが含まれます
// 例: "Colin Hetrick" / "Grady Harness" / "Sherlock Holmes" (主キー710)
$employee:=ds.Employee.get(710) // "Sherlock Holmes" を返します
$result:=$employees.and($employee) // $result は主キー710 ("Sherlock Holmes") の
// エンティティのみを格納するエンティティセレクション。
例題 2
"Jones" という名前で、New York に住んでいる従業員のセレクションを取得します:
var $sel1; $sel2; $sel3 : cs.EmployeeSelection
$sel1:=ds.Employee.query("name =:1";"Jones")
$sel2:=ds.Employee.query("city=:1";"New York")
$sel3:=$sel1.and($sel2)
.at()
履歴
リリース | 内容 |
---|---|
20 | 追加 |
.at( index : Integer ) : 4D.Entity
引数 | タイプ | 説明 | |
---|---|---|---|
index | Integer | -> | 取得するエンティティのインデックス |
戻り値 | 4D.Entity | <- | そのインデックスにあるエンティティ |
説明
.at()
関数は、index の位置にあるエンティティを返します (index は正負の整数)。
index に負の整数 (-1 から -n; n はエンティティセレクションの length) が渡された場合、エンティティセレクションの最後から逆向きに数えます。
index がエンティティセレクションの範囲を超える場合、この関数は Null を返します。
例題
var $employees : cs.EmployeeSelection
var $emp1; $emp2 : cs.EmployeeEntity
$employees:=ds.Employee.query("lastName = :1";"H@")
$emp1:=$employees.at(2) // $employees エンティティセレクションの 3番目のエンティティ
$emp2:=$employees.at(-3) // $employees エンティティセレクションの
// 終わりから 3番目のエンティティ
.average()
履歴
リリース | 内容 |
---|---|
18 R6 | エンティティセレクションが空の場合には undefined を返します |
17 | 追加 |
.average( attributePath : Text ) : Real
引数 | タイプ | 説明 | |
---|---|---|---|
attributePath | Text | -> | 計算に使用する属性パス |
戻り値 | Real | <- | エンティティの属性値の算術平均 (相加平均) (エンティティセレクションがからの場合には undefined を返します) |
説明
.average()
関数は、attributePath に指定した、エンティティセレクション内の null でない値の算術平均 (相加平均) を返します。
attributePath 引数として、評価する属性パスを渡します。
計算の対象となるのは数値のみです。 ただし、エンティティセレクションの attributePath 引数で指定したパスに異なる型の値が混在している場合、.average()
はすべてのスカラー要素を対象として平均値を算出します。
日付値は数値 (秒数) に変換され、平均を計算するのに使用されます。
エンティティセレクションが空の場合、または attributePath 引数に数値型の値が含まれていない場合には、.average()
は undefined を返します。
以下の場合には、エラーが返されます:
- attributePath はリレート属性である
- attributePath がエンティティセレクションデータクラス内に存在しない属性を指定している場合。
例題
給与が平均より高い従業員の一覧を取得します:
var $averageSalary : Real
var $moreThanAv : cs.EmployeeSelection
$averageSalary:=ds.Employee.all().average("salary")
$moreThanAv:=ds.Employee.query("salary > :1";$averageSalary)
.contains()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.contains( entity : 4D.Entity ) : Boolean
引数 | タイプ | 説明 | |
---|---|---|---|
entity | 4D.Entity | -> | 評価するエンティティ |
戻り値 | Boolean | <- | エンティティがエンティティセレクションに属している場合には true、そうでない場合は false |
説明
.contains()
関数は、エンティティ参照がエンティティセレクションに属している場合には true を返します。そうでない場合には false を返します。
entity 引数として、エンティティセレクション内で検索するエンティティを渡します。 エンティティが Null の場合、関数は false を返します。
entity 引数とエンティティセレクションが同じデータクラスのものでない場合、エラーが生成されます。
例題
var $employees : cs.EmployeeSelection
var $employee : cs.EmployeeEntity
$employees:=ds.Employee.query("lastName=:1";"H@")
$employee:=ds.Employee.get(610)
If($employees.contains($employee))
ALERT("主キー610のエンティティのラストネームは H で始まります。")
Else
ALERT("主キー610のエンティティのラストネームは H で始まりません。")
End if
.count()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.count( attributePath : Text ) : Real
引数 | タイプ | 説明 | |
---|---|---|---|
attributePath | Text | -> | 計算に使用する属性パス |
戻り値 | Real | <- | エンティティセレクション内の attributePath が null でない値の個数 |
説明
.count()
関数は、
エンティティセレクション内で attributePath に指定したパスの値が null でないエンティティの数を返します。
対象となるのはスカラー値のみです。 オブジェクトあるいはコレクション型の値は Null値とみなされます。
以 下の場合には、エラーが返されます:
- attributePath はリレート属性である
- attributePath がエンティティセレクションデータクラス内に存在しない場合。
例題
ある会社の全従業員のうち、役職のない者を除いた人数を確認します:
var $sel : cs.EmployeeSelection
var $count : Real
$sel:=ds.Employee.query("employer = :1";"Acme, Inc")
$count:=$sel.count("jobtitle")
.copy()
履歴
リリース | 内容 |
---|---|
18 R5 | 追加 |
.copy( { option : Integer } ) : 4D.EntitySelection
引数 | タイプ | 説明 | |
---|---|---|---|
option | Integer | -> | ck shared : 共有可能なエンティティセレクションを返します |
戻り値 | 4D.EntitySelection | <- | エンティティセレクションのコピー |
説明
.copy()
関数は、元のエンティティセレクションのコピーを返します。
この関数は、元のエンティティセレクションを変更しません。
option パラメーターが省略された場合はデフォルトで、たとえコピー元が共有可能なエンティティセレクションであったとしても、関数はデフォルトで追加可能な (共有不可の) 新規エンティティセレクシ ョンを返します。 共有可能なエンティティセレクションを取得するには、option に ck shared
定数を渡します。
詳細については 共有可能/追加可能なエンティティセレクション を参照ください。
例題
フォームロード時に、商品データを格納するための新規の空エンティティセレクションを作成します:
Case of
:(Form event code=On Load)
Form.products:=ds.Products.newSelection()
End case
このエンティティセレクションに商品を登録したのちに、複数のプロセスでこの商品データを共有するには、 Form.products を共有可能なエンティティセレクションとしてコピーします:
...
// Form.products エンティティセレクションに商品データを登録します
Form.products.add(Form.selectedProduct)
Use(Storage)
If(Storage.products=Null)
Storage.products:=New shared object()
End if
Use(Storage.products)
Storage.products:=Form.products.copy(ck shared)
End use
End use
.distinct()
履歴
リリース | 内容 |
---|---|
20 | dk count values をサポート |
17 | 追加 |
.distinct( attributePath : Text { ; options : Integer } ) : Collection
引数 | タイプ | 説明 | |
---|---|---|---|
attributePath | Text | -> | 重複しない値を取得する属性のパス |
options | Integer | -> | dk diacritical , dk count values |
戻り値 | Collection | <- | 重複しない値のみを格納したコレクション |
説明
.distinct()
関数は、attributePath に指定した、エンティティセレクション内の重複しない (異なる) 値のみを格納したコレクションを返します。
返されたコレクションは自動的に並べ替えられています。 Null 値は返されません。
attributePath 引数として、固有の値を取得したいエンティティ属性を渡します。 スカラー値 (テキスト、数値、ブール、あるいは日付) のみが可能です。 attributePath のパスが異なる型の値を格納しているオブジェクトプロパティであった場合、まず最初に型ごとにグループ分けされ、そのあとで並べ替えされます。 型は以下の順番で返されます:
- ブール
- 文字列
- 数値
- 日付
attributePath がオブジェクト内のパスの場合、[]
を使ってコレクションを指定できます (例題参照)。
options 引数として、以下の定数を 1つ、または組み合わせで渡すことができます:
定数 | 値 | 説明 |
---|---|---|
dk diacritical | 8 | 文字の大小とアクセントを区別して評価をおこないます。 省略された場合のデフォルトでは、アクセント等の発音区別符号を無視した評価が実行されます。 |
dk count values | 32 | 特定の値を持つエンティティの数 (重複がなければ 1、重複があればその数) を返します。 このオプションを渡すと、.distinct() は、{"value":*value*; "count":*count*} のプロパティを含むオブジェクトのコレクションを返します。 |
dk count values
のオプションは、ブール、文字列、数値、日付型のストレージ属性でのみ利用可能です。
以下の場合には、エラーが返されます:
- attributePath はリレート属性である
- attributePath がエンティティセレクションデータクラス内に存在しない場合。