Dokumentacja języka YAML operatora zdefiniowanego przez użytkownika

Ważna

Ta funkcja jest dostępna w publicznej wersji testowej.

Na tej stronie opisano konfigurację YAML dla operatorów zdefiniowanych przez użytkownika w programie Lakeflow Designer. Wszystkie typy operatorów (uc-udf, uc-udtfi python-run-function) używają schematu user-defined-operator-v0.1.0 , który definiuje pola konfiguracji przy użyciu formatu schematu JSON.

Aby uzyskać informacje o sposobie tworzenia operatorów zdefiniowanych przez użytkownika, zobacz Operatory zdefiniowane przez użytkownika w programie Lakeflow Designer.

Właściwości katalogu głównego

Każdy plik YAML operatora rozpoczyna się od zestawu właściwości głównych, które identyfikują operator i definiują jego zachowanie. W poniższym przykładzie przedstawiono ogólną strukturę:

schema: user-defined-operator-v0.1.0
type: python-run-function
name: My Operator
id: my_operator
version: '1.0.0'
description: >
  What this operator does.
  Can be multiple lines.
config:
  type: object
  properties:
    my_field:
      type: string
      title: My Field
      description: Help text
ports:
  input:
    - name: data
      title: Input Data
  output:
    - name: out
      title: Output
run_function:
  type: inline
  code: |
    def run(config, inputs, spark):
        return {"out": inputs["data"]}
environment:
  environment_version: '4'
  dependencies:
    - 'pandas>=2.0'

Majątek	Typ	Wymagane	Description
`schema`	ciąg	Yes	Identyfikator schematu. Musi mieć wartość `user-defined-operator-v0.1.0`.
`type`	ciąg	Yes	Typ operatora: `uc-udf`, lub `uc-udtfpython-run-function`.
`name`	ciąg	Yes	Nazwa wyświetlana operatora. Zachowaj krótki rozmiar, aby dopasować interfejs użytkownika projektanta lakeflow. Minimalna długość 1 znaków.
`id`	ciąg	Yes	Unikatowy identyfikator typu operatora. Minimalna długość 1 znaków. Rozważ użycie przestrzeni nazw (takich jak `finance.` lub `ml.`) do kategoryzowania operatorów.
`description`	ciąg	Yes	Szczegółowy opis tego, co robi operator. Wyświetlane użytkownikom w interfejsie użytkownika. Aby uzyskać dłuższe opisy, użyj składni wielowierszowej YAML (`>`).
`config`	obiekt	Yes	Obiekt schematu JSON definiujący pola konfiguracji. Zobacz Konfiguracja.
`ports`	obiekt	No	Definicje portów wejściowych i wyjściowych. Zobacz Porty.
`version`	ciąg	Yes	Ciąg wersji (na przykład `"1.0.0"`). Służy do śledzenia własnych wydań operatorów.
`run_function`	obiekt	No	Wbudowany kod Python dla operatorów `python-run-function`. Zobacz: `run_function`.
`environment`	obiekt	No	Python konfiguracji środowiska, w tym zależności. Zobacz: `environment`.

Porty

Porty definiują sposób łączenia operatora z innymi operatorami w potoku. Obiekt ports zawiera input tablice i output .

ports:
  input:
    - name: input_data
      title: Input Data
      mime: application/vnd.databricks.dataframe
      allowMultiple: true
      required: true
  output:
    - name: out
      title: Output

Majątek	Typ	Wymagane	Description
`name`	ciąg	Yes	Unikatowy identyfikator portu. Używane w połączeniach i odwołaniach konfiguracji.
`title`	ciąg	No	Czytelna dla człowieka etykieta wyświetlana w interfejsie użytkownika.
`mime`	ciąg	No	Typ MIME dla danych portów. Na przykład `application/vnd.databricks.dataframe`.
`allowMultiple`	boolean	No	Jeśli `true`port akceptuje wiele połączeń przychodzących.
`required`	boolean	No	Jeśli `false`port jest opcjonalny. Wartość domyślna: `true`.

Akceptowane są tylko udokumentowane właściwości portu. Nieznane klucze (takie jak starsze label pole) są odrzucane przez walidację schematu.

Przykłady portów

UDF z portami wejściowymi i wyjściowymi:

ports:
  input:
    - name: in
      title: Input Data
  output:
    - name: out
      title: Output

UdTF z portami wejściowymi i wyjściowymi:

ports:
  input:
    - name: input_data
      title: Input Data
  output:
    - name: clustered_data
      title: Clustered Results

python-run-function z wieloma danymi wejściowymi i opcjonalnym portem:

ports:
  input:
    - name: main_data
      title: Main Data
    - name: reference_data
      title: Reference Table
      required: false
  output:
    - name: joined_output
      title: Joined Output

Config

Pole config jest obiektem schematu JSON. Każde pole konfiguracji definiuje się jako właściwość w schemacie. Ten format zapewnia dostęp do standardowych funkcji weryfikacji schematu JSON, takich jak enum, minimum, maximumi examples.

Obiekt config musi mieć type: object mapę i properties . Opcjonalnie można uwzględnić required (tablicę wymaganych nazw właściwości) i additionalProperties.

config:
  type: object
  properties:
    cluster_count:
      type: number
      title: Number of Clusters
      description: How many clusters to create
      default: 3
      minimum: 1
      maximum: 100
    algorithm:
      type: string
      title: Algorithm
      description: Clustering algorithm to use
      enum: ['kmeans', 'dbscan', 'hierarchical']
      default: kmeans
    feature_col:
      type: string
      title: Feature Column
      description: Column to use as input
      format: expression
      x-ui:
        widget: expression
        port: data
  required: [cluster_count, feature_col]
  additionalProperties: false

Pola właściwości konfiguracji

Każda właściwość w config.properties obiekcie obsługuje następujące standardowe pola schematu JSON:

Pole	Typ	Description
`type`	ciąg	Typ danych: `string`, , `integernumber`, `boolean`, `array`lub `object`.
`title`	ciąg	Czytelna dla człowieka etykieta wyświetlana w interfejsie użytkownika.
`description`	ciąg	Tekst pomocy wyświetlany użytkownikom.
`default`	any	Wartość domyślna pola.
`examples`	macierz	Przykładowe wartości pola.
`enum`	macierz	Naprawiono listę dozwolonych wartości.
`format`	ciąg	Wskazówka typu semantycznego. Zobacz Formatowanie wartości.
`minimum`	number	Minimalna dozwolona wartość (dla `number` typów i `integer` ).
`maximum`	number	Maksymalna dozwolona wartość (dla `number` typów i `integer` ).
`items`	obiekt	Schemat dla elementów tablicy (gdy `type` ma wartość `array`).
`properties`	obiekt	Zagnieżdżone definicje właściwości (gdy `type` ma wartość `object`).
`required`	macierz	Lista wymaganych zagnieżdżonych nazw właściwości (gdy `type` ma wartość `object`).

Obsługiwane są również inne standardowe pola schematu JSON, takie jak minLength, maxLength, patterni const .

Formatowanie wartości

Pole format we właściwości konfiguracji zawiera semantyczną wskazówkę typu, która informuje projektanta Lakeflow, jak interpretować wartość. Te wskazówki umożliwiają specjalne zachowanie i walidację interfejsu użytkownika.

Format	Description
`expression`	Odwołanie do kolumny lub wyrażenie SQL.
`table_source`	Odwołanie do źródła tabeli.
`file_source`	Dokumentacja źródła pliku.
`column_expressions`	Wyrażenia kolumn.
`sort_expressions`	Sortuj wyrażenia.
`aggregation_expressions`	Wyrażenia agregacji.
`ai_function_expressions`	Wyrażenia funkcji sztucznej inteligencji.
`is_preview`	Flaga trybu automatycznego podglądu. Program Lakeflow Designer ustawia tę wartość na `true` podczas podglądu przepływu pracy. Nazwa właściwości konfiguracji jest dowolna — ma znaczenie tylko `format: is_preview` tag. Użyj tej funkcji, aby pominąć efekty uboczne, takie jak zewnętrzne wywołania interfejsu API podczas korzystania z wersji zapoznawczej.
`string[]`	Tablica ciągów.

Widżety interfejsu użytkownika

Widżety dostosowują sposób renderowania pola konfiguracji w interfejsie projektanta lakeflow. Zdefiniuj x-ui widżety we właściwości dla każdej właściwości konfiguracji. Jeśli pominięto widżet, projektant lakeflow używa domyślnego widżetu na podstawie typu danych.

Widget	Typ danych	Description
`input`	ciąg	Wprowadzanie tekstu jednowierszowego.
`textarea`	ciąg	Obszar tekstu wielowierszowego. Obsługuje właściwość opcjonalną `rows` .
`checkbox`	boolean	Standardowe pole wyboru.
`toggle`	boolean	Przełącznik.
`number`	liczba/liczba całkowita	Dane wejściowe liczbowe z opcjonalnymi ograniczeniami.
`slider`	liczba/liczba całkowita	Suwak wizualny dla zakresów liczbowych. Obsługuje właściwość opcjonalną `step` .
`select`	ciąg	Lista rozwijana wyboru pojedynczego. Wymaga `optionsSource`.
`multi-select`	macierz	Lista rozwijana wyboru wielokrotnego. Wymaga `optionsSource`.
`expression`	ciąg	Selektor kolumn/wyrażeń. Wymaga `port`.

`input`

Jednowierszowe pole wprowadzania tekstu.

api_endpoint:
  type: string
  title: API Endpoint
  x-ui:
    widget: input

`textarea`

Obszar tekstowy wielowierszowy dla dłuższej zawartości. Obsługuje opcjonalną rows właściwość do kontrolowania wysokości.

message_body:
  type: string
  title: Message Body
  x-ui:
    widget: textarea
    rows: 4

`checkbox`

Standardowe pole wyboru wartości logicznych.

send_notification:
  type: boolean
  title: Send Notification
  default: false
  x-ui:
    widget: checkbox

`toggle`

Przełącz przełącznik dla wartości logicznych.

enable_logging:
  type: boolean
  title: Enable Logging
  default: true
  x-ui:
    widget: toggle

`number`

Pole wejściowe liczbowe. Użyj minimum właściwości i maximum dla samej właściwości, aby ograniczyć zakres.

num_clusters:
  type: number
  title: Number of Clusters
  default: 3
  minimum: 1
  maximum: 100
  x-ui:
    widget: number

`slider`

Suwak wizualny do wybierania wartości liczbowych w zakresie. Użyj i maximumminimum we właściwości , aby ustawić zakres i step w x-ui , aby kontrolować przyrost.

confidence_threshold:
  type: number
  title: Confidence Threshold
  default: 0.8
  minimum: 0
  maximum: 1
  x-ui:
    widget: slider
    step: 0.05

`select`

Lista rozwijana wyboru pojedynczego. Wymaga elementu optionsSource do zdefiniowania lokalizacji, z której pochodzą wartości listy rozwijanej. Zobacz Źródła opcji.

aggregation_type:
  type: string
  title: Aggregation Type
  x-ui:
    widget: select
    optionsSource:
      type: static
      values: ['sum', 'avg', 'min', 'max', 'count']

`multi-select`

Lista rozwijana wielokrotnego wyboru do wybierania wielu wartości. Użyj polecenia type: array z items: { type: string } właściwością . Wymaga elementu optionsSource. Zobacz Źródła opcji.

feature_columns:
  type: array
  title: Feature Columns
  items:
    type: string
  x-ui:
    widget: multi-select
    optionsSource:
      type: inputColumns
      port: input_data

`expression`

Selektor kolumn/wyrażeń, który umożliwia użytkownikom wybranie kolumny z danych wejściowych lub zapisanie niestandardowego wyrażenia SQL. Ustaw format: expression właściwość i określ dane wejściowe port w pliku x-ui. Jest to przydatne:

Gdy użytkownik powinien wybrać kolumnę z danych wejściowych.
Gdy użytkownik może chcieć napisać niestandardowe wyrażenie SQL.
W przypadku parametrów odwołujących się do danych dynamicznych w potoku.

amount:
  type: string
  title: Amount
  format: expression
  x-ui:
    widget: expression
    port: input_data

Źródła opcji

W przypadku select elementów i multi-select widżetów należy zdefiniować, skąd pochodzą opcje listy rozwijanej przy użyciu polecenia optionsSource.

Opcje statyczne

Stała lista wartości zdefiniowanych w yaML.

optionsSource:
  type: static
  values: ['option1', 'option2', 'option3']

Majątek	Typ	Wymagane	Description
`type`	ciąg	Yes	Musi mieć wartość `static`.
`values`	macierz	Yes	Tablica wartości ciągów dla listy rozwijanej.

Kolumny wejściowe

Dynamicznie wypełnia listę rozwijaną nazwami kolumn z portu wejściowego.

optionsSource:
  type: inputColumns
  port: input_data

Majątek	Typ	Wymagane	Description
`type`	ciąg	Yes	Musi mieć wartość `inputColumns`.
`port`	ciąg	Yes	Nazwa portu wejściowego do pobrania nazw kolumn. Musi odpowiadać `name` jednemu ze zdefiniowanych portów wejściowych.

`run_function`

Właściwość run_function umożliwia osadzanie kodu Python bezpośrednio w konfiguracji YAML dla operatorów python-run-function. Eliminuje to konieczność zarejestrowania oddzielnej funkcji wykazu aparatu Unity.

run_function:
  type: inline
  code: |
    def run(config, inputs, spark):
        df = inputs["data"]
        threshold = config["threshold"]
        return {"out": df.filter(df["score"] > threshold)}

Majątek	Typ	Wymagane	Description
`type`	ciąg	Yes	Musi mieć wartość `inline`.
`code`	ciąg	Yes	Python kodu źródłowego. Musi zdefiniować `run()` funkcję.

Funkcja run() otrzymuje trzy argumenty:

config: słownik wartości konfiguracji ustawionych przez użytkownika w interfejsie użytkownika.
inputs: słownik mapuje nazwy portów wejściowych na ramki danych.
spark: aktywna platforma SparkSession.

Funkcja musi zwrócić nazwy portów wyjściowych mapowania słownika na ramki danych. Klucze muszą dokładnie odpowiadać name polu każdego portu wyjściowego zdefiniowanego w pliku ports.output. Na przykład z portem wyjściowym o nazwie out:

return {"out": result_df}

Z wieloma portami wyjściowymi:

return {"match": match_df, "rest": rest_df}

`environment`

Właściwość environment określa środowisko Python dla operatorów python-run-function. Służy do przypinania wersji środowiska i deklarowania zależności pip.

environment:
  environment_version: '4'
  dependencies:
    - 'scikit-learn>=1.3'
    - 'pandas>=2.0'

Majątek	Typ	Wymagane	Description
`environment_version`	ciąg	No	Wersja środowiska do użycia. Na przykład `"4"`.
`dependencies`	tablica ciągów	No	Lista specyfikatorów zależności pip. Każdy wpis jest zgodny ze standardową składnią pip (na przykład `"pandas>=2.0"`).

Kompletne przykłady

Zdefiniowanie funkcji zdefiniowanej przez użytkownika opartej na protokole UC

W tym przykładzie zdefiniowano operator UDF oparty na wykazie aparatu Unity, który oblicza odsetki złożone.

schema: user-defined-operator-v0.1.0
type: uc-udf
name: Compound Interest
id: finance.compound_interest
version: '1.0.0'
description: >
  Calculates compound interest based on principal, rate, and time period.

config:
  type: object
  properties:
    principal:
      type: string
      title: Principal Amount
      format: expression
      x-ui:
        widget: expression
        port: input_data

    annual_rate:
      type: number
      title: Annual Interest Rate
      default: 5.0
      minimum: 0
      maximum: 100
      x-ui:
        widget: number

    years:
      type: number
      title: Number of Years
      default: 10
      minimum: 1
      maximum: 50
      x-ui:
        widget: slider
        step: 1

    compound_frequency:
      type: string
      title: Compounding Frequency
      default: 'monthly'
      x-ui:
        widget: select
        optionsSource:
          type: static
          values: ['daily', 'monthly', 'quarterly', 'annually']
  required: [principal, annual_rate]
  additionalProperties: false

ports:
  input:
    - name: input_data
      title: Input Data
  output:
    - name: out
      title: Output

operator Python run-function

W tym przykładzie zdefiniowano python-run-function operator, który segmentuje klientów przy użyciu klastrowania metodą K-Średnich.

schema: user-defined-operator-v0.1.0
type: python-run-function
name: Customer Segmentation
id: ml.customer_segmentation
version: '1.2.0'
description: >
  Segments customers into groups based on selected features
  using K-Means clustering. Returns customer IDs with their
  assigned segment numbers.

config:
  type: object
  properties:
    num_segments:
      type: integer
      title: Number of Segments
      description: How many customer segments to create
      default: 3
      minimum: 2
      maximum: 20
      x-ui:
        widget: number
    customer_id_column:
      type: string
      title: Customer ID Column
      description: Column containing customer identifiers
      x-ui:
        widget: select
        optionsSource:
          type: inputColumns
          port: customer_data
    feature_columns:
      type: array
      title: Feature Columns
      description: Columns to use for segmentation
      items:
        type: string
      x-ui:
        widget: multi-select
        optionsSource:
          type: inputColumns
          port: customer_data
    normalize_features:
      type: boolean
      title: Normalize Features
      description: Whether to normalize feature values before clustering
      default: true
      x-ui:
        widget: toggle
  required: [num_segments, customer_id_column, feature_columns]
  additionalProperties: false

ports:
  input:
    - name: customer_data
      title: Customer Data
      mime: application/vnd.databricks.dataframe
  output:
    - name: segmented_customers
      title: Segmented Customers

run_function:
  type: inline
  code: |
    def run(config, inputs, spark):
        from pyspark.ml.feature import VectorAssembler, StandardScaler
        from pyspark.ml.clustering import KMeans

        df = inputs["customer_data"]
        id_col = config["customer_id_column"]
        features = config["feature_columns"]
        k = config["num_segments"]
        normalize = config.get("normalize_features", True)

        assembler = VectorAssembler(inputCols=features, outputCol="features_vec")
        assembled = assembler.transform(df)

        if normalize:
            scaler = StandardScaler(inputCol="features_vec", outputCol="scaled_features")
            model = scaler.fit(assembled)
            assembled = model.transform(assembled)
            feature_col = "scaled_features"
        else:
            feature_col = "features_vec"

        kmeans = KMeans(k=k, featuresCol=feature_col, predictionCol="segment")
        result = kmeans.fit(assembled).transform(assembled)

        return {"segmented_customers": result.select(id_col, "segment")}

environment:
  environment_version: '4'
  dependencies:
    - 'scikit-learn>=1.3'

Krótki przewodnik

Wymagane właściwości katalogu głównego

schema: user-defined-operator-v0.1.0
name: Nazwa wyświetlana
id: Unikatowy identyfikator
description: Co robi operator
config: obiekt schematu JSON
type: uc-udf, , uc-udtflub python-run-function
version: Ciąg wersji zdefiniowanej przez autora

Opcjonalne właściwości katalogu głównego

ports: Definicje portów wejściowych i wyjściowych
run_function: wbudowany kod Python (tylko python-run-function)
environment: środowisko Python i zależności (tylko python-run-function)

Konfigurowanie typów danych właściwości

Widżety interfejsu użytkownika

Źródła opcji

static (stałe wartości) | inputColumns (z portu wejściowego)

Formatowanie wartości

Opinia

Czy ta strona była pomocna?

Last updated on 2026-06-01

Dokumentacja języka YAML operatora zdefiniowanego przez użytkownika

Właściwości katalogu głównego

Porty

Przykłady portów

Config

Pola właściwości konfiguracji

Formatowanie wartości

Widżety interfejsu użytkownika

input

textarea

checkbox

toggle

number

slider

select

multi-select

expression

Źródła opcji

Opcje statyczne

Kolumny wejściowe

run_function

environment

Kompletne przykłady

Zdefiniowanie funkcji zdefiniowanej przez użytkownika opartej na protokole UC

operator Python run-function

Krótki przewodnik

Wymagane właściwości katalogu głównego

Opcjonalne właściwości katalogu głównego

Konfigurowanie typów danych właściwości

Widżety interfejsu użytkownika

Źródła opcji

Formatowanie wartości

Opinia

Dodatkowe zasoby

`input`

`textarea`

`checkbox`

`toggle`

`number`

`slider`

`select`

`multi-select`

`expression`

`run_function`

`environment`