Documentation
ドキュメントの検索
karat

+

K

APIリファレンス ↗
開発者ツールチェーンCode Workspacesデータの操作

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

データを操作する

Jupyter® および RStudio® の Code Workspaces では、Foundry データセット、Iceberg テーブル、仮想テーブルの読み取り、分析、加工、および書き戻しができます。また、制限付きビューおよび時系列プロパティの読み取りと分析もできます。

セキュリティ

Code Workspaces は、データセットに適用された Foundry マーキングと機密情報区分に基づくアクセス制御に従い、ワークスペースは、読み込まれたすべてのデータセットのマーキングと機密情報区分を継承します。これをワークスペースのリネージと呼びます。つまり、ワークスペースにアクセスするには、ワークスペースに含まれるすべてのデータセットおよびその他の入力に対して必要な権限も持っている必要があります。ワークスペースの入力のうち1個でもアクセスできなくなると、ワークスペース全体にアクセスできなくなります。

Code Workspace に読み込まれた制限付きビューには、出力制限モードが適用されます。このモードは制限付きビューのインポートに必須であり、それらのビューから派生した出力の公開を防ぎます。出力制限モードは、ワークスペース内の制限付きビューに対して Granular Policy を適用します。ユーザーが読み取れるデータを絞り込み、ポリシーによって本来制限されるデータを公開しかねない出力がワークスペースから生成されることを防ぎます。伝播モデルの詳細については、アクセス制御の伝播を参照してください。

リソースに関する考慮事項

Jupyter® および RStudio® のワークスペースは、対話型の分析ワークフローとアプリケーション開発向けに設計されています。単一の仮想マシンで実行され、分散 Spark 環境でデータセットを処理することはありません。そのため、扱うデータはマシンのリソース内に収まる必要があります。リソースのデフォルトは、最大8 CPU、64 GB のメモリーです。大規模なデータセットを読み込む前に、フィルターや SQL を使用して必要なデータ量を減らすと、これらの上限を超えないようにできます。データセットのファイルを絞り込むことも、ワークスペースの上限内に収める方法です。

大規模なデータパイプラインを開発するには、Spark を使用する Python トランスフォームまたは Pipeline Builder を使用します。

データセットのブランチ

デフォルトでは、Code Workspaces はワークスペース自体と同じブランチからデータセットのデータを読み込み、そのブランチがない場合は master ブランチにフォールバックします。たとえば、現在 my-branch ブランチにあるコードワークスペースは、データセットの my-branch バージョンを読み取ろうとし、データセットに my-branch が存在しない場合は master ブランチにフォールバックします。

インポートした特定のデータセットのブランチを固定するには、左サイドバーのデータタブで、データセットの横にあるオプションの ••• アイコンを選択します。次に、読み取り用のデータセットブランチを固定を選択し、コードワークスペース内で使用するデータセットブランチを選択します。

データを読み取る

Code Workspaces では、ワークスペースにインポートするすべての Foundry データセットまたは制限付きビューに対して、エイリアスを選択する必要があります。エイリアスは、コード内でデータセットまたは制限付きビューから読み取り、データセットに書き込むための参照として機能します。データタブでデータセットを登録すると、Code Workspaces は、選択したデータセットのエイリアスと Foundry リソースの一意の識別子とのマッピングを、ワークスペースの /home/user/repo/.foundry フォルダー内にある隠しファイルに作成します。

Code Workspaces では、テーブル形式のデータセット、非テーブル形式のデータセット、Iceberg テーブル、仮想テーブル、および制限付きビューを読み込めます。データタブの追加 > データの読み取りボタンを使用して、ワークスペースに新しいデータソースを追加できます。

ワークスペースに追加するデータセットを選択した後、そのリソースの一意の識別子およびコード内の参照として使用するエイリアスを定義する必要があります。データセットの読み取り方法（pandas DataFrame、Polars LazyFrame、生ファイルへのアクセスなど）を選択すると、指定した入力データ型でデータセットを読み込むコードスニペットが生成されます。

  • この読み取り方法は、データセットの登録後でもいつでも変更し、新しいスニペットを生成できます。
  • デフォルトでは、Code Workspaces はデータセット自体と同じ名前をデータセットのエイリアスとして提案します。

完了を選択すると、データセットの登録プロセスが完了し、スニペットを実行またはクリップボードにコピーのオプションを使用して、コード内でデータを使用できるようになります。

このページでは、テーブル形式のデータセット、非テーブル形式のデータセット、および制限付きビューの例を紹介します。

データセットを読み取る際に、ファイル名やファイル件数を知る必要はありません。 1個の Foundry データセットは、多くの場合、多数のファイルを元にしており、それらのファイル名が動的に付けられたり、実行ごとにファイル件数が変わったりすることがあります。これは、出力をパーティション分割するパイプラインや、ファイル名に変数を含めるパイプラインによってデータセットが生成される場合によく見られます。

  • データセットにスキーマがある場合は、read_table または SQL を使用してテーブルとして読み取ります。これらの方法では、データセットの元となるファイルの件数やファイル名に関係なく、論理テーブル全体が読み取られるため、ファイルを個別に列挙する必要はありません。
  • データセットにスキーマがない場合、または生ファイルの内容が必要な場合は、データセット内のすべてのファイルを反復処理することで、名前をハードコードせずにすべてのファイルを読み取ります。

元となるファイルが多数ある、またはファイル名が動的に付けられるという理由で、スキーマを持つ構造化データを非構造化ファイルとして扱う必要はありません。

テーブル形式のデータセット

以下のスニペットは、データセットのエイリアスが kittens であるテーブル形式のデータセット Cats に対して生成されます。コードスニペット内では Cats が一切参照されていないことに注目してください。Code Workspaces は、選択したエイリアスでこのデータセットを暗黙的に登録します。

Jupyter® の場合：

Copied!
1
2
3
4
5
from foundry.transforms import Dataset

kittens = Dataset.get("kittens")\
  .read_table(format="arrow")\
  .to_pandas()

Jupyter® ワークスペースで使用される Dataset クラスで利用可能なメソッドとプロパティの完全な一覧については、foundry.transforms.Dataset API リファレンスを参照してください。

上記の read_table メソッドは、以下の引数をサポートしています。

  • arrow（推奨）： データセットを Apache Arrow テーブルに変換します。このテーブルでは効率的な絞り込みが可能です。その後、.to_pandas() を使用して、このテーブルを pandas データフレームに変換できます。
  • pandas または dataframe： データセットを pandas データフレームに変換します。
  • polars： データセットを Polars データフレームに変換します。その後、.to_pandas() を使用して、pandas データフレームに変換できます。
  • lazy-polars： Polars データフレームの遅延評価版です。遅延評価の polars ではフィルターを実行できません。
  • path： データセットが保存されているローカルパスを出力します。

特定の形式を read_table 操作で利用するには、対応するパッケージである pyarrow、pandas、polars が環境内に存在する必要があります。これらはデフォルトの Code Workspaces 環境に自動的に含まれていますが、カスタム環境には手動で追加する必要がある場合があります。

RStudio® の場合：

Copied!
1
kittens <- datasets.read_table("kittens")

上記の構文はデータセットを読み込み、データを R データフレームに自動的に収集します。

データがワークスペースのメモリー容量を超える場合は、以下の構文を使用してプッシュダウンフィルターを適用し、行または列の一部だけを読み込めます。

Copied!
1
2
3
4
5
library(dplyr) # .Rprofile でデフォルトでインポートされているはずです

kittens_df <- Dataset.get("kittens") %>%
  # （任意）収集する前にほかの変換を適用します
  collect()

SQL でテーブル形式のデータセットをクエリする

Python で SQL を使用して、SQL クエリをサポートする任意のテーブル形式のデータセット、データセットビュー（オブジェクトの実体化を含む）、Iceberg テーブル、または仮想テーブルをクエリできます。

以下のスニペットは、データセットのエイリアスが ducklings であるテーブル形式のデータセット Ducks に対して生成されます。コードスニペット内では Ducks が一切参照されていないことに注目してください。Code Workspaces は、選択したエイリアスでこのデータセットを暗黙的に登録します。

以下の方法では、SELECT Spark SQL 文ごとにクエリできるデータセットは1個のみです。クエリは結果を PyArrow テーブル ↗ として返します。その後、pandas DataFrame などの別の形式に変換できます。

  • SQL クエリのデフォルトの上限は1,000,000行です。一度に1,000,000行を超えるクエリを実行する必要がある場合は、個別のクエリを並列化し、その結果を結合できます。データがワークスペースのメモリーに収まることを確認してください。

Jupyter® の場合：

containers-sql パッケージと foundry-platform-sdk パッケージをインストールした後、FoundrySdkSqlExecutor を使用して Spark SQL を記述できます。

Copied!
1
2
3
4
from containers_sql import FoundrySdkSqlExecutor
sql = FoundrySdkSqlExecutor()
query = sql.execute("SELECT * from `ducklings`")
df = query.fetch_results() # 任意でタイムアウト引数を指定します: query.fetch_results(timeout_in_seconds=60)

また、最初にノートブックの先頭で以下を実行すると、マジックコマンド ↗ も使用できます。

Copied!
1
2
import containers_sql
%reload_ext containers_sql.foundry_sdk.magics

次に、1行のクエリを実行する場合は %sql マジックコマンドを、複数行のクエリを実行する場合は %%sql を使用します。%%sql -o df を使用すると、SQL クエリの結果が PyArrow テーブルとして Python オブジェクト df に代入されます。

Copied!
1
2
ducklings_df = %sql SELECT hatch_date, bill_color, * from `ducklings`
ducklings_pandas_df = ducklings_df.to_pandas()
Copied!
1
2
3
4
5
6
%%sql -o ducklings_df
SELECT
    hatch_date, bill_color, *
FROM
    `ducklings`
LIMIT 10;

RStudio® の場合：

まず、containers-sql、foundry-platform-sdk、pyarrow、reticulate をインストールします。次に、reticulate パッケージと上述の Python SQL エグゼキューターを使用して、データセットをクエリします。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
library(reticulate)

FoundrySdkSqlExecutor <- import("containers_sql")$FoundrySdkSqlExecutor
sql <- FoundrySdkSqlExecutor()
query <- sql$execute("SELECT * from `ducklings`")
results_df <- query$fetch_results()

# データが小さい場合は、中間の R オブジェクトを作成しても問題ありません。
r_list <- py_to_r(results_df$to_pydict())
tibble <- as_tibble(r_list)

# データが大きい場合は、データをディスクに書き込むことを検討します。
# これにより、コンテナのメモリー制限を超えることを回避できます。
library(arrow)
pa <- import("pyarrow")
pa$feather$write_feather(results_df, "tmp.arrow")
tibble <- read_feather("tmp.arrow") |> as_tibble()

非テーブル形式のデータセット

以下のスニペットは、データセットのエイリアスが puppies の非テーブル形式のデータセット Dogs 用に生成されたものです。コードスニペット内では Dogs がどこにも参照されていないことに注目してください。Code Workspaces は、選択したエイリアスでデータセットを暗黙的に登録します。テーブル形式のデータセットを読み込む場合とは異なり、この方法ではデータフレームに値を挿入するのではなく、puppies_files 変数を通じてデータセット内のファイルにアクセスできます。

Jupyter® の場合：

Copied!
1
2
3
4
5
6
from foundry.transforms import Dataset

puppies = Dataset.get("puppies")
puppies_files = puppies.files().download()
with open(puppies_files["puppy_names.txt"], "rb") as f:
    puppy_names_text = f.read().decode("utf-8")

RStudio® の場合：

Copied!
1
2
3
puppies_files <- datasets.list_files("puppies")
puppies_local_files <- datasets.download_files("puppies", puppies_files)
puppy_names_text <- readLines(raw_files_local_files[["puppy_names.txt"]], warn = FALSE)

ワークスペースにダウンロードするファイルを特定のサブセットに絞る方法については、データセットのファイルを絞り込むを参照してください。

データセット内のすべてのファイルを読み込む

データセットにスキーマがあり、そのテーブル形式の内容を扱う場合は、read_table または SQL を使用してテーブルとして読み込むことを推奨します。これらの方法では、元となるすべてのファイルが1個の論理テーブルにまとめられるため、個々のファイルをダウンロードしてパースする必要はありません。

上記の例では、ファイルの正確な名前を指定してアクセスしています。パイプラインによって動的に名前が付けられるファイルや、数が変動する出力ファイルなど、名前が事前にわからないファイルがデータセットにある場合は、名前を直接参照するのではなく、すべてのファイルをダウンロードし、返されたマップを反復処理します。download() メソッドは、各ファイルの名前（現在のデータセットビューで定義されている名前）から、ダウンロード先のローカルパスへのマップを返すため、データセット内のファイル数や名前に関係なくコードが動作します。

Jupyter® の場合：

Copied!
1
2
3
4
5
6
7
8
9
10
from foundry.transforms import Dataset

# 名前や件数に関係なく、データセット内のすべてのファイルをダウンロードします
downloaded_files = Dataset.get("puppies").files().download()

# 名前を明示的に参照せずに、すべてのファイルを反復処理します
for file_name, local_path in downloaded_files.items():
    with open(local_path, "rb") as f:
        contents = f.read()
        # ここで各ファイルの内容を処理します

特定のディレクトリ接頭辞に該当するファイルのみを読み込むなど、ダウンロードするファイルを制限するには、ダウンロード前にファイルのメタデータにフィルターを適用します。

Copied!
1
2
3
4
5
6
7
8
9
10
from foundry.transforms import Dataset

# ディレクトリ接頭辞 "2024/" の下にあるファイルのみをダウンロードします
downloaded_files = Dataset.get("puppies").files()\
    .filter(lambda f: f.path.startswith("2024/"))\
    .download()

for file_name, local_path in downloaded_files.items():
    # ここで各ファイルの内容を処理します
    ...

RStudio® の場合：

Copied!
1
2
3
4
5
6
7
8
9
10
# 名前や件数に関係なく、データセット内のすべてのファイルを一覧表示してダウンロードします
all_files <- datasets.list_files("puppies")
downloaded_files <- datasets.download_files("puppies", all_files)

# 名前を明示的に参照せずに、すべてのファイルを反復処理します
for (file_name in names(downloaded_files)) {
  local_path <- downloaded_files[[file_name]]
  contents <- readLines(local_path, warn = FALSE)
  # ここで各ファイルの内容を処理します
}

制限付きビュー

制限付きビューへのクエリは、Jupyter® ワークスペースでのみサポートされています。

Python で前述の SQL による方法を使用して、制限付きビューにクエリできます。これを行うには、制限付きビューをワークスペースにインポートし、ほかのテーブル形式のデータセットと同様に、そのエイリアスを使用してクエリします。

制限付きビューをコードワークスペースにインポートするには、より高いレベルのデータセキュリティを適用するため、制限付き出力モードを有効にする必要があります。制限付き出力モードを有効にすると、制限付きビュー内のデータを分析できますが、そのデータを使用する出力をワークスペースから公開することはできません。

制限付きビューを初めてワークスペースに追加するときは、特定の Python 依存関係をインストールするように指示するプロンプトが表示されます。その後、データセットの場合と同様にエイリアスを定義し、制限付きビューをワークスペースに追加できます。制限付きビューにクエリするには、制限付き出力モードを有効にしてワークスペースを再起動する必要があります。

制限付きビューのポリシーによって、ユーザーがクエリできるデータが決まります。たとえば、制限付きビューをワークスペースにインポートし、別のユーザーがそのワークスペースを開いた場合、そのユーザーには異なるデータが表示されることがあります。制限付きビューがワークスペースに読み込まれている間にアクセス権が変更されると、そのワークスペースへのアクセス権が失われ、ワークスペースを再起動する必要があります。

データセットのファイルを絞り込む

Code Workspaces では、テーブル形式（つまり、スキーマがある形式）か非テーブル形式かに関係なく、任意のデータセットの元となるファイルをダウンロードできます。ファイル名を指定するか、ファイルのメタデータ（パス、バイト単位のサイズ、トランザクション RID、更新時刻）にフィルターロジックを適用することで、ダウンロードするファイルのサブセットを選択できます。

Jupyter® の場合：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
from foundry.transforms import Dataset

# データセット内のすべてのファイルをダウンロードします
downloaded_files = Dataset.get("my_alias").files().download()
local_file = downloaded_files["file.pdf"]

# 1個のファイルをダウンロードします
local_file = Dataset.get("my_alias").files().get("file.pdf").download()

# データセット内の 1MB より小さいすべての PDF ファイルをダウンロードします
downloaded_files = my_dataset.files()\
    .filter(lambda f: f.path.endswith(".pdf") and f.size_bytes < 1024 * 1024)
    .download()

複数のファイルをダウンロードする場合は、並列ダウンロードを活用するため、ファイル名を指定して個別にダウンロードするのではなく、フィルター構文を使用することを推奨します。

RStudio® の場合：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
# データセット内のすべてのファイルをダウンロードします
all_files <- datasets.list_files("my_alias")
downloaded_files <- datasets.download_files("my_alias", all_files)
local_file <- downloaded_files$`file.pdf`

# 名前を指定してファイルをダウンロードします
downloaded_files <- datasets.download_files("my_alias", c("file1.pdf", "file2.pdf"))

# データセット内の 1MB より小さいすべての PDF ファイルをダウンロードします
all_files <- datasets.list_files("my_alias")
pdf_files <- all_files[sapply(all_files, function(f) f.endswith(".pdf") && f$sizeBytes < 1024*1024)]
downloaded_files <- datasets.download_files("my_alias", pdf_files)

どちらの場合も、downloaded_files は、現在のデータセットビューで定義されているファイル名（スラッシュが含まれる場合があります）から、ファイルのダウンロード先のローカルパスへのマップになります。このローカルパスは変わる可能性があるため、マップのキーを使用することを推奨します。

表形式のデータセットを絞り込む

Code Workspaces では、データセットをメモリーに読み込む前にフィルターを適用できます。これにより、ワークスペースにインポートするデータフレームのメモリー消費量を削減し、分析に関連するデータのサブセットに集中できます。Code Workspaces では、列、行、またはその両方を選択して柔軟に操作できます。

表形式のデータセットにフィルターを使用するタイミング

ワークスペースで利用可能なリソースの範囲内に収まるよう、次の方法を推奨します。

  • 非圧縮データがワークスペースのメモリー内に収まる場合は、フィルターを使用せずにデータセットを読み込み、メモリー内で変換を適用することで、効率を最大限に高められます。

  • 非圧縮データがワークスペースのメモリー容量を超える場合は、列フィルターと行フィルターを使用して、データのサブセットをメモリーに読み込めます。これらのプッシュダウンフィルターは、データがワークスペースに読み込まれる前に適用されるため、インポートするデータのメモリー使用量を削減できます。これらのフィルター操作の速度は、データの規模とパーティション分割によって異なります。また、結果のデータがマシンのメモリー上限内に収まる限り、Python で SQL を使用して、任意のサイズの表形式のデータセットにクエリを実行できます。

    • この方法がユースケースに適さない場合は、Spark ベースのアプリケーションを使用してデータを処理し、Code Workspaces で扱える小さなデータセットを作成することもできます。この方法は、同じデータのサブセットを頻繁に使用したり、複数のワークスペースで使用したりする対話型ワークフローを高速化することがよくあります。これは、データセットの Parquet ファイルは1回だけダウンロードされるのに対し、フィルター処理はデータがワークスペースに読み込まれるたびに実行されるためです。

  • より複雑なデータ読み込み要件がある場合は、非表形式データセットの構文を使用してデータセットの元ファイルをダウンロードし、ネイティブの Python または R パッケージを使用してファイルの内容を処理できます。

行数の制限

データセットから限られた数の行だけを読み込むことができます。

Jupyter® の場合：

Copied!
1
2
3
4
5
from foundry.transforms import Dataset

dogs_subset = Dataset.get("dogs")\
  .limit(1000)\
  .read_table(format="pandas")

RStudio® の場合：

Copied!
1
2
3
4
5
library(dplyr) # .Rprofile でデフォルトでインポートされているはずです

dogs_subset <- Dataset.get("dogs") %>%
  head(1000) %>%
  collect()

列フィルター

すべての表形式のデータセットは、列のサブセットを選択してワークスペースに読み込めます。次のデータセットを例に考えます。

nameweightcoloragebreed
Bella60Brown4Labrador
Max75Black7German Shepherd
Daisy30White2Poodle

dogs データセットがワークスペースに正しく登録されている場合、次の構文を使用して、このデータセットの breed 列と age 列だけを読み込めます。

Jupyter® の場合：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
from foundry.transforms import Dataset, Column

# "breed" 列と "age" 列のみを読み込みます
columns_to_load = ["breed", "age"]
breed_and_age_only = Dataset.get("dogs")\
  .select(*columns_to_load)\
  .read_table(format="pandas")

# "weight" 列と "color" 列のみを読み込みます
weight_and_color_only = Dataset.get("dogs")\
  .select("weight", "color")\
  .read_table(format="pandas")

RStudio® の場合：

Copied!
1
2
3
4
5
6
library(dplyr) # .Rprofile でデフォルトでインポートされているはずです

# "weight" 列と "color" 列のみを読み込みます
weight_and_color_only <- Dataset.get("dogs") %>%
  select(weight, color) %>%
  collect()

行フィルター

表形式のデータセットは、特定の条件を満たす行のサブセットを選択してワークスペースに読み込むこともできます。

行フィルターは、Parquet 形式のデータセットにのみ適用できます。CSV などのほかの形式では、列フィルターは使用できますが、行フィルターは使用できません。Foundry のトランスフォームを使用して、ほとんどの表形式のデータセットを Parquet 形式に変換できます。

先ほどの dogs データセットをもう一度見てみます。

nameweightcoloragebreed
Bella60Brown4Labrador
Max75Black7German Shepherd
Daisy30White2Poodle
Buddy65Yellow3Labrador
Gizmo18Brown1Pug

Jupyter® の行フィルター構文

次の構文を使用して、Jupyter® でデータセットを行単位で絞り込めます。

次の構文を使用して、dogs データセットから茶色の犬だけを読み込めます。

Copied!
1
2
3
4
5
6
from foundry.transforms import Dataset, Column

# 色が "Brown" の犬のみを読み込みます
brown_dogs = Dataset.get("dogs")\
  .where(Column.get("color") == "Brown")\
  .read_table(format="pandas")

.where、select、または .limit を使用して、データセットがワークスペースに読み込まれる前に絞り込んでいる点に注目してください。これらのステートメントを連結することで、複数の条件を一度に適用できます。

Copied!
1
2
3
4
5
# 色が "Brown" で犬種が "Labrador" の犬のみを読み込みます
golden_dogs = Dataset.get("dogs")\
  .where(Column.get("color") == "Brown")\
  .where(Column.get("breed") == "Labrador")\
  .read_table(format="pandas")

以下に、Jupyter® Code Workspaces でサポートされている、有効な行フィルター構文の例をさらに示します。

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
# 特定の値と等しい行のみを保持します
.where(Column.get("column_name") == value)

# 特定の値と等しくない行のみを保持します
.where(Column.get("column_name") != value)

# ~ 演算子を使用した不等比較
.where(~(Column.get("column_name") == value))

# 値を別の値と比較できる行のみを保持します
.where(Column.get("column_name") > value)
.where(Column.get("column_name") >= value)
.where(Column.get("column_name") < value)
.where(Column.get("column_name") <= value)

# OR / AND 演算子
.where((Column.get("column_name") == value1) | (Column.get("column_name") == value2))
.where((Column.get("column_name1") == value1) & (Column.get("column_name2") == value2))

# 値が null ではない行のみを保持します
.where(~Column.get("column_name").isnull())

# 値が指定されたリストに含まれる行のみを保持します
.where(Column.get("column_name").isin([value1, value2, value3]))

# 日付が指定された下限以上、上限以下の行のみを保持します
.where(Column.get("date_column_name").between('lower_bound_incl', 'upper_bound_incl'))

# 先頭の N 行のみを保持します。N は数値です。これはほかのフィルターより先に適用されます
.limit(N)

# 列のサブセットを選択します
.select("column_name1", "column_name2", "column_name3")

RStudio® の行フィルター構文

次の構文を使用して、RStudio® でデータセットを行単位で絞り込めます。

RStudio のフィルターは dplyr ライブラリーを使用して実装されており、標準のメソッドである filter、select、head が実装されています。これらのフィルターはプッシュダウンされます。つまり、データがワークスペースのメモリーに読み込まれる前に適用されます。

次の構文を使用して、dogs データセットから茶色の犬だけを読み込めます。

Copied!
1
2
3
4
5
6
library(dplyr) # .Rprofile でデフォルトでインポートされているはずです

# 色が "Brown" の犬のみを読み込みます
brown_dogs <- Dataset.get("dogs") %>%
  foundry::filter(color == "Brown") %>%
  collect()

foundry::filter を使用して、データセットがワークスペースに読み込まれる前に絞り込んでいる点に注目してください。技術的には foundry:: 接頭辞は必須ではありませんが、環境内のほかのパッケージにある類似名の filter 関数との競合を避けるため、使用を推奨します。これらの filter ステートメントは、dplyr ライブラリーの %>% 演算子を使用して連結することで、複数の条件を一度に適用できます。このライブラリーは、RStudio ワークスペースの .Rprofile ファイルでデフォルトでインポートされているはずです。

Copied!
1
2
3
4
5
6
7
library(dplyr) # .Rprofile でデフォルトでインポートされているはずです

# 色が "Brown" で犬種が "Labrador" の犬のみを読み込みます
brown_labradors <- Dataset.get("dogs") %>%
  foundry::filter(color == "Brown") %>%
  foundry::filter(breed == "Labrador") %>%
  collect()

以下に、RStudio® Code Workspaces でサポートされている、有効な行フィルター構文の例をさらに示します。列名は、引用符で囲まずに foundry::filter 関数に渡す必要があります。

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
# 特定の値と等しい行のみを保持します
foundry::filter(column_name == "string_value") %>%
foundry::filter(integer_column_name == 4) %>%

# 特定の値と等しくない行のみを保持します
foundry::filter(column_name != value) %>%

# ! 演算子を使用した不等比較
foundry::filter(!(column_name == value)) %>%

# 値を別の値と比較できる行のみを保持します
foundry::filter(column_name > value) %>%
foundry::filter(column_name >= value) %>%
foundry::filter(column_name < value) %>%
foundry::filter(column_name <= value) %>%

# OR / AND 演算子
foundry::filter(column_name == value1 | column_name == value2) %>%
foundry::filter(column_name == value1 & column_name == value2) %>%

# 値が指定されたリストに含まれる行のみを保持します
foundry::filter(column_name %in% c("value1", "value2")) %>%

# 値が null ではない行のみを保持します
foundry::filter(!is.na(column_name)) %>%

# 値が指定された下限以上、上限以下の行のみを保持します
foundry::filter(between(age, 2, 4)) %>%

# 列のサブセットを選択します
select(column_name1, column_name2) %>% # 設定する場合は、`filter` 句で使用するすべての列を含める必要があります

# 先頭の N 行のみを保持します。N は数値です。これはほかのフィルターより先に適用されます
head(N) %>%

さらに、データを一時的に Arrow テーブルとして収集することで、group_by などの高度なデータ変換を実行できます。

Copied!
1
2
3
4
5
6
7
8
9
library(dplyr) # .Rprofile でデフォルトでインポートされているはずです

grouped_dogs <- Dataset.get("alias") %>%
  # 単純なフィルターはプッシュダウンできます
  foundry::filter(age > 2) %>%
  collect(as_data_frame = FALSE) %>% # 一時的にデータを Arrow テーブルとして収集します
  # 高度な変換は arrow Table に適用する必要があります
  group_by(breed) %>%
  collect()

列フィルターと行フィルターの併用

列フィルターと行フィルターを併用して、列と行の両方のサブセットを含むデータセットを読み込めます。先ほどの dogs データセットを使用します。

nameweightcoloragebreed
Bella60Brown4Labrador
Max75Black7German Shepherd
Daisy30White2Poodle
Buddy65Yellow3Labrador
Gizmo18Brown1Pug

次の構文を使用して、指定した体重を超える茶色の犬の名前、犬種、色を含むデータセットを取得できます。

Jupyter® の場合：

Copied!
1
2
3
4
5
6
7
8
# 色が "Brown" で体重が62を超える犬のみを読み込みます
# "name" 列、"breed" 列、"color" 列のみを読み込みます
heavy_brown_dogs = Dataset.get("dogs")\
  .where(Column.get("weight") > 62)\
  .where(Column.get("color") == "Brown")\
  .select("name", "breed", "color")\
  .read_table(format="arrow")\
  .to_pandas()

RStudio® の場合：

Copied!
1
2
3
4
5
6
7
8
9
library(dplyr) # .Rprofile でデフォルトでインポートされているはずです

# 色が "Brown" で体重が62を超える犬のみを読み込みます
# "name" 列、"breed" 列、"color" 列のみを読み込みます
heavy_brown_dogs <- Dataset.get("dogs") %>%
  foundry::filter(weight > 62) %>%
  foundry::filter(color == "Brown") %>%
  select("name", "breed", "color") %>%
  collect()

データを書き込む

データ変換のスケジュール設定、データリネージの表示、インクリメンタル（差分処理）での書き込みを行うには、コードを Jupyter® または RStudio のトランスフォームに変換できます。

次の手順で、Code Workspaces を使用して Foundry データセットに対話的に書き込めます。

  1. データタブを開き、データセットをインポートの右側にあるデータセットに保存オプションを選択して、書き込み先の出力データセットを作成します。
  2. 出力データセットの名前と、データセットを保存する場所を選択します。
  3. 保存を選択します。
  4. データタブに新しいデータセットが表示されます。デフォルトでは、データセットに保存オプションが選択されます。出力データセットの場合は、この選択をそのままにしてください。
  5. データセットのエイリアスを指定するダイアログも表示されます。このエイリアスは、データのインポート時のエイリアスと同様に、ワークスペース内での出力データセットの名前になります。
  • 表形式の出力データセットの場合は、データセットに格納するデータフレーム変数を指定するダイアログも表示されます。
  • 表形式ではないデータセットの場合は、代わりにデータセットにアップロードするローカルファイルまたはフォルダーのパスを指定する必要があります。
  1. データセットの種類、データセットのエイリアス、データフレーム変数を設定したら、データセットをコピーして登録を選択して、ワークスペースにデータセットを登録します。この操作により、コードスニペットもクリップボードに保存されます。
  2. ワークスペースにコードスニペットを貼り付け、必要に応じて変数を置き換えてから、コードを実行して出力データセットに書き込みます。

トランザクションの種類

対話的に書き戻す場合、デフォルトでは SDK 関数の各呼び出しが1つのトランザクションに対応します。

  • 表形式のデータを書き戻す場合（Python の output_dataset_tabular.write_table(df_variable) または R の datasets.write_table(df_variable, "output_dataset_tabular")）、SNAPSHOT トランザクションが作成されます。
  • ファイルを書き戻す場合（Python の output_dataset_non_tabular.upload_directory(path_to_file_variable) または R の datasets.upload_files(path_to_file_variable, "output_dataset_non_tabular")）、UPDATE トランザクションが作成されます。

スクリプトをトランスフォームとして登録すると、対話的な呼び出しは code-workspace-sandbox/ で始まるブランチに書き込むようになり、現在のブランチはトランスフォームの実行時に更新されます。この場合、SDK 関数の呼び出しが複数あっても、スクリプト全体の実行に対して1つのトランザクションが作成されます。

  • デフォルトでは、トランザクションの種類は SNAPSHOT になります。
  • インクリメンタル設定が構成されている場合、トランザクションの種類は APPEND になります。

コードスニペットの例

上記の手順に従い、output_dataset_tabular と output_dataset_non_tabular という名前の2つのデータセットを同名の変数で作成し、ワークスペースに登録したとします。Code Workspaces は、選択した変数に基づいて、各データセットに対して次のコードスニペットを生成します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
# テーブル形式のスニペット
from foundry.transforms import Dataset

output_dataset_tabular = Dataset.get("output_dataset_tabular")
output_dataset_tabular.write_table(df_variable)

# 非テーブル形式のスニペット
from foundry.transforms import Dataset

output_dataset_non_tabular = Dataset.get("output_dataset_non_tabular")
output_dataset_non_tabular.upload_directory(path_to_file_variable)

R では次のようになります。

Copied!
1
2
3
4
5
# テーブル形式のスニペット
datasets.write_table(df_variable, "output_dataset_tabular")

# 非テーブル形式のスニペット
datasets.upload_files(path_to_file_variable, "output_dataset_non_tabular")