データ ソース内で 1 つ以上のレコードを変更または作成するか、データ ソースの外部でレコードをマージします。

概要

Patch 関数を使用して、データ ソースの 1 つ以上のレコードを変更します。 特定のプロパティの値が、その他のプロパティに影響を与えることなく変更されます。

Patch は、レコードを作成するために Defaults 関数と併せて使用します。 この動作は、レコードの作成と編集に使用する単一の画面を構築するのに使用できます。

データ ソースを使用していない場合でも、Patch を使用して 2 つ以上のレコードをマージすることができます。

説明

データ ソースのレコードを変更または作成する

データ ソースに対してこの関数を使用するには、データ ソースを指定し、基本レコードを指定します。

  • レコードを変更する場合、基本レコードはデータ ソースからのものである必要があります。 基本レコードは、ギャラリーの Items プロパティから取得されてコンテキスト変数内に配置されることも、他のパスを通じて取得されることもあります。 しかし、基本レコードは、データ ソースまで追跡可能である必要があります。 レコードには、変更する際にそのレコードを再度特定するのに役立つ情報を追加するため、これは重要です。

  • レコードを作成する際は、Defaults 関数を使用して既定値で基本レコードを作成します。

次に、1 つ以上の変更レコードを指定します。各レコードには、基本レコード内のプロパティ値を上書きする新しいプロパティ値が含まれます。 変更レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。

Patch の戻り値は、変更または作成したレコードです。 レコードを作成した場合、戻り値にはデータ ソースによって自動的に生成されたプロパティが含まれる場合があります。

データ ソースを更新するとき、1 つまたは複数の問題が発生する場合があります。 データ ソースの利用に関する記事で説明されているとおり、問題の特定と調査には Errors 関数を使用します。

関連する関数として、レコード全体の置き換えに使用できる Update 関数や、レコードの作成に使用できる Collect 関数などがあります。 UpdateIf 関数を使用すると、条件に基づいて複数のレコードの特定のプロパティを変更できます。

データ ソースのレコード セットを変更または作成する

Patch は、1 回の呼び出しで複数のレコードを作成または変更するときにも使用できます。

基本レコードを 1 つ渡す代わりに、2 番目の引数で基本レコードのテーブルを渡せます。 変更レコードもテーブルで渡され、基本レコードに一対一で対応します。 各変更テーブル内のレコードの数は、基本テーブル内のレコードの数と同じである必要があります。

この方法で Patch を使用した場合、戻り値もテーブルになり、その各レコードは基本レコードと変更レコードに一対一で対応します。

データ ソースの外部でレコードをマージする

マージする 2 つ以上のレコードを指定します。 レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。

Patch はマージされたレコードを返します。引数またはデータ ソース内のレコードは変更されません。

構文

データ ソースのレコードを変更または作成する

Patch( DataSource, BaseRecord, ChangeRecord1 [, ChangeRecord2, … ])

  • DataSource – 必須。 変更するレコードを含むデータ ソースまたはこれから作成するレコードを含むデータ ソース。

  • BaseRecord – 必須。 変更または作成するレコード。 レコードがデータ ソースからのものだった場合、レコードが検出され、変更されます。 Defaults の結果を使用した場合は、レコードが作成されます。

  • ChangeRecord(s) – 必須。 BaseRecord 内で変更するプロパティを含む、1 つまたは複数のレコード。 変更レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。

データ ソースのレコード セットを変更または作成する

Patch( DataSource, BaseRecordsTable, ChageRecordTable1, [, ChangeRecordTable2, … ] )

  • DataSource – 必須。 変更するレコードを含むデータ ソースまたはこれから作成するレコードを含むデータ ソース。

  • BaseRecordTable – 必須。 変更または作成するレコードのテーブル。 レコードがデータ ソースからのものだった場合、レコードが検出され、変更されます。 Defaults の結果を使用した場合は、レコードが作成されます。

  • ChangeRecordTable(s) – 必須。 BaseRecordTable の各レコードで変更するプロパティを含む、1 つまたは複数のレコード テーブル。 変更レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。

レコードをマージする

Patch( Record1, Record2 [, …] )

  • Record(s) - 必須。 少なくとも 2 つ以上の、マージするレコード。 レコードは、引数リストの先頭から末尾まで順に処理されます。その際、前のプロパティ値は後のプロパティ値によって上書きされます。

(データ ソースの) レコードを変更または作成する

これらの例では、IceCream というデータ ソースのレコードを変更または作成します。このデータ ソースは次のテーブルのデータを含み、ID 内の値を自動的に生成します。

数式 説明 結果
Patch( IceCream,
First( Filter( IceCream, Flavor = "Chocolate" ) ), { Quantity: 400 } )
IceCream データ ソース内のレコードを変更します。
  • 変更するレコードの ID 列には値 1 が含まれます (Chocolate レコードの ID がこれです)。
  • Quantity 列の値が 400 に変更されます。
{ ID: 1, Flavor: "Chocolate", Quantity: 400 }

IceCream データ ソースの Chocolate エントリが変更されています。
Patch( IceCream, Defaults( IceCream ), { Flavor: "Strawberry" } ) IceCream データ ソース内のレコードを作成します。
  • ID 列には値 3 が含まれます。これはデータ ソースが自動的に生成するものです。
  • Quantity 列には 0 が含まれます。これは Defaults 関数で指定するとおり、IceCream データ ソースにおけるこの列の既定値です。
  • Flavor 列には Strawberry という値が含まれます。
{ ID: 3, Flavor: "Strawberry", Quantity: 0 }

IceCream データ ソースの Strawberry エントリが作成されています。

前の数式が評価された後、データ ソースはこれらの値で終了します。

(データ ソースの外部で) レコードをマージする

数式 説明 結果
Patch( { Name: "James", Score: 90 }, { Name: "Jim", Passed: true } ) データ ソースの外部で 2 つのレコードをマージします。
  • 各レコードの Name 列の値は一致しません。 結果には、引数リストの先頭に近いレコードの値 (James) ではなく、末尾に近いレコードの値 (Jim) が含まれます。
  • 最初のレコードには、2 番目のレコードには存在しない列 (Score) が含まれます。 結果には、その列とその値 (90) が含まれます。
  • 2 番目のレコードには、最初のレコードには存在しない列 (Passed) が含まれます。 結果には、その列とその値 (true) が含まれます。
{ Name: "Jim", Score: 90, Passed: true }