Tutorial: Operador de calculadora de juros compostos

Importante

Esse recurso está em Visualização Pública.

Este tutorial explica como criar um operador UDF Python para o Lakeflow Designer que calcula os juros compostos. Use este exemplo para aprender os conceitos básicos 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 explica como criar 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 composta, A = P × (1 + r/n)^(n×t)em que:

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

Step 1: gravar e testar a função Python

Primeiro, defina a função de Python principal que executa o cálculo. Teste-o em uma célula do notebook para garantir que ele funcione 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)

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

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

Etapa 2: Criar o YAML para o operador

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

Principal usa um widget expression para que os usuários selecionem uma coluna dos seus dados
Taxa anual, Capitalizações por ano e Anos usam number controles com valores padrão 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 usuário para obter um guia abrangente sobre todas as propriedades, tipos de dados, widgets e opções disponíveis.

Etapa 3: Criar a função catálogo do Unity

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

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

Etapa 4: Testar a função

Teste a função UC diretamente com o 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

Etapa 5: Registrar o operador

Adicione o operador ao seu .user_defined_operators.yaml arquivo:

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

Note

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

Etapa 6: Configurar permissões

Conceda acesso aos usuários que precisam usar este operador:

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

Usando o operador no Lakeflow Designer

Depois de registrado, o operador aparecerá no Lakeflow Designer com:

Uma lista suspensa para selecionar a coluna principal de seus dados de entrada
Campos numéricos para taxa, frequência de capitalização e anos (com valores padrão adequados)

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

Comentários

Esta página foi útil?

Last updated on 2026-06-01