Partilhar 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 que são 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 superior, o pacote de núcleo de link semântico está disponível no tempo de execução padrão do Fabric, mas o pacote semantic-link-functions que inclui a lógica de função semântica (como is_holiday) precisa ser instalado manualmente. Para atualizar para a versão mais recente da biblioteca de link semântico Python (SemPy), execute o 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 is_holiday função aparece nas sugestões de preenchimento automático quando você trabalha em um FabricDataFrame que contém uma coluna datetime e uma coluna country.

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 em que você está trabalhando.

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

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

As 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ê ler 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 incorporadas

A biblioteca Python SemPy fornece um conjunto de funções semânticas internas que estão disponíveis prontamente. Estas funções incorporadas incluem:

Funções semânticas personalizadas

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

Para usar uma função semântica fora de um bloco de anotações, declare a função semântica dentro do sempy.functions módulo. O exemplo de código a seguir mostra a definição de uma função _is_capital semântica que retorna true se uma cidade é 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 col_country parâmetros e col_city são anotados com CountryMatcher e CityMatcher, respectivamente. Essa anotação permite que a função semântica seja descoberta automaticamente ao trabalhar com um FabricDataFrame que tenha os metadados correspondentes.
  • Chamar a função também fornece tipos de dados padrão, como str, int, floate 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údos relacionados