Tutorial: Operador da calculadora de juros compostos

Neste tutorial, você cria um operador UDF Python para o Lakeflow Designer que calcula juros compostos. Use este exemplo para aprender os fundamentos da criação de operadores que transformam valores individuais ou colunas. Para saber mais, consulte Operadores personalizados no Lakeflow Designer.

Visão geral

Este tutorial orienta você na criação de um operador personalizado usando um UDF Python. O operador compute o valor futuro de um investimento usando a fórmula de juros compostos, A = P × (1 + r/n)^(n×t), onde:

P = Principal (valor inicial)
r = Taxa de juros anual (em decimal)
n = Número de períodos de capitalização por ano
t = Tempo em anos

Requisitos

Acesso ao Lakeflow Designer em um workspace habilitado para Unity Catalog. Consulte Pré-requisitos.
USE CATALOG no catálogo main, e CREATE SCHEMA em main, ou USE SCHEMA e CREATE FUNCTION em um esquema main.example_output existente. Para usar um catálogo ou esquema diferente, substitua main.example_output por completo. Consulte Referência de privilégios do Unity Catalog.
Compute que pode realizar a execução de UDFs Python do Unity Catalog. Consulte Funções definidas pelo usuário (UDFs) SQL e Python no Unity Catalog.

Passo 1: Escreva e teste a função Python

Primeiro, defina a função principal do Python que realiza o cálculo. Faça um teste em uma célula do Notebook para garantir que funcione corretamente.

Python
def compound_amount(principal: float,
                    annual_rate: float,
                    compounds_per_year: int,
                    years: float) -> float:
    """
    Compute compound interest future value.

    A = P * (1 + r/n)^(n*t)

    principal: starting amount (P)
    annual_rate: annual nominal rate as decimal (r), e.g. 0.05
    compounds_per_year: compounding periods per year (n), e.g. 12
    years: time in years (t), can be fractional
    """
    import math
    if principal is None or annual_rate is None or compounds_per_year is None or years is None:
        return None

    if compounds_per_year <= 0:
        raise ValueError("compounds_per_year must be > 0")

    return principal * math.pow(1.0 + annual_rate / compounds_per_year,
                                 compounds_per_year * years)

Teste a função com um investimento de exemplo: $ 1.000 a uma taxa anual de 5%, com juros compostos mensais ao longo de 10 anos. O resultado deve ser aproximadamente 1647.01.

Python
compound_amount(1000, 0.05, 12, 10)

o passo 2: Crie o YAML para o operador

A configuração YAML define como o operador aparece no LakeFlow Designer. Para esta operadora:

Principal usa um widget expression para que os usuários possam selecionar uma coluna de seus dados.
A taxa anual , os juros compostos por ano e os anos usam widgets number com valores padrão e restrições.
O operador possui uma porta de entrada que fornece dados de coluna para o parâmetro de expressão.

YAML
schema: custom-operator-v0.1.0
type: uc-udf
name: Compound Amount
id: finance.compound_amount
version: '1.0.0'
description: >
  Computes the future value of an investment using compound interest.
  Formula: A = P * (1 + r/n)^(n*t)
config:
  type: object
  properties:
    principal:
      type: string
      format: expression
      title: Principal
      examples:
        - 'Select principal column or expression'
      x-ui:
        widget: expression
        port: in
    annual_rate:
      type: number
      title: Annual rate (decimal)
      default: 0.05
      minimum: 0
      examples:
        - 'e.g. 0.05 for 5%'
      x-ui:
        widget: number
    compounds_per_year:
      type: number
      title: Compounds per year
      default: 12
      minimum: 1
      examples:
        - 'e.g. 12 for monthly'
      x-ui:
        widget: number
    years:
      type: number
      title: Years
      default: 10
      minimum: 0
      examples:
        - 'Time in years (t)'
      x-ui:
        widget: number
  required:
    - principal
    - annual_rate
    - compounds_per_year
    - years
  additionalProperties: false
ports:
  input:
    - name: in
      title: Input
  output:
    - name: out
      title: Output

Para todas as propriedades disponíveis, tipos de dados, widgets e opções, consulte Referência de YAML do operador personalizado.

o passo 3: Criar a função Unity Catalog

Combine o esquema YAML e a função Python em uma única instrução CREATE FUNCTION . A configuração YAML deve ser inserida na docstring no início do corpo da função.

O exemplo cria a função em main.example_output. Crie o esquema primeiro, caso ele não exista:

SQL
CREATE SCHEMA IF NOT EXISTS main.example_output

SQL
CREATE OR REPLACE FUNCTION main.example_output.compound_amount(
    principal DOUBLE,
    annual_rate DOUBLE,
    compounds_per_year INT,
    years FLOAT)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
  """
  schema: custom-operator-v0.1.0
  type: uc-udf
  name: Compound Amount
  id: finance.compound_amount
  version: "1.0.0"
  description: >
    Computes the future value of an investment using compound interest.
    Formula: A = P * (1 + r/n)^(n*t)
  config:
    type: object
    properties:
      principal:
        type: string
        format: expression
        title: Principal
        examples:
          - "Select principal column or expression"
        x-ui:
          widget: expression
          port: in
      annual_rate:
        type: number
        title: Annual rate (decimal)
        default: 0.05
        minimum: 0
        examples:
          - "e.g. 0.05 for 5%"
        x-ui:
          widget: number
      compounds_per_year:
        type: number
        title: Compounds per year
        default: 12
        minimum: 1
        examples:
          - "e.g. 12 for monthly"
        x-ui:
          widget: number
      years:
        type: number
        title: Years
        default: 10
        minimum: 0
        examples:
          - "Time in years (t)"
        x-ui:
          widget: number
    required:
      - principal
      - annual_rate
      - compounds_per_year
      - years
    additionalProperties: false
  ports:
    input:
      - name: in
        title: Input
    output:
      - name: out
        title: Output
  """

  def compound_amount(principal: float,
                      annual_rate: float,
                      compounds_per_year: int,
                      years: float) -> float:
      import math
      if principal is None or annual_rate is None or compounds_per_year is None or years is None:
          return None

      if compounds_per_year <= 0:
          raise ValueError("compounds_per_year must be > 0")

      return principal * math.pow(1.0 + annual_rate / compounds_per_year,
                                   compounds_per_year * years)

  return compound_amount(principal, annual_rate, compounds_per_year, years)
$$

o passo 4: Teste a função

Teste a função UC diretamente com SQL. Estas queries verificam três cenários:

$ 1.000 a 5% de juros compostos mensalmente durante 10 anos, o que retorna aproximadamente 1647.01
$ 1.000 a 5% com juros compostos anuais por 1 ano, o que retorna 1050.00
$ 1.000 a 15% de juros compostos mensalmente durante 1 ano, o que retorna aproximadamente 1160.75

SQL
SELECT main.example_output.compound_amount(1000, 0.05, 12, 10);
SELECT main.example_output.compound_amount(1000, 0.05, 1, 1);
SELECT main.example_output.compound_amount(1000, 0.15, 12, 1);

o passo 5: registrar a operadora

Adicione o operador ao seu arquivo .custom_operators.yaml :

YAML
operators:
  - catalog: main
    schema: example_output
    functionName: compound_amount

nota

Se você definir esse arquivo em sua pasta de usuário, ele aparecerá apenas para você. Para obter mais informações, consulte Registrar e implantar seu operador no Lakeflow Designer.

o passo 6: Configurar permissões

Conceda acesso aos usuários que precisam usar esta operadora:

SQL
GRANT USE SCHEMA ON SCHEMA main.example_output TO `<user>`;
GRANT EXECUTE ON FUNCTION main.example_output.compound_amount TO `<user>`;

o passo 7: Usar o operador no Lakeflow Designer

Em uma preparação visual de dados, abra o menu Operadores no painel esquerdo e encontre o operador Montante Composto .
Arraste o operador para a tela e conecte uma entrada a ele.
Clique duas vezes no operador para abrir seu painel de configuração e defina seus campos.
Selecione o operador para visualizar seus resultados no painel de saída.

O painel de configuração do operador inclui:

Uma dropdown para selecionar a coluna principal dos seus dados de entrada.
Número de entradas para taxa, frequência de capitalização e anos (com valores padrão razoáveis)

Os usuários podem aplicar esse operador para calcular valores futuros para colunas inteiras de dados de investimento.

Visão geral​

Requisitos​

Passo 1: Escreva e teste a função Python​

o passo 2: Crie o YAML para o operador​

o passo 3: Criar a função Unity Catalog​

o passo 4: Teste a função​

o passo 5: registrar a operadora​

o passo 6: Configurar permissões​

o passo 7: Usar o operador no Lakeflow Designer​

Outros recursos​