0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@fahmifahim

Microsoft Fabric Notebook パラメーター活用編：Pipeline から JSON 文字列を渡してリスト条件で処理する

0
Last updated at Posted at 2026-05-19

pipeline-notebook-param.png

背景

前回の記事「Microsoft Fabric で Notebook パラメーターを Pipeline から動的に渡して実行する」では、Microsoft Fabric の Pipeline から Notebook にパラメーターを渡し、Notebook 側で処理対象を動的に切り替える基本的な方法を確認しました。

今回はその続きとして、Pipeline から Notebook にリストや配列のような値を渡したい場合の実装方法を確認します。

Fabric Notebook Activity の ベース パラメーター では、list や dict のような複合型を直接渡すことはできません。

Microsoft Docs でも、Notebook parameters は int、float、bool、string などの単純型をサポートし、list や dict は未サポートであるため、複合型を渡したい場合は JSON 文字列として渡し、Notebook 内でデシリアライズする方法が案内されています。

実際のデータ処理では、以下のように複数の値を条件として使いたいケースがあります。

  • 複数の ID に該当するデータだけを抽出したい
  • 複数のコードを条件に isin() でフィルターしたい
  • 数値 ID のリストを条件にしたい
  • 開始日、終了日、処理モードなど複数条件をまとめて渡したい

この記事では、Pipeline から Notebook にパラメーターを渡し、Notebook 側で json.loads() や split() を使ってリスト化し、PySpark の isin() などで利用する方法を確認します。

参考情報

今回のシナリオ

今回は、以下の 4 種類のパラメーターを Pipeline から Notebook に渡すことを想定します。

No パターン 例 Notebook 側での扱い
1 JSON 文字列のリスト ["ID-AAA","ID-BBB","ID-CCC"] json.loads() で Python list に変換
2 数値リスト [101,102,103] json.loads() 後に int として扱う
3 カンマ区切り文字列 AA,BB,CC split(",") で list に変換
4 複数条件の JSON codes, start_date, end_date, mode json.loads() で dict に変換

今回のゴールは、Pipeline から渡された値を Notebook 側でリスト化し、以下のような処理に利用することです。

df.filter(F.col("code").isin(code_list))

パラメーターが渡る流れ

今回のポイントは、以下の流れです。

Pipeline parameter
  ↓ JSON 文字列、またはカンマ区切り文字列として渡す
Notebook Activity ベース パラメーター
  ↓ string として受け取る
Fabric Notebook
  ↓ json.loads() または split() で Python list に変換
PySpark DataFrame
  ↓ isin() で複数値フィルター

重要なのは、Pipeline から Notebook に list / dict を直接渡すのではなく、文字列として渡すことです。

事前に押さえておくポイント

1. list / dict はそのまま渡さない

Fabric Notebook Activity の ベース パラメーター では、list や dict のような複合型は直接サポートされていません。

そのため、以下のような値を渡したい場合は、

["ID-AAA","ID-BBB","ID-CCC"]

Notebook 側では、いったん文字列として受け取り、以下のように Python list に戻します。

import json

id_list = json.loads(param_json_string)

このようにすることで、Pipeline から渡した JSON 文字列を Notebook 内で通常の Python list として扱えるようになります。

2. JSON 文字列の形式に注意する

正しい JSON 文字列の例です。

["ID-AAA","ID-BBB","ID-CCC"]

数値リストの場合は以下のようになります。

[101,102,103]

一方で、以下は JSON として正しくありません。

[ID-AAA,ID-BBB,ID-CCC]

文字列の値は、必ずダブルクォートで囲む必要があります。

3. Notebook の Parameter cell でも文字列として定義する

Notebook 上でローカル実行するだけであれば Python の list として定義することもできます。

ただし、Pipeline から ベース パラメーター で渡す前提の場合は、Notebook 側の Parameter cell でも JSON 文字列として定義しておく方が分かりやすいです。

今回作成する Notebook パラメーター

Notebook の Parameter cell には、以下の 4 種類のパラメーターを定義します。

パラメーター名 内容 例
param_json_string 文字列 ID の JSON 配列 ["ID-AAA","ID-BBB","ID-CCC"]
param_json_int 数値 ID の JSON 配列 [101,102,103]
param_comma_string カンマ区切り文字列 AA,BB,CC
param_multiple_config 複数条件の JSON codes, start_date, end_date, mode

手順

1. Notebook の Parameter cell を作成する

まず、Fabric Notebook に Parameter cell を作成します。

Notebook の Parameter cell は、Pipeline から渡された値で上書きされます。
そのため、Pipeline から実行する前提であれば、Parameter cell には本番データのような固定値を入れず、空のデフォルト値を設定しておく方が安全です。

今回は、Pipeline から値を渡す前提として、以下のように空のデフォルト値を定義します。

# Fabric Notebook Parameter Cell
# Pipeline から渡される値で上書きされる想定です。

param_json_string = "[]"
param_json_int = "[]"
param_comma_string = ""
param_multiple_config = "{}"

ハンズオンや Notebook 単体で動作確認したい場合は、以下のようにサンプル値を入れても問題ありません。

param_json_string = '["ID-AAA","ID-BBB","ID-CCC"]'
param_json_int = '[101,102,103]'
param_comma_string = "AA,BB,CC"
param_multiple_config = '''
{
  "codes": ["ID-AAA", "ID-BBB", "ID-CCC"],
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "mode": "overwrite"
}
'''

次に、作成したセルを Parameter cell に設定します。

手順は以下です。

対象セルを選択
↓
セル右上の ...
↓
Toggle parameter cell

または、Notebook UI 上で Mark cell as parameters を選択します。

2. サンプルデータを作成する

今回は、動作確認しやすいように Notebook 内でサンプル DataFrame を作成します。

実際の環境では、spark.read.table() で Lakehouse Table を読み込む形に置き換えられます。

from pyspark.sql import functions as F

sample_data = [
    ("ID-AAA", 101, "AA", "2026-05-05", 1000),
    ("ID-BBB", 102, "BB", "2026-05-10", 2000),
    ("ID-CCC", 103, "CC", "2026-05-20", 3000),
    ("ID-DDD", 104, "DD", "2026-06-01", 4000),
    ("ID-EEE", 105, "EE", "2026-06-10", 5000)
]

columns = ["code", "numeric_id", "category", "business_date", "amount"]

df = spark.createDataFrame(sample_data, columns)

display(df)

サンプルデータのイメージです。

code numeric_id category business_date amount
ID-AAA 101 AA 2026-05-05 1000
ID-BBB 102 BB 2026-05-10 2000
ID-CCC 103 CC 2026-05-20 3000
ID-DDD 104 DD 2026-06-01 4000
ID-EEE 105 EE 2026-06-10 5000

3. パターン 1：JSON 文字列を list に変換して isin() で使う

最初に、以下のような JSON 文字列を扱います。

["ID-AAA","ID-BBB","ID-CCC"]

Notebook 側では、json.loads() を使って Python list に変換します。

import json

# JSON 文字列を Python list に変換
code_list = json.loads(param_json_string)

# 念のため、空白や None を除外
code_list = [
    str(x).strip()
    for x in code_list
    if x is not None and str(x).strip() != ""
]

print("=== Pattern 1: JSON string list ===")
print("Original parameter:", param_json_string)
print("Parsed list:", code_list)
print("Type:", type(code_list))

df_pattern1 = df.filter(
    F.col("code").isin(code_list)
)

display(df_pattern1)

この例では、code 列が ID-AAA、ID-BBB、ID-CCC のいずれかに一致するデータだけが抽出されます。

isin() は、指定した値の一覧に列の値が含まれているかどうかを判定するために使えます。

4. パターン 2：数値リストを使って isin() でフィルターする

次に、数値のリストを扱います。

Pipeline からは、以下のような JSON 文字列として渡します。

[101,102,103]

Notebook 側では、json.loads() で list に変換した後、必要に応じて int に変換します。

import json

# 数値リストの JSON 文字列を Python list に変換
numeric_id_list = json.loads(param_json_int)

# 念のため int に正規化
numeric_id_list = [
    int(x)
    for x in numeric_id_list
    if x is not None
]

print("=== Pattern 2: JSON numeric list ===")
print("Original parameter:", param_json_int)
print("Parsed list:", numeric_id_list)
print("Type:", type(numeric_id_list))
print("Element types:", [type(x) for x in numeric_id_list])

df_pattern2 = df.filter(
    F.col("numeric_id").isin(numeric_id_list)
)

display(df_pattern2)

数値列に対して isin() を使う場合は、列の型と list の値の型を合わせておく方が安全です。

たとえば、numeric_id が integer 型であれば、list 側も int にしておくと分かりやすいです。

5. パターン 3：カンマ区切り文字列を list に変換して使う

簡単なケースでは、JSON ではなくカンマ区切り文字列として渡すこともできます。

例です。

AA,BB,CC

Notebook 側では、split(",") を使って list に変換します。

# カンマ区切り文字列を Python list に変換
category_list = [
    x.strip()
    for x in param_comma_string.split(",")
    if x.strip() != ""
]

print("=== Pattern 3: Comma separated string ===")
print("Original parameter:", param_comma_string)
print("Parsed list:", category_list)
print("Type:", type(category_list))

df_pattern3 = df.filter(
    F.col("category").isin(category_list)
)

display(df_pattern3)

この方法はシンプルで扱いやすいです。

ただし、値そのものにカンマが含まれる可能性がある場合や、複雑な条件を渡したい場合は JSON 文字列の方が安全です。

6. パターン 4：複数条件を JSON で渡す

最後に、複数の条件を 1 つの JSON 文字列として渡す例です。

{
  "codes": ["ID-AAA", "ID-BBB", "ID-CCC"],
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "mode": "overwrite"
}

このようにすると、コードリストだけでなく、日付範囲や書き込みモードもまとめて Notebook に渡せます。

import json
from pyspark.sql import functions as F

# JSON 文字列を Python dict に変換
config = json.loads(param_multiple_config)

codes = config.get("codes", [])
start_date = config.get("start_date")
end_date = config.get("end_date")
write_mode = config.get("mode", "overwrite")

# codes を文字列 list として正規化
codes = [
    str(x).strip()
    for x in codes
    if x is not None and str(x).strip() != ""
]

print("=== Pattern 4: Multiple config JSON ===")
print("Original parameter:", param_multiple_config)
print("Parsed config:", config)
print("codes:", codes)
print("start_date:", start_date)
print("end_date:", end_date)
print("write_mode:", write_mode)

df_pattern4 = df

# code 条件
if len(codes) > 0:
    df_pattern4 = df_pattern4.filter(
        F.col("code").isin(codes)
    )

# 日付条件
if start_date and end_date:
    df_pattern4 = df_pattern4.filter(
        (F.col("business_date") >= F.lit(start_date)) &
        (F.col("business_date") <= F.lit(end_date))
    )

display(df_pattern4)

この例では、以下の 2 つの条件を同時に適用しています。

code が ID-AAA / ID-BBB / ID-CCC のいずれか
かつ
business_date が 2026-05-01 ～ 2026-05-31 の範囲

7. isin() 以外に使える条件指定の例

複数値の完全一致では isin() が分かりやすいですが、条件によっては他のメソッドも使えます。

7.1 contains() で部分一致する

特定の文字列を含むデータを抽出したい場合は、contains() が使えます。

df_contains = df.filter(
    F.col("code").contains("ID-A")
)

display(df_contains)

7.2 startswith() で前方一致する

コードが特定の文字列から始まるデータを抽出したい場合は、startswith() が使えます。

df_startswith = df.filter(
    F.col("code").startswith("ID-A")
)

display(df_startswith)

7.3 between() で範囲指定する

数値や日付の範囲指定では、between() も使えます。

df_between = df.filter(
    F.col("numeric_id").between(101, 103)
)

display(df_between)

7.4 when() で分岐列を作る

条件に応じて新しい列を作りたい場合は、when() と otherwise() が使えます。

df_flag = df.withColumn(
    "target_flag",
    F.when(F.col("code").isin(code_list), F.lit("target"))
     .otherwise(F.lit("non_target"))
)

display(df_flag)

たとえば、Pipeline から渡した ID リストに該当するデータにだけ target フラグを付ける、といった処理ができます。

8. 実際の Lakehouse Table に適用する場合

ここまではサンプル DataFrame で確認しました。

実際の Lakehouse Table を使う場合は、以下のように読み込み部分を変更します。

source_table_name = "sample_source_table"

df = spark.read.table(source_table_name)

フィルター後に別テーブルとして保存する場合は、以下のように書けます。

target_table_name = "sample_filtered_table"

df_pattern4.write \
    .format("delta") \
    .mode(write_mode) \
    .saveAsTable(target_table_name)

write_mode は、パターン 4 の JSON に含めた mode の値を使っています。

{
  "mode": "overwrite"
}

必要に応じて、append や overwrite に切り替えることができます。

Pipeline 側の設定

1. Pipeline パラメーターを作成する

Pipeline 側で、以下のパラメーターを作成します。

パラメーター名 型 値の例
param_json_string String ["ID-AAA","ID-BBB","ID-CCC"]
param_json_int String [101,102,103]
param_comma_string String AA,BB,CC
param_multiple_config String 複数条件の JSON 文字列

ポイントは、すべて String として扱うことです。

2. Notebook Activity の ベース パラメーター を設定する

Pipeline に Notebook Activity を追加し、対象の Notebook を指定します。

その後、Notebook Activity の ベース パラメーター に以下を設定します。

Base parameter name Value
param_json_string @pipeline().parameters.param_json_string
param_json_int @pipeline().parameters.param_json_int
param_comma_string @pipeline().parameters.param_comma_string
param_multiple_config @pipeline().parameters.param_multiple_config

ここで重要なのは、以下の名前を一致させることです。

Notebook の Parameter cell の変数名
=
Notebook Activity の Base parameter name

たとえば、Pipeline parameter が p_codes_for_filter であっても、Notebook Activity の Base parameter name を param_json_string とし、その Value に @pipeline().parameters.p_codes_for_filter を指定すれば、Notebook 側の param_json_string に値を渡すことができます。

3. 複数条件 JSON の設定例

Pipeline parameter param_multiple_config には、以下のような JSON 文字列を設定します。

{
  "codes": ["ID-AAA", "ID-BBB", "ID-CCC"],
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "mode": "overwrite"
}

Pipeline の画面上で改行を入れると扱いづらい場合は、1 行で書いても問題ありません。

{"codes":["ID-AAA","ID-BBB","ID-CCC"],"start_date":"2026-05-01","end_date":"2026-05-31","mode":"overwrite"}

Notebook 側では json.loads() で同じように読み取れます。

実行確認

Pipeline を実行すると、Notebook 側で以下のように print() されます。

例です。

=== Pattern 1: JSON string list ===
Original parameter: ["ID-AAA","ID-BBB","ID-CCC"]
Parsed list: ['ID-AAA', 'ID-BBB', 'ID-CCC']
Type: <class 'list'>

=== Pattern 2: JSON numeric list ===
Original parameter: [101,102,103]
Parsed list: [101, 102, 103]
Type: <class 'list'>
Element types: [<class 'int'>, <class 'int'>, <class 'int'>]

=== Pattern 3: Comma separated string ===
Original parameter: AA,BB,CC
Parsed list: ['AA', 'BB', 'CC']
Type: <class 'list'>

=== Pattern 4: Multiple config JSON ===
codes: ['ID-AAA', 'ID-BBB', 'ID-CCC']
start_date: 2026-05-01
end_date: 2026-05-31
write_mode: overwrite

このように表示されれば、Pipeline から渡した文字列を Notebook 側で正しく list / dict に変換できています。

よくあるハマりどころ

1. JSON の形式が正しくない

以下は JSON として正しくありません。

[ID-AAA,ID-BBB,ID-CCC]

正しくは以下です。

["ID-AAA","ID-BBB","ID-CCC"]

文字列はダブルクォートで囲む必要があります。

2. Notebook 側で json.loads() していない

Pipeline から以下の値を渡した場合、

["ID-AAA","ID-BBB","ID-CCC"]

Notebook 側では最初は文字列として扱われます。

そのため、以下のように json.loads() で Python list に変換する必要があります。

code_list = json.loads(param_json_string)

3. Parameter cell にしていない

Notebook 側でパラメーター用のセルを作成していても、そのセルを Parameter cell として設定していない場合、Pipeline から値が期待通りに渡らないことがあります。

パラメーターを定義しているセルは、必ず Parameter cell として設定します。

4. パラメーター名が一致していない

以下の名前は一致させる必要があります。

Notebook の変数名
Notebook Activity の Base parameter name

たとえば Notebook 側が以下の場合、

param_json_string = '["ID-AAA","ID-BBB","ID-CCC"]'

Notebook Activity の Base parameter name も以下にします。

param_json_string

5. 数値列に文字列リストを渡している

たとえば、numeric_id が数値型なのに、以下のように文字列の list として扱うと、期待通りに一致しない可能性があります。

numeric_id_list = ["101", "102", "103"]

この場合は、以下のように int に変換しておく方が安全です。

numeric_id_list = [int(x) for x in numeric_id_list]

6. 空リストを渡したときの挙動を決めていない

空の list を isin() に渡すと、基本的には一致する値がなくなります。

df.filter(F.col("code").isin([]))

そのため、空リストの場合にどうするかを事前に決めておくと安全です。

エラーにする例です。

if len(code_list) == 0:
    raise ValueError("code_list is empty.")

空の場合は全件対象にする例です。

if len(code_list) > 0:
    df_filtered = df.filter(F.col("code").isin(code_list))
else:
    df_filtered = df

7. カンマ区切り文字列で値自体にカンマが含まれる

カンマ区切り文字列は簡単ですが、値自体にカンマが含まれるケースには向いていません。

その場合は、JSON 文字列として渡す方が安全です。

まとめ

この記事では、Microsoft Fabric の Pipeline から Notebook に、リストや配列のような値を渡す方法を確認しました。

ポイントは以下です。

  • Fabric Notebook Activity の ベース パラメーター では、list / dict のような複合型は直接扱わない
  • 複数値を渡したい場合は、JSON 文字列として渡す
  • Notebook 側では json.loads() で Python list / dict に戻す
  • 簡単なケースでは、カンマ区切り文字列を split() で list に変換してもよい
  • 複数値の完全一致フィルターでは isin() が使いやすい
  • 日付範囲や処理モードなど複数条件を渡したい場合は、JSON object としてまとめると扱いやすい

実装イメージとしては、以下の流れです。

Pipeline parameter
  ↓
Notebook Activity ベース パラメーター
  ↓
Notebook Parameter cell
  ↓
json.loads() / split()
  ↓
PySpark DataFrame filter
  ↓
Lakehouse Table へ保存

個人的には、PoC や本番運用を考える場合、カンマ区切りよりも JSON 文字列として渡す方法の方が拡張しやすいと感じました。

特に、将来的に以下のような条件を増やしたい場合は、JSON object として渡す方が管理しやすいです。

{
  "codes": ["ID-AAA", "ID-BBB", "ID-CCC"],
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "mode": "overwrite"
}

Disclaimer

本記事は、Microsoft Fabric の検証内容をもとに個人的に整理したものです。
一部、AI を利用して文章の整理や構成案の作成を行っています。
また、Microsoft Fabric は継続的に機能更新が行われているため、最新の仕様や制限事項については Microsoft 公式ドキュメントをご確認ください。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?