Tutoriel : Opérateur de calcul des intérêts composés

Dans ce tutoriel, vous allez créer un opérateur Python UDF pour Lakeflow Designer qui calcule l’intérêt composé. Utilisez cet exemple pour découvrir les principes fondamentaux des opérateurs de transformation qui transforment des valeurs individuelles ou des colonnes. Pour en savoir plus, consultez Opérateurs personnalisés dans Lakeflow Designer.

Vue d’ensemble

Ce tutoriel vous guide pour créer un opérateur personnalisé à l’aide d’un UDF Python. L’opérateur calcule la valeur future d’un investissement à l’aide de la formule d’intérêt composée, A = P × (1 + r/n)^(n×t)où :

• P = Principal (montant de départ)
• r = Taux d’intérêt annuel (comme décimal)
• n = Nombre de périodes composées par année
• t = Temps en années

Requirements

• Accès à Lakeflow Designer dans un espace de travail compatible avec Unity Catalog. Voir Conditions préalables.
• USE CATALOG sur le main catalog, et CREATE SCHEMA sur main, ou USE SCHEMA et CREATE FUNCTION sur un schéma existant main.example_output. Pour utiliser un catalogue ou un schéma différent, remplacez main.example_output partout. Consultez les informations de référence sur les privilèges du catalogue Unity.
• Des ressources de calcul qui peuvent exécuter des UDF Python du catalogue Unity. Consultez les fonctions définies par l’utilisateur SQL et Python dans Unity Catalog.

Step 1 : Écrire et tester la fonction Python

Tout d’abord, définissez la fonction de base Python qui effectue le calcul. Testez-le dans une cellule de bloc-notes pour vous assurer qu’il fonctionne correctement.

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)

Testez la fonction avec un investissement d’exemple : 1 000 $ à un taux annuel de 5%, composé mensuel pendant 10 ans. Le résultat devrait être approximativement 1647.01.

compound_amount(1000, 0.05, 12, 10)

Étape 2 : Créer le YAML pour l’opérateur

La configuration YAML définit la façon dont l’opérateur apparaît dans Lakeflow Designer. Pour cet opérateur :

• Principal utilise un expression widget afin que les utilisateurs puissent sélectionner une colonne à partir de leurs données
• Taux annuel, Composés par année et Années utilisent number des widgets avec des valeurs par défaut et des contraintes
• L’opérateur a un port d’entrée qui fournit des données de colonne pour le paramètre d’expression

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

Pour toutes les propriétés, types de données, widgets et options disponibles, voir référence YAML de l’opérateur personnalisé.

Étape 3 : Créer la fonction Catalogue Unity

Combinez le schéma YAML et la fonction Python en une seule instruction CREATE FUNCTION. La configuration YAML se place dans la docstring au début du corps de la fonction.

L’exemple crée la fonction dans main.example_output. Créez d’abord le schéma s’il n’existe pas :

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

Étape 4 : Tester la fonction

Testez directement la fonction UC avec SQL. Ces requêtes vérifient trois scénarios :

• 1 000 $ à un taux de 5 % capitalisé mensuellement pendant 10 ans, ce qui donne environ 1647.01
• 1 000 $ à 5 % capitalisés annuellement pendant 1 an, ce qui rapporte 1050.00
• 1 000 $ à 15 % capitalisés mensuellement pendant 1 an, ce qui donne environ 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);

Étape 5 : Inscrire l’opérateur

Ajoutez l’opérateur au fichier .custom_operators.yaml :

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

Étape 6 : Configurer les autorisations

Accordez l’accès aux utilisateurs qui doivent utiliser cet opérateur :

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

Étape 7 : Utilisez l’opérateur dans Lakeflow Designer

1. Dans une préparation visuelle des données, ouvrez le menu Opérateurs dans le panneau de gauche et trouvez l’opérateur Montant composé.
2. Faites glisser l’opérateur sur la toile et y connectez une entrée.
3. Double-cliquez sur l’opérateur pour ouvrir son panneau de configuration, puis définissez ses champs.
4. Sélectionnez l’opérateur pour prévisualiser ses résultats dans le panneau de sortie.

Le panneau de configuration de l’opérateur comprend :

• Liste déroulante pour sélectionner la colonne principale dans vos données d’entrée
• Nombre d’entrées pour le taux, la fréquence composée et les années (avec des valeurs par défaut sensibles)

Les utilisateurs peuvent appliquer cet opérateur pour calculer les valeurs futures pour les colonnes entières des données d’investissement.

Ressources supplémentaires

• Opérateurs personnalisés dans Lakeflow Designer
• Écrire la logique pour les opérateurs personnalisés Lakeflow Designer
• Référence YAML d’opérateur personnalisé