Tutorial: Operador de calculadora de juros compostos

Neste tutorial, crias um operador Python UDF para o Lakeflow Designer que calcula o juro composto. Utilize este exemplo para aprender os fundamentos da criação de operadores que transformam valores individuais ou colunas. Para saber mais, consulte Operadores definidos pelo utilizador no Lakeflow Designer.

Overview

Este tutorial orienta-o na criação de um operador definido pelo utilizador usando um UDF em Python. O operador calcula o valor futuro de um investimento usando a fórmula do juro composto, A = P × (1 + r/n)^(n×t), onde:

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

Passo 1: Escrever e testar a função Python

Primeiro, defina a função central de Python que realiza o cálculo. Teste-o numa célula de notebook para garantir que funciona corretamente.

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%, capitalizada mensalmente durante 10 anos. O resultado deve ser aproximadamente 1647.01.

compound_amount(1000, 0.05, 12, 10)

Passo 2: Criar o YAML para o operador

A configuração YAML define como o operador aparece no Lakeflow Designer. Para este operador:

  • O Principal utiliza um expression widget para que os utilizadores possam selecionar uma coluna dos seus dados
  • Taxa anual, compostos por ano e anos usam number widgets com padrões e restrições
  • O operador tem uma porta de entrada que fornece dados de coluna para o parâmetro de expressão
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 utilizador para um guia abrangente de todas as propriedades, tipos de dados, widgets e opções disponíveis.

Passo 3: Criar a função Unity Catalog

Combine o esquema YAML e a função Python numa única instrução CREATE FUNCTION. A configuração YAML fica na cadeia de documentação, no início do corpo da função.

O exemplo cria a função em main.example_output. Cria primeiro o esquema se este não existir:

CREATE SCHEMA IF NOT EXISTS main.example_output

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

Passo 4: Testar a função

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

  • $1,000 a 5%, com capitalização mensal durante 10 anos, o que rende aproximadamente 1647.01
  • $1,000 à taxa de 5%, capitalizados anualmente durante 1 ano, o que rende 1050.00
  • 1 000 $ a uma taxa de 15%, com capitalização mensal durante 1 ano, o que rende aproximadamente 1160.75
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);

Passo 5: Registar o operador

Adicione o operador ao seu .user_defined_operators.yaml ficheiro:

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

Note

Se definir este ficheiro na sua pasta de utilizador, ele só aparece para si. Para mais informações, consulte Tornar o seu operador descobrável.

Passo 6: Configurar permissões

Conceda acesso a utilizadores que necessitem de usar este operador:

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

Depois de registado, o operador aparece no Lakeflow Designer com:

  • Um menu suspenso para selecionar a coluna principal dos seus dados de entrada
  • Campos numéricos para taxa, frequência de capitalização e anos (com valores predefinidos adequados)

Os utilizadores podem aplicar este operador para calcular valores futuros de colunas inteiras de dados de investimento.

  • Última atualização a