YamL-verwijzing voor door de gebruiker gedefinieerde operator

Door de gebruiker gedefinieerde operators in Lakeflow Designer worden gedefinieerd in YAML. Alle operatortypen (uc-udf, uc-udtfen python-run-function) maken gebruik van het user-defined-operator-v0.1.0 schema, waarmee configuratievelden worden gedefinieerd met behulp van de JSON-schema-indeling.

Zie Door de gebruiker gedefinieerde operators in Lakeflow Designer voor meer informatie over het bouwen van door de gebruiker gedefinieerde operators.

Hoofdeigenschappen

Elk YAML-operatorbestand begint met een set hoofdeigenschappen die de operator identificeren en het gedrag ervan definiëren. In het volgende voorbeeld ziet u de algemene structuur:

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'

Ports

Poorten bepalen hoe uw operator verbinding maakt met andere operators in de pijplijn. Het ports object bevat input en output matrices.

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

Alleen de gedocumenteerde poorteigenschappen worden geaccepteerd. Onbekende sleutels (zoals het verouderde label veld) worden geweigerd door schemavalidatie.

Poortvoorbeelden

UDF met invoer- en uitvoerpoorten:

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

UDTF met invoer- en uitvoerpoorten:

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

python-run-function met meerdere invoer en een optionele poort:

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

Config

Het config veld is een JSON-schemaobject. U definieert elk configuratieveld als een eigenschap in het schema. Met deze indeling hebt u toegang tot standaardfuncties voor JSON-schemavalidatie, zoals enum, minimumen maximumexamples.

Het config object moet een kaart hebbentype: object.properties U kunt eventueel required (een matrix met vereiste eigenschapsnamen) en 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

Eigenschappenvelden voor configuratie

Elke eigenschap in het config.properties object ondersteunt de volgende standaard JSON-schemavelden:

Andere standaard JSON-schemavelden, zoals minLength, maxLengthen patternconst worden ook ondersteund.

Waarden opmaken

Het format veld op een configuratie-eigenschap biedt een semantische typehint die Lakeflow Designer vertelt hoe de waarde moet worden geïnterpreteerd. Deze hints maken gespecialiseerde gebruikersinterfacegedrag en -validatie mogelijk.

UI-widgets

Widgets passen aan hoe een configuratieveld wordt weergegeven in de Lakeflow Designer-interface. Definieer widgets in de x-ui eigenschap voor elke configuratie-eigenschap. Als u de widget weglaat, gebruikt Lakeflow Designer een standaardwidget op basis van het gegevenstype.

input

Invoerveld voor tekst met één regel.

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

textarea

Tekstgebied met meerdere regels voor langere inhoud. Ondersteunt een optionele rows eigenschap om de hoogte te beheren.

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

checkbox

Standaard selectievakje voor Booleaanse waarden.

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

toggle

Schakeloptie voor Booleaanse waarden in- of uitschakelen.

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

number

Numeriek invoerveld. Gebruik minimum en maximum op de eigenschap zelf om het bereik te beperken.

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

slider

Visuele schuifregelaar voor het selecteren van numerieke waarden binnen een bereik. Gebruik minimum en maximum op de eigenschap om het bereik in te stellen en step om x-ui de verhoging te beheren.

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

select

Vervolgkeuzelijst met één selectie. Hiervoor moet worden optionsSource gedefinieerd waar de vervolgkeuzelijstwaarden vandaan komen. Zie optiesbronnen.

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

multi-select

Vervolgkeuzelijst met meerdere selecties voor het kiezen van meerdere waarden. Gebruiken type: array met items: { type: string } op de eigenschap. Vereist een optionsSource. Zie optiesbronnen.

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

expression

Kolom-/expressiekiezer waarmee gebruikers een kolom kunnen kiezen uit invoergegevens of een aangepaste SQL-expressie kunnen schrijven. Stel format: expression de eigenschap in en geef de invoer port op in x-ui. Dit is handig:

• Wanneer de gebruiker een kolom in de invoergegevens moet selecteren.
• Wanneer de gebruiker mogelijk een aangepaste SQL-expressie wil schrijven.
• Voor parameters die verwijzen naar dynamische gegevens in de pijplijn.

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

Optiesbronnen

Voor select en multi-select widgets moet u definiëren waar de vervolgkeuzelijsten vandaan komen met behulp van optionsSource. Er zijn twee bronnen: static (een vaste lijst die is gedefinieerd in de YAML) en inputColumns (kolomnamen van een invoerpoort).

Statische opties

Een vaste lijst met waarden die zijn gedefinieerd in de YAML.

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

Invoerkolommen

De vervolgkeuzelijst wordt dynamisch gevuld met kolomnamen van een invoerpoort.

optionsSource:
  type: inputColumns
  port: input_data

run_function

Met de eigenschap run_function kunt u Python code rechtstreeks insluiten in de YAML-configuratie voor python-run-function-operators. Hierdoor hoeft u geen afzonderlijke Unity Catalog-functie te registreren.

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

De run() functie ontvangt drie argumenten:

• config: Een woordenlijst met configuratiewaarden die door de gebruiker in de gebruikersinterface zijn ingesteld.
• inputs: Een woordenlijst die invoerpoortnamen toe te wijzen aan DataFrames.
• spark: De actieve SparkSession.

De functie moet de uitvoerpoortnamen van een woordenlijsttoewijzing retourneren aan DataFrames. De sleutels moeten exact overeenkomen met het name veld van elke uitvoerpoort die is gedefinieerd in ports.output. Bijvoorbeeld met een uitvoerpoort met de naam out:

return {"out": result_df}

Met meerdere uitvoerpoorten:

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

environment

De eigenschap environment geeft de Python-omgeving op voor python-run-function operators. Gebruik deze om de omgevingsversie vast te maken en pip-afhankelijkheden te declareren.

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

Volledige voorbeelden

UDF op basis van UC

In dit voorbeeld wordt een op Unity Catalog gebaseerde UDF-operator gedefinieerd waarmee samengestelde rente wordt berekend.

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

In dit voorbeeld wordt een python-run-function operator gedefinieerd die klanten segmenteert met behulp van K-Means-clustering.

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'

Snelzoekgids

Vereiste hoofdeigenschappen

• schema: user-defined-operator-v0.1.0
• name: Weergavenaam
• id: Unieke id
• description: Wat de operator doet
• config: JSON-schemaobject
• type: uc-udf, uc-udtf, of python-run-function
• version: Door de auteur gedefinieerde versietekenreeks

Optionele hoofdeigenschappen

• ports: Definities van invoer- en uitvoerpoorten
• run_function: Inline Python code (alleen python-run-function)
• environment: Python omgeving en afhankelijkheden (alleen python-run-function)

Gegevenstypen van configuratie-eigenschappen

string | boolean | number | integer | array | object

UI-widgets

input | textarea | checkbox | toggle | number | slider | select | multi-select | expression

Optiesbronnen

static (vaste waarden) | inputColumns (vanaf invoerpoort)

Waarden opmaken

expression | table_source | file_source | column_expressions | sort_expressions | aggregation_expressions | ai_function_expressions | is_preview | string[]