注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
このセクションでは、インクリメンタル(差分処理)に計算できるトランスフォームのさまざまな例を紹介します。
これらの例では、students と students_updated の2つの入力を使ってインクリメンタル計算を説明します。students 入力には3人の学生が含まれ、インクリメンタルではありません。つまり、履歴がありません。
>>> students.dataframe('previous').sort('id').show()
+---+----+---+---+
| id|hair|eye|sex|
+---+----+---+---+
+---+----+---+---+
>>>
>>> students.dataframe('current').sort('id').show()
+---+-----+-----+------+
| id| hair| eye| sex|
+---+-----+-----+------+
| 1|Brown|Green|Female|
| 2| Red| Blue| Male|
| 3|Blond|Hazel|Female|
+---+-----+-----+------+
>>>
>>> students.dataframe('added').sort('id').show()
+---+-----+-----+------+
| id| hair| eye| sex|
+---+-----+-----+------+
| 1|Brown|Green|Female|
| 2| Red| Blue| Male|
| 3|Blond|Hazel|Female|
+---+-----+-----+------+
>>>
>>> # Recall that the default read mode for inputs is 'added'
>>> students.dataframe('added') is students.dataframe()
True
students_updated 入力は students と同じですが、さらに3人の学生を含む更新が追加されています。この更新により、入力はインクリメンタルになります。そのため、空でない previous DataFrame を持ちます。
>>> students_updated.dataframe('previous').sort('id').show()
+---+-----+-----+------+
| id| hair| eye| sex|
+---+-----+-----+------+
| 1|Brown|Green|Female|
| 2| Red| Blue| Male|
| 3|Blond|Hazel|Female|
+---+-----+-----+------+
>>>
>>> students_updated.dataframe('current').sort('id').show()
+---+-----+-----+------+
| id| hair| eye| sex|
+---+-----+-----+------+
| 1|Brown|Green|Female|
| 2| Red| Blue| Male|
| 3|Blond|Hazel|Female|
| 4|Brown|Green|Female|
| 5|Brown| Blue| Male|
| 6|Blond|Hazel|Female|
+---+-----+-----+------+
>>>
>>> students_updated.dataframe('added').sort('id').show()
+---+-----+-----+------+
| id| hair| eye| sex|
+---+-----+-----+------+
| 4|Brown|Green|Female|
| 5|Brown| Blue| Male|
| 6|Blond|Hazel|Female|
+---+-----+-----+------+
>>>
>>> # Recall that the default read mode for inputs is 'added'
>>> students_updated.dataframe('added') is students_updated.dataframe()
True
追加専用のインクリメンタル計算とは、追加される出力行が、追加された入力行だけによって決まる計算です。つまり、出力を計算するために、トランスフォームは次の処理を行います。
列のデータ型の変更、日付の文字列への書式設定、絞り込みは、いずれも追加専用の計算の例です。これらの例では、追加された各入力行を変換または削除して、出力行を生成します。
追加専用のトランスフォームをインクリメンタルにするために必要な違いは、incremental() デコレーターだけであることに注目してください。
インクリメンタルに実行する場合、デフォルトの読み取りモードである added では、トランスフォームは新しい学生だけを読み取ります。また、デフォルトの書き込みモードである modify では、絞り込み後の新しい学生だけを出力に追加します。
非インクリメンタルに実行する場合、デフォルトの読み取りモードである added では、トランスフォームは入力全体を読み取ります。また、デフォルトの書き込みモードである replace では、絞り込み後の学生全体で出力を置き換えます。
Copied!1 2 3 4 5 6 7 8 9 10 11 12 13import polars as pl from transforms.api import transform, incremental, Input, Output @incremental() @transform.using( students=Input('/examples/students_hair_eye_color'), processed=Output('/examples/hair_eye_color_processed') ) def incremental_filter(students, processed): new_students_df = students.polars() processed.write_table( new_students_df.filter(pl.col('hair') == 'Brown') )
Copied!1 2 3 4 5 6 7 8 9 10 11 12from transforms.api import transform, incremental, Input, Output @incremental() @transform.using( students=Input('/examples/students_hair_eye_color'), processed=Output('/examples/hair_eye_color_processed') ) def incremental_filter(students, processed): new_students_df = students.pandas() processed.write_table( new_students_df[new_students_df['hair'] == 'Brown'] )
Copied!1 2 3 4 5 6 7 8 9 10 11 12from transforms.api import transform, incremental, Input, Output @incremental() @transform( students=Input('/examples/students_hair_eye_color'), processed=Output('/examples/hair_eye_color_processed') ) def incremental_filter(students, processed): new_students_df = students.dataframe() processed.write_dataframe( new_students_df.filter(new_students_df.hair == 'Brown') )
更新をインクリメンタルに計算するために、トランスフォームが以前の出力を参照する必要がある場合があります。その例が distinct() ↗ メソッドです。
トランスフォームで重複行を削除するには(現在の出力が正しいと仮定すると)、まず入力の新しい行から重複を削除し、次に、それらの行が出力にまだ存在していないことを確認する必要があります。
Copied!1 2 3 4 5 6 7 8 9 10 11 12@incremental() @transform( students=Input('/examples/students_hair_eye_color'), processed=Output('/examples/hair_eye_color_processed') ) def incremental_distinct(students, processed): new_students_df = students.dataframe() processed.write_dataframe( new_students_df.distinct().subtract( processed.dataframe('previous', schema=new_students_df.schema) ) )
ここでは、出力データセットに対して previous 読み取りモードを使用します。これにより、前回のビルドで出力された DataFrame ↗ が返されます。previous 出力が存在しない可能性があるため、空の DataFrame を正しく構築できるように、dataframe('previous') 呼び出しにスキーマを指定する必要があります。
常に出力全体を置き換える変換もあります。しかし、このようなトランスフォームでも、インクリメンタル計算のメリットを得られることがよくあります。その一例が統計の集計です。たとえば、列内の一意の値ごとに出現回数を数える処理が該当します。
Copied!1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23from pyspark.sql import functions as F @incremental() @transform( students=Input('/examples/students_hair_eye_color'), processed=Output('/examples/hair_eye_color_processed') ) def incremental_group_by(students, processed): # 新しい学生のみを対象に、髪の色ごとの件数を計算します。 new_hair_counts_df = students.dataframe().groupBy('hair').count() # 以前の件数と縦結合します out_schema = new_hair_counts_df.schema all_counts_df = new_hair_counts_df.union( processed.dataframe('previous', schema=out_schema) ) # 髪の色でグループ化し、2つの件数を合計します。 totals_df = all_counts_df.groupBy('hair').agg(F.sum('count').alias('count')) # 出力全体を置き換えるため、出力モードは常に 'replace' に設定します。 processed.set_mode('replace') processed.write_dataframe(totals_df.select(out_schema.fieldNames()))
ここでも、previous 出力が存在しない可能性があるため、空の DataFrame を正しく構築できるように、dataframe('previous') 呼び出しにスキーマを指定する必要があります。
インクリメンタルトランスフォームで、スキーマのない入力データセットに追加されたファイルから Spark DataFrame を作成し、その DataFrame の内容を出力に追加する必要がある場合があります。このようなトランスフォームには、2つの実装パターンがあります。
想定するスキーマを静的に指定し、生成される DataFrame がそのスキーマに従うようにします(入力データの余分なフィールドを無視する、入力データにないフィールドを null で埋める、など)。
入力データに存在するフィールドを動的に取り込みます。
動的に取り込む実装パターンでは、出力に追加する DataFrame のスキーマが、既存の出力と_互換性がある_ことを確認する必要があります。スキーマが既存の出力と互換性を持つには、次の条件を満たす必要があります。
新しいデータの列のうち、既存の出力の列と同じ名前を持つ列は、データ型も同じである必要があります。
既存の出力のすべての列が、新しいデータにも存在する必要があります。
新しいデータに、既存のデータの列と大文字と小文字の違いしかない名前の列があってはなりません。たとえば、既存のデータにすでに value 列がある場合、新しいデータに Value 列を含めることはできません。
これらの条件が満たされるようにするには、既存のデータのスキーマを動的に調べる必要があります。つまり、スキーマを指定せずに dataframe('previous') を呼び出す必要があります。これは、トランスフォームがインクリメンタルに実行されている場合に限りサポートされます。
以下のコードは、これらすべての原則を組み合わせたものです。
Copied!1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59from functools import reduce from pyspark.sql import functions as F from transforms.api import transform, incremental, Input, Output from transforms.verbs.dataframes import sanitize_schema_for_parquet @incremental() @transform( csvs=Input('/examples/dataset_of_csvs'), parsed=Output('/examples/parsed_csvs') ) def incremental_read_csv(ctx, csvs, parsed): input_fs = csvs.filesystem() def process_file(f): df = ( ctx.spark_session.read # すべての列が文字列になるように inferSchema を False に設定します # これにより、同じインクリメンタルビルド内でも、異なるビルド間でも、 # ファイル間で推論結果が一致しないことによる問題を防ぎます。 .option("inferSchema", False) .option("header", True) .csv(input_fs.hadoop_path + "/" + f) ) sanitized = sanitize_schema_for_parquet(df) # 同じインクリメンタルビルド内でも、異なるビルド間でも、ファイル間で大文字と小文字の使い方が # 一致しないことによる問題を防ぐため、すべての列名を小文字にします。 # このロジックでは、1つのファイル内に大文字と小文字だけが異なる列が # 含まれる場合には対応できないことに注意してください。 return sanitized.select(*(F.col(a).alias(a.lower()) for a in sanitized.columns)) dfs = [process_file(f.path) for f in input_fs.ls()] if len(dfs) == 0: parsed.abort() return df = reduce( lambda a, b: a.unionByName(b, allowMissingColumns=True), dfs[1:], dfs[0], ) if not ctx.is_incremental: parsed.write_dataframe(df) else: existing_columns = parsed.dataframe("previous").columns columns_in_new_data = set(df.columns) resolved_schema_df = df.select( *df.columns, *( F.lit(None).cast("string").alias(col) for col in existing_columns if col not in columns_in_new_data ) ) parsed.write_dataframe(resolved_schema_df)
顧客が送信した Orders と、配送が完了した Deliveries という2個のテーブルがあり、品物の配送にかかる時間を格納したテーブル DeliveryDuration を計算するとします。Orders と Deliveries の両テーブルには新しい行が追加されるだけで、既存の行が変更されることはありませんが、この2つのインクリメンタルデータセットを単純に結合するだけでは機能しません。たとえば、Orders テーブルには、Deliveries テーブルにまだ存在しない orderIds が含まれている可能性があります。
Orders: Deliveries:
+---------+---------------+ +---------+--------------+ +---------+------------------+
| orderId | submittedDate | | orderId | deliveryDate | | orderId | deliveryDuration |
+---------+---------------+ +---------+--------------+ ----> +---------+------------------+
| 1001 | 2019-08-21 | join on | 1001 | 2019-08-23 | | 1001 | 2 |
+---------+---------------+ orderId +---------+--------------+ +---------+------------------+
| 1002 | 2019-08-22 |
+---------+---------------+
| 1003 | 2019-08-23 |
+---------+---------------+
Orders と Deliveries の両テーブルで orderId が狭義単調増加すると仮定すると、deliveryDuration を計算済みの最後の orderId(maxComputedOrderId)を確認し、Orders と Deliveries の両テーブルから、orderId が maxComputedOrderId より大きい行だけを取得できます。
Copied!1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41from transforms.api import transform, Input, Output, incremental from pyspark.sql import types as T from pyspark.sql import functions as F @incremental(snapshot_inputs=['orders', 'deliveries']) @transform( orders=Input('/example/Orders'), deliveries=Input('/example/Deliveries'), delivery_duration=Output('/example/New_Delivery_Date') ) def compute_delivery_duration(orders, deliveries, delivery_duration): def to_fields(datatype, names, nullable=True): return [T.StructField(n, datatype, nullable) for n in names] # deliveryDuration 用に渡すスキーマを生成します fields = to_fields(T.IntegerType(), ['orderId', 'deliveryDuration']) # 以前のバージョンのスキーマを参照できないため、スキーマを明示的に定義します maxComputedOrderId = ( delivery_duration .dataframe('previous', schema=T.StructType(fields)) .groupby() .max('orderId') .collect()[0][0] ) # 初回の反復では、delivery_duration データセットがまだ存在しないため、maxComputedOrderId は空です if maxComputedOrderId == None: maxComputedOrderId = 0 ordersNotProcessed = orders.dataframe().filter(F.col('orderId') > maxComputedOrderId) deliveriesNotProcessed = deliveries.dataframe().filter(F.col('orderId') > maxComputedOrderId) newDurations = ( ordersNotProcessed .join(deliveriesNotProcessed, 'orderId', how='left') .withColumn('deliveryDuration', F.datediff(F.col('deliveryDate'), F.col('submittedDate'))) .drop(*['submittedDate', 'deliveryDate']) ) delivery_duration.write_dataframe(newDurations)
インクリメンタルデータセットに、今後、新しい列を追加したいとします。出力に列を追加しても is_incremental フラグは無効にならないため、次回の実行では新しい行が計算され、新しい列を含むデータが書き込まれます。以前に書き込まれたすべての行では、この列は null になります。
ただし、以前の行についても、この列に値を設定したい場合があります。トランスフォームの semantic_version を上げると、1回だけ非インクリメンタルに実行されます。読み取りモードに「added」を使用している場合は、入力にすべてのデータが含まれるため、再計算して新しい列を追加できます。
トランスフォームでスナップショット入力から履歴データセットを作成していた場合は、以前のデータが入力上の積み重なった SNAPSHOT トランザクションに含まれているため、少し複雑になります。この場合は、Palantir の担当者にお問い合わせください。
この例では新しい列の追加について説明しましたが、上記の考え方はあらゆる種類のロジック変更に当てはまります。
新しいブランチを作成してそのブランチでビルドを実行すると、ビルドはインクリメンタルに実行されます。新しいブランチでの最初のビルドでは、ブランチの作成元となったブランチで最後にコミットされたトランザクションが、そのまま前回のトランザクションとして扱われます。
次の方法でデータの差分だけを処理する方法を見てきました。
また、次の方法も確認しました。
入力データセットに多数のトランザクションが蓄積されている場合、または SNAPSHOT モードで実行される場合は、トランザクション上限を設定して、各ジョブが読み取るデータを制限します。詳細については、インクリメンタル入力のバッチサイズを制限するを参照してください。
インクリメンタル処理のエラーを理解するには、トランザクションとデータセットビューの概念を読んでおくと理解しやすくなります。また、これらの知識が必要になる場合もあります。
ジョブがインクリメンタルに実行されるとき、そのインクリメンタル入力データセットに含まれるのは未処理のトランザクション範囲のみであり、データセットビュー全体ではありません。
データセットに次のトランザクション履歴があるとします。
SNAPSHOT (1) --> UPDATE (2) --> UPDATE (3) --> UPDATE (4) --> UPDATE (5)
|
Last processed transaction
データセットが最後にビルドされたとき、最新のトランザクションは (3) でした。その後、トランザクション (4) と (5) がコミットされたため、未処理のトランザクション範囲は (4) — (5) です。
データセットのビューは、トランザクション範囲 (1) — (5) です。ビューの「最上位」にある(最新の)トランザクションは、ブランチの HEAD と呼ばれることもあります(これも git になぞらえた呼び方です)。git と同様に、ブランチはトランザクションへのポインターであるため、このブランチはトランザクション (5) を指していると表現します。複数のブランチがそれぞれ異なるトランザクションを指すことができ、ブランチ間でトランザクション履歴を共有する場合もあります。
SNAPSHOT (1) ─> UPDATE (2) ─> UPDATE (3) ─> UPDATE (4) ─> UPDATE (5) [develop]
|
└─> UPDATE [feature-branch]
Catalog:TransactionsNotInViewジョブをインクリメンタルに実行するため、ジョブの開始時に一連のチェックが実行されます。 そのうちの1つでは、未処理のトランザクション範囲が厳密にインクリメンタルであることを確認します(つまり、ファイルの変更が追加のみであることです。インクリメンタル計算の要件を参照してください)。このチェックでは、未処理のトランザクション範囲と処理済みのトランザクション範囲にあるファイルを比較します。
ただし、ブランチの HEAD が移動されている場合、インクリメンタルジョブは不整合な状態になります。2つの範囲を比較する意味がなくなるため、Catalog:TransactionsNotInView エラーがスローされます。
このエラーがどのように発生するかを示した図を以下に示します。
SNAPSHOT (1) ─> UPDATE (2) ─> UPDATE (3) ─> UPDATE (4) ─> UPDATE (5)
| (last processed (branch's previous
| transaction) HEAD, now orphan)
|
└─> UPDATE (6) --> UPDATE (7, branch's current HEAD)
ここでは、処理済みのトランザクション範囲は (1) — (3)、現在のブランチの HEAD は (7) を指しており、現在のビューはトランザクション (1)、(2)、(6)、(7) で構成されています。
これは、処理済みのトランザクションの一部がブランチの HEAD の上流にないため、不整合な状態です。実際、(3) は上流にありません。つまり、最後に処理されたトランザクション (3) が現在のビューに含まれなくなったため、Catalog:TransactionsNotInView がスローされます。
Catalog:InconsistentBranchesOrderスローされる可能性があるもう1つの Catalog エラーは、Catalog:InconsistentBranchesOrder です。これは、最後に処理されたトランザクション(prevTransaction)がブランチの HEAD(endTransaction)より大きい場合に発生します。データセットの HEAD が、前回のトランザクションより前のトランザクションに移動された場合に、このエラーが発生することがあります。
このエラーがどのように発生するかを示した図を以下に示します。
SNAPSHOT (1) --> UPDATE (2) --> UPDATE (3) --> UPDATE (4) --> UPDATE (5)
| |
Current HEAD Last processed transaction
ブランチの HEAD は、次の2つの理由で変更される可能性があります。
SNAPSHOT であるため、不整合な状態を引き起こすことはありません。これを修正するには、次のいずれかを行う必要があります。
parentRef として、updateBranch2 エンドポイントを使用します。このエンドポイントは、経験豊富なユーザーのみが使用してください。