Condividi tramite

Funzioni semantiche

  • Articolo

Questo articolo descrive le funzioni semantiche e come possono aiutare i data scientist e i data engineer a individuare le funzioni rilevanti per FabricDataFrame o FabricSeries su cui stanno lavorando. Le funzioni semantiche fanno parte della funzionalità di collegamento semantico di Microsoft Fabric.

Per Spark 3.4 e versioni successive, il pacchetto di base del collegamento semantico è disponibile nel runtime predefinito di Fabric, ma il pacchetto semantic-link-functions che include la logica della funzione semantica (ad esempio is_holiday) deve essere installato manualmente. Per eseguire l'aggiornamento alla versione più recente della libreria Python Semantic Link (SemPy), eseguire il comando seguente:

%pip install -U semantic-link

Un FabricDataFrame espone in modo dinamico le funzioni semantiche in base alla logica definita da ogni funzione. Ad esempio, la funzione is_holiday viene visualizzata nei suggerimenti di completamento automatico quando si lavora su un FabricDataFrame che contiene sia una colonna datetime che una colonna country.

Ogni funzione semantica usa informazioni sui dati, i tipi di dati e i metadati (ad esempio le categorie di dati di Power BI) in FabricDataFrame o FabricSeries per determinarne la pertinenza per i dati specifici su cui si sta lavorando.

Le funzioni semantiche vengono individuate automaticamente quando vengono annotate con l'elemento Decorator @semantic_function. È possibile considerare le funzioni semantiche come metodi di estensione C# applicati al concetto di DataFrame.

Suggerimenti per il completamento automatico delle funzioni semantiche

Le funzioni semantiche sono disponibili nei suggerimenti di completamento automatico quando si lavora con FabricDataFrame o FabricSeries. Usare CTRL+SPAZIO per attivare il completamento automatico.

Screenshot delle funzioni semantiche nei suggerimenti di completamento automatico.

L'esempio di codice seguente specifica manualmente i metadati per un 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()

In alternativa, se si legge da un modello semantico in un FabricDataFrame, i metadati vengono popolati automaticamente.

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

Funzioni semantiche predefinite

La libreria SemPy Python offre un set di funzioni semantiche predefinite disponibili per impostazione predefinita. Le funzioni predefinite includono:

  • is_holiday(...) usa il pacchetto Python festività per restituire true se la data è una festività nel paese specificato.
  • to_geopandas(...) converte un FabricDataFrame in un GeoDataFrame GeoPandas.
  • parse_phonenumber(...) usa il pacchetto Python numeri di telefono per analizzare un numero di telefono nei relativi componenti.
  • validators usa il pacchetto Python validators per convalidare i tipi di dati comuni, ad esempio indirizzi di posta elettronica e numeri di carta di credito.

Funzioni semantiche personalizzate

Le funzioni semantiche sono progettate per l'estendibilità. È possibile definire funzioni semantiche personalizzate all'interno del notebook o come moduli Python separati.

Per usare una funzione semantica all'esterno di un notebook, dichiarare la funzione semantica all'interno del modulo sempy.functions. Nell'esempio di codice seguente viene illustrata la definizione di una funzione semantica _is_capital che restituisce true se una città è la capitale di un paese.

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)

Nell'esempio di codice precedente:

  • I parametri col_country e col_city sono annotati rispettivamente con CountryMatcher e CityMatcher. Questa annotazione consente di individuare automaticamente la funzione semantica quando si lavora con un FabricDataFrame con i metadati corrispondenti.
  • La chiamata alla funzione fornisce anche tipi di dati standard, ad esempio str, int, float, e datetime per definire le colonne di input necessarie.
  • L'annotazione del tipo del primo parametro df mostra che la funzione è applicabile a un FabricDataFrame anziché a FabricSeries.

Contenuto correlato