語意函數
本文說明語意函數，以及其如何協助資料科學家和資料工程師探索與所處理之 FabricDataFrame 或 FabricSeries 相關的函數。 語意函數是 Microsoft Fabric 語意連結功能的一部分。
針對 Spark 3.4 及更新版本，語意連結核心套件可在預設 Fabric 執行階段使用，但需要手動安裝包含語意函數邏輯 (例如 is_holiday) 的 semantic-link-functions 套件。 若要更新至最新版本的 Python 語意連結 (SemPy) 程式庫，請執行下列命令：
%pip install -U semantic-link
FabricDataFrame 會根據每個函數所定義的邏輯，動態公開語意函數。
例如，當您處理同時包含日期時間資料行和國家/地區資料行的 FabricDataFrame 時，is_holiday 函數會出現在自動完成建議中。
每個語意函數都會使用 FabricDataFrame 或 FabricSeries 中有關資料、資料類型和中繼資料的資訊 (例如 Power BI 資料類別)，以判定其與您所處理之特定資料的相關性。
在使用 @semantic_function 裝飾項目標註時，會自動探索語意函數。
您可以將語意函數視為套用至 DataFrame 概念的 C# 擴充方法。
語意函數自動完成建議
當您使用 FabricDataFrame 或 FabricSeries 時，可在自動完成建議中使用語意函數。 使用 Ctrl+空格鍵來觸發自動完成。
下列程式碼範例會手動指定 FabricDataFrame 的中繼資料：
from sempy.fabric import FabricDataFrame
df = FabricDataFrame(
{"country": ["US", "AT"],
"lat": [40.7128, 47.8095],
"long": [-74.0060, 13.0550]},
column_metadata={"lat": {"data_category": "Latitude"}, "long": {"data_category": "Longitude"}},
)
# Convert to GeoPandas dataframe
df_geo = df.to_geopandas(lat_col="lat", long_col="long")
# Use the explore function to visualize the data
df_geo.explore()
或者，如果您從語意模型讀取到 FabricDataFrame，則會自動填入中繼資料。
from sempy.fabric import FabricDataFrame
# Read from semantic model
import sempy.fabric as fabric
df = fabric.read_table("my_dataset_name", "my_countries")
# Convert to GeoPandas dataframe
df_geo = df.to_geopandas(lat_col="lat", long_col="long")
# Use the explore function to visualize the data
df_geo.explore()
內建語意函數
SemPy Python 程式庫提供一組現成可用的內建語意函數。 這些內建函數包括：
- 如果日期是指定國家/地區的假日，則
is_holiday(...)會使用假日 Python 套件傳回true。 to_geopandas(...)會將 FabricDataFrame 轉換為 GeoPandas GeoDataFrame。parse_phonenumber(...)會使用電話號碼 Python 套件，將電話號碼剖析成其元件。validators會使用驗證程式 Python 套件來驗證常見的資料類型，例如電子郵件和信用卡號碼。
自訂語意函數
語意函數針對擴充性而設計。 您可以在筆記本內定義自己的語意函數，或將其作為單獨的 Python 模組。
若要在筆記本外部使用語意函數，請在 sempy.functions 模組內宣告語意函數。 如果城市是國家/地區的首府，下列程式碼範例會顯示傳回 true 的語意函數 _is_capital 的定義。
from sempy.fabric import FabricDataFrame, FabricSeries
from sempy.fabric.matcher import CountryMatcher, CityMatcher
from sempy.functions import semantic_function, semantic_parameters
@semantic_function("is_capital")
@semantic_parameters(col_country=CountryMatcher, col_city=CityMatcher)
def _is_capital(df: FabricDataFrame, col_country: str, col_city: str) -> FabricSeries:
"""Returns true if the city is the capital of the country"""
capitals = {
"US": ["Washington"],
"AT": ["Vienna"],
# ...
}
return df[[col_country, col_city]] \
.apply(lambda row: row[1] in capitals[row[0]], axis=1)
在上述程式碼範例中：
col_country和col_city參數分別以CountryMatcher和CityMatcher加上註釋。 此註釋允許在使用具有對應中繼資料的 FabricDataFrame 時，自動探索語意函數。- 呼叫函數也會提供標準資料類型，例如
str、int、float和datetime來定義必要的輸入資料行。 - 第一個參數
df的類型註釋會顯示函數適用於 FabricDataFrame，而不是 FabricSeries。