Erstellen von Ausdrücken im ZuordnungsdatenflussBuild expressions in mapping data flow

GILT FÜR: Azure Data Factory Azure Synapse Analytics

Im Zuordnungsdatenfluss werden viele Transformationseigenschaften als Ausdrücke eingegeben.In mapping data flow, many transformation properties are entered as expressions. Diese Ausdrücke bestehen aus Spaltenwerten, Parametern, Funktionen, Operatoren und Literalen, die zur Laufzeit zu einem Spark-Datentyp ausgewertet werden.These expressions are composed of column values, parameters, functions, operators, and literals that evaluate to a Spark data type at run time. Die Zuordnung von Datenflüssen verfügt über eine dedizierte Funktion, die Sie bei der Erstellung dieser Ausdrücke unterstützen soll, den so genannten Ausdrucks-Generator.Mapping data flows has a dedicated experience aimed to aid you in building these expressions called the Expression Builder. Der Ausdrucks-Generator nutzt die IntelliSense-Codevervollständigung für Hervorhebung, Syntaxüberprüfung und automatische Vervollständigung und soll Ihnen das Erstellen von Datenflüssen erleichtern.Utilizing IntelliSense code completion for highlighting, syntax checking, and autocompleting, the expression builder is designed to make building data flows easy. In diesem Artikel wird erläutert, wie Sie den Ausdrucks-Generator verwenden, um Ihre Geschäftslogik effektiv zu erstellen.This article explains how to use the expression builder to effectively build your business logic.

Ausdrucks-GeneratorExpression Builder

Öffnen des Ausdrucks-GeneratorsOpen Expression Builder

Der Ausdrucks-Generator kann auf verschiedene Weise geöffnet werden.There are multiple entry points to opening the expression builder. Diese hängen jeweils vom Kontext der Datenflusstransformation ab.These are all dependent on the specific context of the data flow transformation. Der häufigste Anwendungsfall ist eine Transformation wie eine abgeleitete Spalte und ein Aggregat, bei denen Benutzer Spalten mithilfe der Ausdruckssprache für Datenflüsse erstellen oder aktualisieren.The most common use case is in transformations like derived column and aggregate where users create or update columns using the data flow expression language. Sie können den Ausdrucks-Generator öffnen, indem Sie über der Spaltenliste Ausdrucks-Generator öffnen auswählen.The expression builder can be opened by selecting Open expression builder above the list of columns. Sie können auch auf einen Spaltenkontext klicken und den Ausdrucks-Generator direkt für diesen Ausdruck öffnen.You can also click on a column context and open the expression builder directly to that expression.

Öffnen des Ausdrucks-Generators – AbgeleitetOpen Expression Builder derive

Bei einigen Transformationen wie Filtern wird der Ausdrucks-Generator durch Klicken auf ein blaues Ausdruckstextfeld geöffnet.In some transformations like filter, clicking on a blue expression text box will open the expression builder.

Blaues AusdrucksfeldBlue expression box

Wenn Sie in einer Übereinstimmungs- oder Gruppieren nach-Bedingung auf Spalten verweisen, kann ein Ausdruck Werte aus Spalten extrahieren.When you reference columns in a matching or group-by condition, an expression can extract values from columns. Wählen Sie zum Erstellen eines Ausdrucks die Option Berechnete Spalte aus.To create an expression, select Computed column.

Option „Berechnete Spalte“Computed column option

In Fällen, in denen ein Ausdruck oder ein Literalwert gültige Eingaben sind, können Sie mit Dynamischen Inhalt hinzufügen einen Ausdruck erstellen, der zu einem Literalwert ausgewertet wird.In cases where an expression or a literal value are valid inputs, select Add dynamic content to build an expression that evaluates to a literal value.

Option „Dynamischen Inhalt hinzufügen“Add dynamic content option

Elemente eines AusdrucksExpression elements

Bei Zuordnungsdatenflüssen können Ausdrücke aus Spaltenwerten, Parametern, Funktionen, lokalen Variablen, Operatoren und Literalwerten bestehen.In mapping data flows, expressions can be composed of column values, parameters, functions, local variables, operators, and literals. Diese Ausdrücke müssen als Spark-Datentyp wie Zeichenfolge, boolescher Wert oder ganze Zahl ausgewertet werden können.These expressions must evaluate to a Spark data type such as string, boolean, or integer.

Elemente eines AusdrucksExpression elements

FunktionenFunctions

Zuordnungsdatenflüsse verfügen über integrierte Funktionen und Operatoren, die in Ausdrücken verwendet werden können.Mapping data flows has built-in functions and operators that can be used in expressions. Eine Liste der verfügbaren Funktionen finden Sie in der Sprachreferenz zu Zuordnungsdatenflüssen.For a list of available functions, see the mapping data flow language reference.

Angeben von ArrayindizesAddress array indexes

Verwenden Sie bei Spalten oder Funktionen, die Arraytypen zurückgeben, eckige Klammern ([]), um auf ein bestimmtes Element zuzugreifen.When dealing with columns or functions that return array types, use brackets ([]) to access a specific element. Wenn der Index nicht vorhanden ist, wird der Ausdruck als NULL ausgewertet.If the index doesn't exist, the expression evaluates into NULL.

Ausdrucks-Generator: ArrayExpression Builder array

Wichtig

Bei der Zuordnung von Datenflüssen haben Arrays die Basis 1, d. h., das erste Element hat den Index 1.In mapping data flows, arrays are one-based meaning the first element is referenced by index one. Beispielsweise greifen Sie mit myArray[1] auf das erste Element eines Arrays mit dem Namen „myArray“ zu.For example, myArray[1] will access the first element of an array called 'myArray'.

EingabeschemaInput schema

Wenn der Datenfluss in einer seiner Quellen ein definiertes Schema verwendet, können Sie in vielen Ausdrücken anhand des Namens auf eine Spalte verweisen.If your data flow uses a defined schema in any of its sources, you can reference a column by name in many expressions. Wenn Sie die Schemaabweichung verwenden, können Sie mit den Funktionen byName() oder byNames() explizit auf Spalten verweisen oder mithilfe von Spaltenmustern Übereinstimmungen auswählen.If you are utilizing schema drift, you can reference columns explicitly using the byName() or byNames() functions or match using column patterns.

Spaltennamen mit SonderzeichenColumn names with special characters

Wenn Sie Spaltennamen mit Sonder- oder Leerzeichen haben, setzen Sie den Namen in geschweifte Klammern, um darauf in einem Ausdruck zu verweisen.When you have column names that include special characters or spaces, surround the name with curly braces to reference them in an expression.

{[dbo].this_is my complex name$$$}

ParameterParameters

Parameter sind Werte, die von einer Pipeline zur Laufzeit an einen Datenfluss übergeben werden.Parameters are values that are passed into a data flow at run time from a pipeline. Um auf einen Parameter zu verweisen, klicken Sie entweder in der Ansicht Ausdruckselemente auf den Parameter, oder verweisen Sie darauf mit einem Dollarzeichen vor seinem Namen.To reference a parameter, either click on the parameter from the Expression elements view or reference it with a dollar sign in front of its name. Beispielsweise wird mit $parameter1 auf einen Parameter mit dem Namen „parameter1“ verwiesen.For example, a parameter called parameter1 would be referenced by $parameter1. Weitere Informationen finden Sie unter Parametrisieren von Zuordnungsdatenflüssen.To learn more, see parameterizing mapping data flows.

Zwischengespeicherte SucheCached lookup

Eine zwischengespeicherte Suche ermöglicht die Inlinesuche der Ausgabe einer zwischengespeicherten Senke.A cached lookup allows you to do an inline lookup of the output of a cached sink. Für jede Senke stehen zwei Funktionen zur Verfügung: lookup() und outputs().There are two functions available to use on each sink, lookup() and outputs(). Die Syntax zum Verweisen auf diese Funktionen lautet cacheSinkName#functionName().The syntax to reference these functions is cacheSinkName#functionName(). Weitere Informationen finden Sie unter Cachesenken.For more information, see cache sinks.

lookup() akzeptiert die übereinstimmenden Spalten in der aktuellen Transformation als Parameter und gibt eine komplexe Spalte zurück. Diese entspricht der Zeile mit den übereinstimmenden Schlüsselspalten in der Cachesenke.lookup() takes in the matching columns in the current transformation as parameters and returns a complex column equal to the row matching the key columns in the cache sink. Die zurückgegebene komplexe Spalte enthält eine untergeordnete Spalte für jede zugeordnete Spalte in der Cachesenke.The complex column returned contains a subcolumn for each column mapped in the cache sink. Ein Beispiel: Sie verfügen über eine Fehlercode-Cachesenke errorCodeCache, die eine Schlüsselspalte mit Codeübereinstimmung und eine Spalte namens Message aufweist.For example, if you had an error code cache sink errorCodeCache that had a key column matching on the code and a column called Message. Ein Aufruf von errorCodeCache#lookup(errorCode).Message würde die Meldung zurückgeben, die dem übergebenen Code entspricht.Calling errorCodeCache#lookup(errorCode).Message would return the message corresponding with the code passed in.

outputs() akzeptiert keine Parameter und gibt die gesamte Cachesenke als Array komplexer Spalten zurück.outputs() takes no parameters and returns the entire cache sink as an array of complex columns. Ein Aufruf ist nicht möglich, wenn Schlüsselspalten in der Senke angegeben sind. Dieser Vorgang sollte nur dann verwendet werden, wenn die Cachesenke nur einige wenige Zeilen enthält.This can't be called if key columns are specified in the sink and should only be used if there is a small number of rows in the cache sink. Ein gängiger Anwendungsfall ist das Anfügen des Maximalwerts eines Schlüssels, der inkrementell erhöht wird.A common use case is appending the max value of an incrementing key. Wenn die zwischengespeicherte aggregierte Einzelzeile CacheMaxKey die Spalte MaxKey enthält, können Sie durch Aufruf von CacheMaxKey#outputs()[1].MaxKey auf den ersten Wert verweisen.If a cached single aggregated row CacheMaxKey contains a column MaxKey, you can reference the first value by calling CacheMaxKey#outputs()[1].MaxKey.

Zwischengespeicherte SucheCached lookup

LocalsLocals

Wenn Sie Ihre Logik für mehrere Spalten gemeinsam nutzen oder aufteilen möchten, können Sie eine lokale Variable in einer abgeleiteten Spalte erstellen.If you are sharing logic across multiple columns or want to compartmentalize your logic, you can create a local within a derived column. Wenn Sie auf eine lokale Variable verweisen möchten, klicken Sie entweder in der Ansicht Ausdruckselemente auf die lokale Variable, oder verweisen Sie darauf mit einem Doppelpunkt vor ihrem Namen.To reference a local, either click on the local from the Expression elements view or reference it with a colon in front of its name. Beispielsweise wird mit :local1 auf eine lokale Variable mit dem Namen „local1“ verwiesen.For example, a local called local1 would be referenced by :local1. Weitere Informationen zu lokalen Variablen finden Sie in der Dokumentation zu abgeleiteten Spalten.Learn more about locals in the derived column documentation.

Vorschau von AusdrucksergebnissenPreview expression results

Wenn debug mode aktiviert ist, können Sie mithilfe des Debugclusters interaktiv eine Vorschau des Werts anzeigen, den der Ausdruck ergibt.If debug mode is switched on, you can interactively use the debug cluster to preview what your expression evaluates to. Wählen Sie neben der Datenvorschau Aktualisieren aus, um die Ergebnisse der Datenvorschau zu aktualisieren.Select Refresh next to data preview to update the results of the data preview. Es wird die Ausgabe für jede Zeile entsprechend den Eingabespalten angezeigt.You can see the output of each row given the input columns.

Vorschau während der BearbeitungIn-progress preview

ZeichenfolgeninterpolierungString interpolation

Wenn Sie lange Zeichenfolgen erstellen, die Ausdruckselemente verwenden, verwenden Sie die Zeichenfolgeninterpolation, um problemlos eine komplexe Zeichenfolgenlogik zu erstellen.When creating long strings that use expression elements, use string interpolation to easily build up complex string logic. Durch die Zeichenfolgeninterpolation wird eine übermäßige Verkettung von Zeichenfolgen vermieden, wenn Parameter in Abfragezeichenfolgen einbezogen werden.String interpolation avoids extensive use of string concatenation when parameters are included in query strings. Verwenden Sie doppelte Anführungszeichen, um Literalzeichenfolgen in Ausdrücke einzuschließen.Use double quotation marks to enclose literal string text together with expressions. Sie können Ausdrucksfunktionen, Spalten und Parameter einbeziehen.You can include expression functions, columns, and parameters. Wenn Sie eine Ausdruckssyntax verwenden möchten, schließen Sie sie in geschweifte Klammern ein.To use expression syntax, enclose it in curly braces,

Einige Beispiele für Zeichenfolgeninterpolation:Some examples of string interpolation:

  • "My favorite movie is {iif(instr(title,', The')>0,"The {split(title,', The')[1]}",title)}"

  • "select * from {$tablename} where orderyear > {$year}"

  • "Total cost with sales tax is {round(totalcost * 1.08,2)}"

  • "{:playerName} is a {:playerRating} player"

Hinweis

Bei Verwendung der Syntax für Zeichenfolgeninterpolation in SQL-Quellabfragen muss die Abfragezeichenfolge in einer einzigen Zeile (ohne ‚/n‘) stehen.When using string interpolation syntax in SQL source queries, the query string must be on one single line, without '/n'.

Kommentieren von AusdrückenCommenting expressions

Fügen Sie Ihren Ausdrücken Kommentare hinzu. Verwenden Sie dabei eine einzeilige oder eine mehrzeilige Kommentarsyntax.Add comments to your expressions by using single-line and multiline comment syntax.

Die folgenden Beispiele stellen gültige Kommentare dar:The following examples are valid comments:

  • /* This is my comment */

  • /* This is a

  • multi-line comment */

Wenn Sie einen Kommentar am Anfang des Ausdrucks einfügen, wird er im Transformationstextfeld angezeigt und dokumentiert Ihre Transformationsausdrücke.If you put a comment at the top of your expression, it appears in the transformation text box to document your transformation expressions.

Kommentar im TransformationstextfeldComment in the transformation text box

Reguläre AusdrückeRegular expressions

Viele Ausdruckssprachfunktionen verwenden die reguläre Ausdruckssyntax.Many expression language functions use regular expression syntax. Wenn Sie Funktionen mit regulären Ausdrücken verwenden, versucht der Ausdrucks-Generator, den umgekehrten Schrägstrich (\) als Escapezeichensequenz zu interpretieren.When you use regular expression functions, Expression Builder tries to interpret a backslash (\) as an escape character sequence. Wenn Sie in Ihrem regulären Ausdruck umgekehrte Schrägstriche verwenden, schließen Sie entweder den gesamten regulären Ausdruck in Backticks (`) ein, oder verwenden Sie einen doppelten umgekehrten Schrägstrich.When you use backslashes in your regular expression, either enclose the entire regex in backticks (`) or use a double backslash.

Ein Beispiel mit Backticks:An example that uses backticks:

regex_replace('100 and 200', `(\d+)`, 'digits')

Ein Beispiel mit doppelten umgekehrten Schrägstrichen:An example that uses double slashes:

regex_replace('100 and 200', '(\\d+)', 'digits')

TastenkombinationenKeyboard shortcuts

Im Folgenden finden Sie eine Liste der Tastenkombination, die im Ausdrucks-Generator unterstützt werden.Below are a list of shortcuts available in the expression builder. Beim Erstellen von Ausdrücken sind die meisten IntelliSense-Tastenkombinationen verfügbar.Most intellisense shortcuts are available when creating expressions.

  • STRG+K, STRG+C: Gesamte Zeile auskommentierenCtrl+K Ctrl+C: Comment entire line.
  • STRG+K, STRG+U: Auskommentierung aufhebenCtrl+K Ctrl+U: Uncomment.
  • F1: Befehle der Editor-Hilfe anzeigenF1: Provide editor help commands.
  • ALT+NACH-UNTEN-TASTE: Aktuelle Zeile nach unten verschiebenAlt+Down arrow key: Move down current line.
  • ALT+NACH-OBEN-TASTE: Aktuelle Zeile nach oben verschiebenAlt+Up arrow key: Move up current line.
  • STRG+LEERTASTE: Kontexthilfe anzeigenCtrl+Spacebar: Show context help.

Häufig verwendete AusdrückeCommonly used expressions

Konvertieren in Datumsangaben oder ZeitstempelConvert to dates or timestamps

Wenn Sie Zeichenfolgenliterale in Ihre Zeitstempelausgabe einbeziehen möchten, schließen Sie die Konvertierung in toString() ein.To include string literals in your timestamp output, wrap your conversion in toString().

toString(toTimestamp('12/31/2016T00:12:00', 'MM/dd/yyyy\'T\'HH:mm:ss'), 'MM/dd /yyyy\'T\'HH:mm:ss')

Wenn Sie Millisekunden von einer Epoche in ein Datum oder einen Zeitstempel konvertieren möchten, verwenden Sie toTimestamp(<number of milliseconds>).To convert milliseconds from epoch to a date or timestamp, use toTimestamp(<number of milliseconds>). Wenn die Zeit in Sekunden angezeigt wird, multiplizieren Sie den Wert mit 1.000.If time is coming in seconds, multiply by 1,000.

toTimestamp(1574127407*1000l)

Das nachgestellte „l“ am Ende des vorstehenden Ausdrucks gibt eine Konvertierung in einen long-Datentyp als inline-Syntax an.The trailing "l" at the end of the previous expression signifies conversion to a long type as inline syntax.

Zeit aus Epochen- oder Unix-Zeit findenFind time from epoch or Unix Time

toLong( currentTimestamp() - toTimestamp('1970-01-01 00:00:00.000', 'yyyy-MM-dd HH:mm:ss.SSS') ) * 1000ltoLong( currentTimestamp() - toTimestamp('1970-01-01 00:00:00.000', 'yyyy-MM-dd HH:mm:ss.SSS') ) * 1000l

Nächste SchritteNext steps

Mit dem Erstellen von Datentransformationsausdrücken beginnenBegin building data transformation expressions