Compartir a través de

Funciones semánticas

  • Artículo

En este artículo se describen las funciones semánticas y cómo pueden ayudar a los científicos e ingenieros de datos a detectar funciones relevantes para las instancias de FabricDataFrame o FabricSeries con las que trabajan. Las funciones semánticas forman parte de la característica de vínculo semántico de Microsoft Fabric.

Para Spark 3.4 y versiones posteriores, el paquete principal de vínculo semántico está disponible en el runtime de Fabric predeterminado, pero el paquete semantic-link-functions que incluye la lógica de función semántica (como is_holiday) se debe instalar manualmente. Para actualizar a la versión más reciente de la biblioteca de vínculo semántico de Python (SemPy), ejecute el siguiente comando:

%pip install -U semantic-link

Una instancia de FabricDataFrame expone dinámicamente funciones semánticas basadas en la lógica definida por cada función. Por ejemplo, la función is_holiday aparece en las sugerencias de autocompletar cuando se trabaja en una instancia de FabricDataFrame que contiene una columna datetime y una columna de país.

Cada función semántica usa información sobre los datos, tipos de datos y metadatos (como las categorías de datos de Power BI) de FabricDataFrame o FabricSeries a fin de determinar su relevancia con los datos concretos con los que se trabaja.

Las funciones semánticas se detectan automáticamente cuando se anotan con el decorador @semantic_function. Puede considerar a las funciones semánticas como similares a los métodos de extensión de C# aplicados al concepto de DataFrame.

Sugerencias de autocompletar de las funciones semánticas

Las funciones semánticas están disponibles en las sugerencias de autocompletar cuando se trabaja con FabricDataFrame o FabricSeries. Puede presionar Ctrl+Espacio para activar la función de autocompletar.

Captura de pantalla de las funciones semánticas en sugerencias de autocompletar.

En el ejemplo de código siguiente, se especifican manualmente los metadatos de una instancia de 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()

Como alternativa, si lee de un modelo semántico en una instancia de FabricDataFrame, los metadatos se rellenan automáticamente.

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()

Funciones semánticas integradas

La biblioteca de Python de SemPy proporciona un conjunto de funciones semánticas integradas que están disponibles de forma predeterminada. Estas funciones integradas son las siguientes:

  • is_holiday(...) usa el paquete de Python holidays para devolver true si la fecha es un día festivo en el país determinado.
  • to_geopandas(...) convierte un elemento FabricDataFrame en un elemento GeoDataFrame de GeoPandas.
  • parse_phonenumber(...) usa el paquete de Python de números de teléfono para analizar un número de teléfono en sus componentes.
  • validators usa el paquete validators de Python para validar tipos de datos comunes, como números de tarjeta de crédito y correo electrónico.

Funciones semánticas personalizadas

Las funciones semánticas están diseñadas para la extensibilidad. Puede definir funciones semánticas propias en el cuaderno o como módulos independientes de Python.

Para usar una función semántica fuera de un cuaderno, declare la función semántica dentro del módulo sempy.functions. En el ejemplo de código siguiente se muestra la definición de una función semántica _is_capital que devuelve true si la ciudad es la capital de un país.

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)

En el ejemplo de código anterior:

  • Los parámetros col_country y col_city se anotan con CountryMatcher y CityMatcher, respectivamente. Esta anotación permite que la función semántica se detecte automáticamente al trabajar con un FabricDataFrame que tenga los metadatos correspondientes.
  • La llamada a la función también proporciona tipos de datos estándar, como str, int, floaty datetime para definir las columnas de entrada necesarias.
  • La anotación de tipo del primer parámetro df muestra que la función es aplicable a una instancia de FabricDataFrame, en lugar de a FabricSeries.

Contenido relacionado