🐬Spotfire 自動報表腳本常見錯誤解析：IronPython 變數未定義與 SQL 查詢結果不一致的完整排查指南

- 3月 16, 2026

一、問題背景：Spotfire 自動報表腳本出現奇怪錯誤

在企業 BI 系統中，許多工程師會使用 Spotfire + IronPython 來建立自動化報表，例如：

每週自動匯出 CSV
每月產生 PDF 報表
定期從資料庫抓取資料

例如典型流程：

透過 SQL 從資料庫抓取資料
更新 Spotfire Data Table
依不同產品分類輸出報表
匯出 CSV 或 PDF

然而在實務中，常常會遇到這些問題：

常見錯誤

1️⃣ SQL 在 SQL Server 有資料，但 Spotfire 查不到
2️⃣ IronPython 出現變數未定義錯誤
3️⃣ Data Table 不存在
4️⃣ 自動化報表腳本中途停止

例如錯誤訊息：


IronPython.Runtime.UnboundNameException: name 'ReportList' is not defined

或


The table named 'CHECK_TABLE' does not exist

這些問題其實非常常見。

二、典型自動報表腳本架構

以下是一個簡化版的 Spotfire 自動報表流程（已重新設計範例程式）。

Step 1：產生查詢日期


from datetime import datetime, timedelta

today = datetime.today()

start_date = today - timedelta(days=7)
end_date = today

start_str = start_date.strftime("%Y-%m-%d")
end_str = end_date.strftime("%Y-%m-%d")

Step 2：建立 SQL 查詢


sql_query = """
SELECT
    product_id,
    batch_id,
    total_units,
    pass_units
FROM production_yield
WHERE test_time >= '{start}'
AND test_time < '{end}'
""".format(start=start_str, end=end_str)

Step 3：更新 Spotfire Data Table


result = API.UpdateDataTable(
    "YIELD_TABLE",
    "Database|Datasource:main_db|SqlStatement:" + sql_query
)

print("Update result:", result)

Step 4：取得產品清單


product_list = API.GetDistinctValues("YIELD_TABLE", "product_id")
print(product_list)

Step 5：匯出報表


for product in product_list:

    filter_expression = "[product_id] = '" + product + "'"
    table.SetFilter(filter_expression)

    filename = product.replace("/", "_")

    API.ExportCSV(
        "Yield Table",
        export_path + "\\" + filename + ".csv"
    )

三、問題一：SQL Server 有資料，但 Spotfire 查不到

這是最常見問題。

原因通常有三個

1️⃣ Spotfire 連到不同資料庫

例如：

SQL Server 查詢：


Server A
Database: Production

Spotfire datasource：


Server B
Database: Test

結果：


SQL Server 有資料
Spotfire 沒資料

排查方式

執行以下 SQL 確認 Spotfire 連線環境：


SELECT 
    @@SERVERNAME AS server_name,
    DB_NAME() AS database_name

若結果不同，就代表 資料源設定錯誤。

四、問題二：日期格式導致查詢失敗

很多人會寫：


WHERE test_time > '2026/1/21'

但 SQL Server 在不同語系環境中解析日期可能不同。

例如：

格式	風險
2026/1/21	高
2026-01-21	低
2026-01-21T00:00:00	最安全

建議寫法


WHERE test_time >= '2026-01-21T00:00:00'
AND test_time < '2026-01-28T00:00:00'

這樣可以避免：

語系問題
時間邊界問題

五、問題三：IronPython 變數未定義錯誤

常見錯誤：


UnboundNameException: name 'ReportList' is not defined

原因

程式中途發生錯誤，導致變數沒有被建立。

例如：


ReportList = API.GetDistinctValues("YIELD_TABLE", "product_id")

for r in ReportList:
    export(r)

如果 GetDistinctValues 出錯：


ReportList 根本沒有建立

後面就會出現未定義錯誤。

安全寫法

先設定預設值：


ReportList = []

try:
    ReportList = API.GetDistinctValues("YIELD_TABLE", "product_id")
except Exception as e:
    print("Error:", e)

再檢查是否有資料：


if not ReportList:
    print("No data found.")
else:
    for r in ReportList:
        export(r)

六、問題四：Spotfire Data Table 不存在

常見錯誤：


The table named 'CHECK_TABLE' does not exist

原因：

Spotfire API 有些方法只能 更新已存在 Data Table，不能建立新表。

例如：


API.UpdateDataTable("CHECK_TABLE", sql)

如果 CHECK_TABLE 不存在，就會出錯。

解法

先確認 Data Table 是否存在：


tables = [t.Name for t in Document.Data.Tables]

if "CHECK_TABLE" not in tables:
    print("Table not found")

七、企業 BI 自動化報表最佳實務

在企業 BI 專案中，建議遵守以下原則。

1️⃣ SQL 日期一律使用 ISO 格式


YYYY-MM-DD

2️⃣ 每一步都要加入 log

例如：


print("Step1: SQL query generated")
print("Step2: Data table updated")
print("Step3: Exporting reports")

3️⃣ 所有關鍵變數先初始化


ReportList = []
result = None

4️⃣ 所有資料庫操作加 try/except

避免 script 中途停止。

八、完整自動報表流程

典型企業 BI 自動化流程如下：


資料庫
   ↓
Spotfire SQL Query
   ↓
更新 Data Table
   ↓
取得產品清單
   ↓
套用 Filter
   ↓
匯出 CSV
   ↓
匯出 PDF

九、結論

Spotfire 自動報表腳本常見問題其實集中在三件事：

1️⃣ 資料來源環境不同
2️⃣ 日期格式錯誤
3️⃣ IronPython 例外處理不足

只要建立良好的排查流程，就能快速定位問題。

搜尋此網誌

小小大大學