Compartilhar via

Funções semânticas

  • Artigo

Este artigo descreve funções semânticas e como elas podem ajudar cientistas de dados e engenheiros de dados a descobrir funções relevantes para o FabricDataFrame ou FabricSeries em que estão trabalhando. As funções semânticas fazem parte do recurso de link semântico do Microsoft Fabric.

Para o Spark 3.4 e versões posteriores, o pacote principal de link semântico está disponível no runtime padrão do Fabric, mas o pacote “semantic-link-functions” que inclui a lógica da função semântica (como is_holiday) precisa ser instalado manualmente. Para atualizar para a versão mais recente da biblioteca de links semânticos do Python (SemPy), faça a execução do seguinte comando:

%pip install -U semantic-link

Um FabricDataFrame expõe dinamicamente funções semânticas com base na lógica que cada função define. Por exemplo, a função is_holiday aparece nas sugestões de preenchimento automático quando você trabalha em um FabricDataFrame que contém uma coluna de datetime e uma coluna de país.

Cada função semântica usa informações sobre os dados, tipos de dados e metadados (como categorias de dados do Power BI) no FabricDataFrame ou FabricSeries para determinar sua relevância para os dados específicos nos 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 métodos de extensão do C# aplicados ao conceito DataFrame.

Sugestões de preenchimento automático de funções semânticas

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

Captura de tela de funções semânticas em sugestões de preenchimento automático.

O exemplo de código a seguir especifica manualmente os metadados para um 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, se você realizar a leitura de um modelo semântico em um FabricDataFrame, os metadados serão preenchidos 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()

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. As funções internas incluem:

  • is_holiday(...) usa o pacote Python de feriados para retornar true se a data for um feriado no país fornecido.
  • to_geopandas(...) converte um FabricDataFrame em um GeoPandas no GeoDataFrame.
  • parse_phonenumber(...) usa o pacote Python de números de telefone para analisar um número de telefone em seus componentes.
  • validators usa o pacote Python de validadores para validar tipos de dados comuns, como email e números de cartão de crédito.

Funções semânticas personalizadas

Funções semânticas são projetadas para extensibilidade. Você pode definir suas próprias funções semânticas em seu Notebook ou como módulos do Python separados.

Para usar uma função semântica fora de um Notebook, declare a função semântica dentro do módulo sempy.functions. O exemplo de código a seguir mostra a definição de uma função semântica _is_capital que retorna true se uma cidade for a capital de um 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)

No exemplo de código anterior:

  • 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 e não a um FabricSeries.

Conteúdo relacionado