Tutorial: demo di tutti i widget dell'interfaccia utente

Importante

Questa funzionalità è in Anteprima Pubblica.

Questa esercitazione di riferimento crea un operatore UDF Python per Lakeflow Designer che esercita ogni widget dell'interfaccia utente disponibile nello schema user-defined-operator-v0.1.0. Usalo come modello quando crei i tuoi operatori personalizzati. Per una panoramica più ampia, vedere Operatori definiti dall'utente in Lakeflow Designer.

Informazioni generali

Questo operatore è una funzione definita dall'utente dimostrativa che accetta parametri usando ogni tipo di widget dell'interfaccia utente disponibile. Concatena tutti i valori di input in una stringa descrittiva, rendendo più semplice vedere come ogni widget passa i dati alla funzione.

I tipi di widget disponibili sono:

Widget Description Tipo di dati
expression Selezione colonna/espressione dalla porta di input expression
input Input di testo a riga singola string
textarea Area di testo a più righe string
checkbox Attiva/disattiva casella di controllo Boolean
toggle Interruttore a levetta Boolean
number Campo numerico con valori minimo/massimo number
slider Dispositivo di scorrimento numerico con intervallo number
select Elenco a discesa a selezione singola (valori statici) string
select Menu a discesa a selezione singola (dalle colonne di immissione) string
multi-select Selezione multipla (valori statici) string[]
multi-select Selezione multipla (dalle colonne di input) string[]

P 1: Scrivere e testare la funzione Python

Definire prima di tutto la funzione Python che accetta tutti i diversi tipi di parametro. Questa funzione concatena semplicemente tutti gli input in una stringa descrittiva a scopo dimostrativo.

def concat_all_widgets(
    # expression widget - column value from input
    expr_value: str,
    # input widget - single line text
    text_input: str,
    # textarea widget - multi line text
    text_area: str,
    # checkbox widget - boolean
    checkbox_flag: bool,
    # toggle widget - boolean
    toggle_flag: bool,
    # number widget - numeric input
    number_value: float,
    # slider widget - numeric slider
    slider_value: float,
    # select widget with static options
    select_static: str,
    # select widget with inputColumns options
    select_column: str,
    # multi-select widget with static options (array of strings)
    multi_select_static: list,
    # multi-select widget with inputColumns options (array of strings)
    multi_select_columns: list
) -> str:
    """
    Concatenates all input parameters into a descriptive string.
    This demonstrates all UI widget types available in user-defined operators.
    """
    lines = [
        f"1: Expression (Column Picker) -> {expr_value}",
        f"2: Text Input (Single Line) -> {text_input}",
        f"3: Text Area (Multi-Line) -> {text_area}",
        f"4: Checkbox Option -> {checkbox_flag}",
        f"5: Toggle Switch -> {toggle_flag}",
        f"6: Number Input -> {number_value}",
        f"7: Slider Value -> {slider_value}",
        f"8: Select (Static Options) -> {select_static}",
        f"9: Select (From Input Columns) -> {select_column}",
        f"10: Multi-Select (Static Options) -> [{', '.join(multi_select_static or [])}]",
        f"11: Multi-Select (From Input Columns) -> [{', '.join(multi_select_columns or [])}]"
    ]
    return "\n".join(lines)

Testare la funzione con il codice seguente:

result = concat_all_widgets(
    expr_value="column_value_123",
    text_input="Hello World",
    text_area="Line 1\nLine 2\nLine 3",
    checkbox_flag=True,
    toggle_flag=False,
    number_value=42.5,
    slider_value=75.0,
    select_static="option_b",
    select_column="amount",
    multi_select_static=["tag1", "tag3"],
    multi_select_columns=["col1", "col3"]
)
print(result)

Passaggio 2: Creare la configurazione YAML

La configurazione YAML definisce la modalità di visualizzazione dell'operatore in Lakeflow Designer. Questo esempio illustra ogni tipo di widget disponibile:

schema: user-defined-operator-v0.1.0
type: uc-udf
name: All Widgets Demo
id: demo.all_widgets
version: '1.0.0'
description: >
  A demonstration UDF that showcases all available UI widgets.
config:
  type: object
  properties:
    # ============================================
    # EXPRESSION WIDGET
    # ============================================
    expr_value:
      type: string
      format: expression
      title: 1. Expression (Column Picker)
      examples:
        - 'Select a column or enter an expression'
      x-ui:
        widget: expression
        port: in

    # ============================================
    # INPUT WIDGET (single-line text)
    # ============================================
    text_input:
      type: string
      title: 2. Text Input (Single Line)
      default: default text
      examples:
        - 'Enter a single line of text'
      x-ui:
        widget: input

    # ============================================
    # TEXTAREA WIDGET (multi-line text)
    # ============================================
    text_area:
      type: string
      title: 3. Text Area (Multi-Line)
      default: Sample text
      examples:
        - 'Enter multiple lines of text here...'
      x-ui:
        widget: textarea
        rows: 3

    # ============================================
    # CHECKBOX WIDGET (boolean)
    # ============================================
    checkbox_flag:
      type: boolean
      title: 4. Checkbox Option
      default: true
      x-ui:
        widget: checkbox

    # ============================================
    # TOGGLE WIDGET (boolean switch)
    # ============================================
    toggle_flag:
      type: boolean
      title: 5. Toggle Switch
      default: false
      x-ui:
        widget: toggle

    # ============================================
    # NUMBER WIDGET (numeric input with min/max)
    # ============================================
    number_value:
      type: number
      title: 6. Number Input
      default: 50
      minimum: 0
      maximum: 100
      examples:
        - 'Enter a number (0-100)'
      x-ui:
        widget: number

    # ============================================
    # SLIDER WIDGET (numeric slider)
    # ============================================
    slider_value:
      type: number
      title: 7. Slider Value
      default: 50
      minimum: 0
      maximum: 100
      x-ui:
        widget: slider
        step: 5

    # ============================================
    # SELECT WIDGET with STATIC options
    # ============================================
    select_static:
      type: string
      title: 8. Select (Static Options)
      default: option_a
      examples:
        - 'Choose an option'
      x-ui:
        widget: select
        optionsSource:
          type: static
          values:
            - option_a
            - option_b
            - option_c

    # ============================================
    # SELECT WIDGET with INPUT COLUMNS options
    # ============================================
    select_column:
      type: string
      title: 9. Select (From Input Columns)
      examples:
        - 'Select a column from input'
      x-ui:
        widget: select
        optionsSource:
          type: inputColumns
          port: in

    # ============================================
    # MULTI-SELECT WIDGET with STATIC options
    # ============================================
    multi_select_static:
      type: array
      items:
        type: string
      title: 10. Multi-Select (Static Options)
      default:
        - tag1
        - tag2
      examples:
        - 'Select one or more tags'
      x-ui:
        widget: multi-select
        optionsSource:
          type: static
          values:
            - tag1
            - tag2
            - tag3
            - tag4
            - tag5

    # ============================================
    # MULTI-SELECT WIDGET with INPUT COLUMNS options
    # ============================================
    multi_select_columns:
      type: array
      items:
        type: string
      title: 11. Multi-Select (From Input Columns)
      examples:
        - 'Select one or more columns'
      x-ui:
        widget: multi-select
        optionsSource:
          type: inputColumns
          port: in

  required:
    - expr_value
  additionalProperties: false
ports:
  input:
    - name: in
      title: Input Data
  output:
    - name: out
      title: Output

Evidenziazioni dello schema

Chiave di configurazione Widget Tipo di dati Purpose
expr_value expression expression Selezionare una colonna o un'espressione dai dati di input.
text_input input string Campo di testo a riga singola.
text_area textarea string Immissione di testo a più righe.
checkbox_flag checkbox Boolean Casella di controllo Boolean.
toggle_flag toggle Boolean Interruttore di attivazione/disattivazione booleano.
number_value number number Campo numerico con valori minimo/massimo.
slider_value slider number Cursore numerico con incrementi a intervalli.
select_static select string Menu a discesa con opzioni codificate in modo statico.
select_column select string Elenco a discesa popolato dalle colonne di input.
multi_select_static multi-select string[] Selezione multipla con opzioni codificate.
multi_select_columns multi-select string[] Selezione multipla popolata dalle colonne di input.

Tipi di origine delle opzioni

Per i widget select e multi-select, è necessario specificare un optionsSource:

Opzioni statiche - Elenco fisso di valori:

optionsSource:
  type: static
  values:
    - value1
    - value2
    - value3

Colonne di input : elenco dinamico dalle colonne delle porte di input:

optionsSource:
  type: inputColumns
  port: in

Per una guida completa a tutte le proprietà, i tipi di dati, i widget e le opzioni disponibili, consulta il riferimento YAML dell'operatore definito dall'utente.

Passaggio 3: Creare la funzione Catalogo Unity

Combinare la configurazione YAML e la funzione Python in una singola istruzione CREATE FUNCTION. Si noti che i valori string[] (selezione multipla) vengono passati come ARRAY<STRING> alla UDF.

CREATE OR REPLACE FUNCTION main.my_schema.all_widgets_demo(
    expr_value STRING,
    text_input STRING,
    text_area STRING,
    checkbox_flag BOOLEAN,
    toggle_flag BOOLEAN,
    number_value DOUBLE,
    slider_value DOUBLE,
    select_static STRING,
    select_column STRING,
    multi_select_static ARRAY<STRING>,
    multi_select_columns ARRAY<STRING>
)
RETURNS STRING
LANGUAGE PYTHON
AS $$
  """
  schema: user-defined-operator-v0.1.0
  type: uc-udf
  name: All Widgets Demo
  id: demo.all_widgets
  version: "1.0.0"
  description: >
    A demonstration UDF that showcases all available UI widgets.
  config:
    type: object
    properties:
      expr_value:
        type: string
        format: expression
        title: 1. Expression (Column Picker)
        examples:
          - "Select a column or enter an expression"
        x-ui:
          widget: expression
          port: in
      text_input:
        type: string
        title: 2. Text Input (Single Line)
        default: "default text"
        examples:
          - "Enter a single line of text"
        x-ui:
          widget: input
      text_area:
        type: string
        title: 3. Text Area (Multi-Line)
        default: Sample text
        examples:
          - "Enter multiple lines of text here..."
        x-ui:
          widget: textarea
          rows: 3
      checkbox_flag:
        type: boolean
        title: 4. Checkbox Option
        default: true
        x-ui:
          widget: checkbox
      toggle_flag:
        type: boolean
        title: 5. Toggle Switch
        default: false
        x-ui:
          widget: toggle
      number_value:
        type: number
        title: 6. Number Input
        default: 50
        minimum: 0
        maximum: 100
        examples:
          - "Enter a number (0-100)"
        x-ui:
          widget: number
      slider_value:
        type: number
        title: 7. Slider Value
        default: 50
        minimum: 0
        maximum: 100
        x-ui:
          widget: slider
          step: 5
      select_static:
        type: string
        title: 8. Select (Static Options)
        default: option_a
        examples:
          - "Choose an option"
        x-ui:
          widget: select
          optionsSource:
            type: static
            values:
              - option_a
              - option_b
              - option_c
      select_column:
        type: string
        title: 9. Select (From Input Columns)
        examples:
          - "Select a column from input"
        x-ui:
          widget: select
          optionsSource:
            type: inputColumns
            port: in
      multi_select_static:
        type: array
        items:
          type: string
        title: 10. Multi-Select (Static Options)
        default:
          - tag1
          - tag2
        examples:
          - "Select one or more tags"
        x-ui:
          widget: multi-select
          optionsSource:
            type: static
            values:
              - tag1
              - tag2
              - tag3
              - tag4
              - tag5
      multi_select_columns:
        type: array
        items:
          type: string
        title: 11. Multi-Select (From Input Columns)
        examples:
          - "Select one or more columns"
        x-ui:
          widget: multi-select
          optionsSource:
            type: inputColumns
            port: in
    required:
      - expr_value
    additionalProperties: false
  ports:
    input:
      - name: in
        title: Input Data
    output:
      - name: out
        title: Output
  """

  def concat_all_widgets(
      expr_value: str,
      text_input: str,
      text_area: str,
      checkbox_flag: bool,
      toggle_flag: bool,
      number_value: float,
      slider_value: float,
      select_static: str,
      select_column: str,
      multi_select_static: list,
      multi_select_columns: list
  ) -> str:
      lines = [
          f"1: Expression (Column Picker) -> {expr_value}",
          f"2: Text Input (Single Line) -> {text_input}",
          f"3: Text Area (Multi-Line) -> {text_area}",
          f"4: Checkbox Option -> {checkbox_flag}",
          f"5: Toggle Switch -> {toggle_flag}",
          f"6: Number Input -> {number_value}",
          f"7: Slider Value -> {slider_value}",
          f"8: Select (Static Options) -> {select_static}",
          f"9: Select (From Input Columns) -> {select_column}",
          f"10: Multi-Select (Static Options) -> [{', '.join(multi_select_static or [])}]",
          f"11: Multi-Select (From Input Columns) -> [{', '.join(multi_select_columns or [])}]"
      ]
      return "\n".join(lines)

  return concat_all_widgets(
      expr_value,
      text_input,
      text_area,
      checkbox_flag,
      toggle_flag,
      number_value,
      slider_value,
      select_static,
      select_column,
      multi_select_static,
      multi_select_columns
  )
$$

Passaggio 4: Testare la funzione

Testare la funzione UC direttamente con SQL:

SELECT main.my_schema.all_widgets_demo(
    'my_column_value',             -- expr_value (expression)
    'Hello World',                 -- text_input (input)
    'Multi\nLine\nText',           -- text_area (textarea)
    TRUE,                          -- checkbox_flag (checkbox)
    FALSE,                         -- toggle_flag (toggle)
    42.5,                          -- number_value (number)
    75.0,                          -- slider_value (slider)
    'option_b',                    -- select_static (select with static)
    'amount',                      -- select_column (select with inputColumns)
    array('tag1', 'tag3'),         -- multi_select_static (multi-select with static)
    array('col1', 'col2', 'col3')  -- multi_select_columns (multi-select with inputColumns)
) AS result;

Passaggio 5: Registrare l'operatore

Aggiungi l'operatore nel file .user_defined_operators.yaml:

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

Passaggio 6: Configurare le autorizzazioni

Concedere l'accesso agli utenti che devono usare questo operatore:

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

Utilizzo dell'operatore in Lakeflow Designer

Dopo la registrazione, l'operatore verrà visualizzato in Lakeflow Designer con un pannello di configurazione completo con:

  • Selettore di espressioni per la selezione delle colonne
  • Input di testo (riga singola e multilinea)
  • Controlli booleani (casella di controllo e interruttore)
  • Input numerici (campo numerico e dispositivo di scorrimento)
  • Elenchi a discesa con opzioni statiche e dinamiche
  • Controlli a selezione multipla per la scelta di più valori

Questo operatore funge da riferimento utile per comprendere come ogni tipo di widget esegue il rendering e passa i dati alla funzione.

Riepilogo dei riferimenti dei widget

Widget Tipo di dati Opzioni dell'interfaccia utente
expression expression port (obbligatorio), placeholder
input string placeholder
textarea string rows, placeholder
checkbox boolean placeholder
toggle boolean placeholder
number number min, max, placeholder
slider number min, max, stepplaceholder
select string optionsSource (obbligatorio), placeholder
multi-select string[] optionsSource (obbligatorio), placeholder
  • Last updated on