Schrijf logica voor door Lakeflow Designer door gebruikers gedefinieerde operatoren

De operatorlogica is de code die draait wanneer een door de gebruiker gedefinieerde operator wordt uitgevoerd. Voor een python-run-function operator is het een inline Python-run()functie. Voor een uc-udf of uc-udtf-operator is het een Unity Catalog-functie geschreven in SQL of Python.

Het schrijven van de logica is één stap in het bouwen van een gedeelde, door de gebruiker gedefinieerde operator. Nadat je de logica hebt geschreven en getest, beschrijf je de operator in YAML zodat Lakeflow Designer weet hoe hij deze in de UI moet tonen, en registreer je deze zodat hij in het Operators-paneel verschijnt. Om alle stappen samen voor één operator te zien, volg een tutorial zoals Tutorial: Compound interest calculator operator.

Schrijf een python-run-function operator

Elke python-run-function operator moet een run() functie definiëren:

def run(config: Dict[str, Any], inputs: Dict[str, Any], spark) -> Dict[str, Any]:
  • config: door de gebruiker geconfigureerde waarden uit de gebruikersinterface, gesleuteld op eigenschapsnaam.
  • inputs: Invoerdataframes, gesleuteld door invoerpoort name.
  • spark: De actieve SparkSession.
  • Retourneert: Een woordenlijst die uitvoerpoortwaarden name aan DataFrames toetoewijzingt.

In het volgende voorbeeld worden rijen uit een invoerdataframe gefilterd:

def run(config, inputs, spark):
    df = inputs["in"]
    filtered = df.filter(config["filter_expression"])
    return {"out": filtered}

Om de functie te testen voordat je hem registreert, roep je hem aan in een notitieboekje met voorbeeldgegevens:

test_df = spark.createDataFrame(
    [("Alice", 100), ("Bob", 200)],
    ["name", "amount"]
)

result = run(
    config={"filter_expression": "amount > 100"},
    inputs={"in": test_df},
    spark=spark
)

result["out"].show()

Als uw operator externe PIP-pakketten vereist, voegt u het environment veld toe aan de YAML:

environment:
  environment_version: '4'
  dependencies:
    - requests==2.31.0
    - beautifulsoup4==4.12.0

Schrijf een UDF- of UDTF-operator

Je kunt Unity Catalog-functies schrijven in SQL of Python. Python functies worden verpakt in een SQL CREATE FUNCTION-instructie:

SQL-functie:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
RETURN
  SELECT weight_kg / (height_m * height_m);

Python-functie (verpakt in SQL):

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
  return weight_kg / (height_m ** 2)
$$;

UDF's verwerken één waarde tegelijk en retourneren een berekende waarde. UDTF's verwerken tabellen rij voor rij en kunnen over alle rijen heen een toestand behouden. Gebruiken uc-udf voor transformaties op kolomniveau en uc-udtf voor bewerkingen zoals ML-clustering of aggregatie.

Een UDTF-handlerklasse definieert eval(), die voor elke invoerrij draait. Optioneel definieert het ook __init__() om state in te stellen en terminate() om eindresultaten te geven na alle rijen. Zie door de gebruiker gedefinieerde tabelfuncties (UDDF's) van Python in Unity Catalog.

class MyOperator:
    def __init__(self):
        # Optional. Called before processing - initialize any values needed.
        ...

    def eval(self, row):
        # Required. Called one time per input row - process or accumulate data here.
        ...

    def terminate(self):
        # Optional. Called after all rows - perform final calculations and yield results.
        ...

Notitie

UDTF-retourtabellen moeten vaste, expliciete typen hebben. U kunt niet verwijzen naar invoerkolomtypen in de retourconfiguratie.

Sla neveneffecten over tijdens previews

Lakeflow Designer ondersteunt previews in de ontwerpmodus. Voor operators die externe API's aanroepen of schrijven naar externe systemen, voegt u een is_preview configuratie-eigenschap toe, zodat u neveneffecten tijdens de preview-versie kunt overslaan. Gebruikers klikken op Run om de operator met de bijwerkingen uit te voeren. De ingebouwde Python-operator heeft deze eigenschap niet nodig, omdat deze config["is_preview"] automatisch leest. Zie Python preview-modus.

config:
  type: object
  properties:
    is_preview:
      type: boolean
      format: is_preview
      default: false

Lakeflow Designer stelt deze waarde true automatisch in op tijdens de preview. Vink dit in uw logica aan om neveneffecten over te slaan:

# In a python-run-function
if config.get("is_preview"):
    return {"out": inputs["in"]}

-- In a UC function (SQL)
CASE WHEN is_preview THEN 'preview' ELSE /* actual work */ END

Roep externe API's aan met HTTP-verbindingen van Unity Catalog

Voor door gebruikers gedefinieerde operatoren gebaseerd op SQL Unity Catalog-functies die externe API's aanroepen, gebruik Unity Catalog HTTP-verbindingen om inloggegevens veilig op te slaan:

CREATE CONNECTION my_api_connection TYPE HTTP OPTIONS (
  host 'https://api.example.com',
  port '443',
  base_path '/v1/',
  bearer_token 'your-token-here'
);

Gebruik vervolgens de verbinding in uw SQL UDF met de http_request() functie. Zie Verbinding maken met externe HTTP-services voor meer informatie.

Krijg toegang tot workspace-bronnen met WorkspaceClient

Voor python-run-function-operators kunt u de Azure Databricks WorkspaceClient gebruiken voor toegang tot werkruimtebronnen en externe API's:

def run(config, inputs, spark):
    from databricks.sdk import WorkspaceClient
    w = WorkspaceClient()
    # Use w to access workspace resources

Aanvullende bronnen

  • Laatst bijgewerkt om