Funções semânticas

Este artigo aborda funções semânticas e como elas podem ajudar cientistas de dados e engenheiros de dados a descobrir funções que são relevantes para o FabricDataFrame ou FabricSeries em que estão trabalhando.

Para o Spark 3.4 e superior, o link semântico está disponível no runtime padrão ao usar o Fabric e não há necessidade de instalá-lo. Se você estiver usando o Spark 3.3 ou inferior, ou se quiser atualizar para a versão mais recente do link semântico, poderá executar o comando:

python %pip install -U semantic-link  

Os FabricDataFrames expõem dinamicamente funções semânticas com base na lógica definida por cada função. Por exemplo, a função is_holiday aparece nas sugestões de preenchimento automático quando você está trabalhando em um FabricDataFrame que contém uma coluna de data e hora e uma coluna de país/região.

Cada função semântica usa informações sobre os tipos de dados, metadados (como categorias de dados do Power BI) e os dados em um FabricDataFrame ou FabricSeries para determinar sua relevância para os dados específicos com os quais você está trabalhando.

Funções semânticas são automaticamente descobertas quando anotadas com o decorador @semantic_function. Você pode pensar em funções semânticas como sendo semelhantes a métodos de extensão C# aplicados ao popular conceito de DataFrame.

Uso da função semântica: sugestões de preenchimento automático

Funções semânticas estão disponíveis nas sugestões de preenchimento automático quando você trabalha com um FabricDataFrame ou FabricSeries. Você pode usar CTRL+Espaço para disparar o preenchimento automático.

No exemplo a seguir, os metadados para o FabricDataFrame são especificados manualmente.

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

Alternativamente, você poderia ler de um modelo semântico em um FabricDataFrame, e nesse caso, os metadados serão autopreenchidos.

from sempy.fabric import FabricDataFrame

# Alternative: reading 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()

Funções semânticas internas

A biblioteca Python SemPy fornece um conjunto de funções semânticas internas que estão disponíveis prontas para uso. Alguns exemplos são

• is_holiday(...), que retorna true se a data for um feriado no país/região determinado, usando o pacote python holidays.
• to_geopandas(...), que converte um FabricDataFrame em um GeoPandas GeoDataFrame.
• parse_phonenumber(...), que analisa um número de telefone em seus componentes, usando o pacote Python phone numbers.
• validators, que realiza validação de dados para tipos de dados comuns, como email e números de cartão de crédito. A função semântica usa o pacote Python validators.

Funções semânticas personalizadas

Funções semânticas são construídas para extensibilidade. Você pode definir suas próprias funções semânticas dentro do seu notebook ou como um módulo Python separado. Para usar uma função semântica fora de um notebook, a função semântica precisa ser declarada dentro do módulo sempy.functions.

Este exemplo de código mostra a definição de uma função semântica _is_captial que retorna true se a cidade for a capital do país.

from sempy.fabric import FabricDataFrame, FabricSeries
from sempy.fabric.matcher import CountryMatcher, CityMatcher
from sempy.functions import semantic_function, semantic_paramters

@semantic_function("is_capital")
@semantic_parameters(col_country=CountryMatcher, col_city=CityMatcher)
def _is_captial(df: FabricDataFrame, col_country: str, col_city: str) -> FabricSeries:
    """Returns true if the city is a 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)

Os pontos a seguir fornecem uma análise do trecho de código:

• Os parâmetros col_country e col_city são anotados com CountryMatcher e CityMatcher, respectivamente. Esta anotação permite que a função semântica seja automaticamente descoberta ao trabalhar com um FabricDataFrame que possui os metadados correspondentes.
• Chamar a função também fornece tipos de dados padrão como str, int, float e datetime para definir as colunas de entrada necessárias.
• A anotação de tipo do primeiro parâmetro (df) mostra que a função é aplicável a um FabricDataFrame, em vez de um FabricSeries.

Conteúdo relacionado

• Confira sempy.functions para aprender sobre o uso de funções semânticas
• Tutorial: limpeza de dados com dependências funcionais
• Conectividade do Power BI com o Link Semântico e o Microsoft Fabric
• Propagação de dados semânticos de modelos semânticos