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

Tutorial: Operador da calculadora de juros compostos

info

Visualização

Este recurso está em Pré-visualização Pública.

Este tutorial demonstra como criar um operador UDF Python para LakeFlow Designer que calcula juros compostos. Use este exemplo para aprender os fundamentos da criação de operadores que transformam valores ou colunas individuais. Para saber mais, consulte Operadores definidos pelo usuário no 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)

Você pode testar a função com o seguinte código:

Python
# $1,000 invested at 5% annual rate, compounded monthly for 10 years
compound_amount(1000, 0.05, 12, 10)
# Expected result: ~1647.01

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.

SQL
CREATE OR REPLACE FUNCTION main.my_schema.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:

SQL
-- Test 1: $1,000 at 5% compounded monthly for 10 years
SELECT main.my_schema.compound_amount(1000, 0.05, 12, 10)
-- Expected: ~1647.01

-- Test 2: $1,000 at 5% compounded annually for 1 year
SELECT main.my_schema.compound_amount(1000, 0.05, 1, 1)
-- Expected: 1050.00

-- Test 3: $1,000 at 15% compounded monthly for 1 year
SELECT main.my_schema.compound_amount(1000, 0.15, 12, 1)
-- Expected: ~1160.75

o passo 5: registrar a operadora​

Adicione o operador ao seu arquivo .user_defined_operators.yaml :

YAML
operators:
  - catalog: main
    schema: my_schema
    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.my_schema TO `<user>`;
GRANT EXECUTE ON FUNCTION main.my_schema.compound_amount TO `<user>`;

Utilizando o operador no LakeFlow Designer​

Após o registro, o operador aparecerá no LakeFlow Designer com as seguintes características:

  • 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