通过

语义函数

  • 项目

本文介绍了语义函数，以及它们如何帮助数据科学家和数据工程师发现与其使用的 FabricDataFrame 或 FabricSeries 相关的函数。 语义函数是 Microsoft Fabric 语义链接功能的一部分。

对于 Spark 3.4 及更高版本，语义链接核心包在默认 Fabric 运行时中可用，但包含语义函数逻辑（如 is_holiday）的语义链接函数包需要手动安装。 若要更新到最新版本的 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 模块中声明该语义函数。 以下代码示例显示了语义函数 _is_capital 的定义，如果此城市是国家/地区的首都，该函数会返回 true。

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 时自动发现语义函数。
  • 调用该函数还会提供标准数据类型，例如 strintfloat 以及 datetime，以定义所需的输入列。
  • 第一个参数 df 的类型注释显示该函数适用于 FabricDataFrame，而不是 FabricSeries。

相关内容