Pular para o conteúdo principal
Última atualização em

Tutorial: Operador da calculadora de juros compostos

Neste tutorial, cria-se um operador de UDF em Python para o Lakeflow Designer que calcula juros compostos. Usar este exemplo para aprender os fundamentos da construção de operadores que transformam valores individuais ou colunas. Para saber mais, consulte Operadores definidos pelo usuário em Lakeflow Designer.

Visão geral​

Este tutorial irá guiá-lo passo a passo na criação de um operador definido pelo usuário usando uma UDF Python . O operador calcula 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

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: user-defined-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

Consulte a referência YAML do operador definido pelo usuário para obter um guia completo de todas as propriedades, tipos de dados, widgets e opções disponíveis.

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: user-defined-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 .user_defined_operators.yaml :

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

Se você definir esse arquivo na sua pasta de usuário, ele aparecerá apenas para você. Para obter mais informações, consulte Torne seu operador detectável.

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>`;

Utilize o operador no Lakeflow Designer​

Após ser registrado, o operador aparece no Lakeflow Designer com:

  • 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.

Nesta página