Uživatelem definované funkce

Přepněte služby pomocí rozevíracího seznamu Verze . Přečtěte si další informace o navigaci.
Platí pro: ✅ Microsoft Fabric ✅ Azure Data Explorer ✅ Azure Monitor ✅ Microsoft Sentinel

Uživatelem definované funkce jsou opakovaně použitelné poddotazy, které je možné definovat jako součást samotného dotazu (funkce definované dotazem) nebo uložené jako součást metadat databáze (uložené funkce). Uživatelem definované funkce jsou vyvolány prostřednictvím názvu, jsou poskytovány s nulovými nebo více vstupními argumenty (které mohou být skalární nebo tabulkové) a vytvářejí jednu hodnotu (což může být skalární nebo tabulkový) na základě těla funkce.

Uživatelem definovaná funkce patří do jedné ze dvou kategorií:

• Skalární funkce
• Tabulkové funkce

Vstupní argumenty a výstup funkce určují, jestli se jedná o skalární nebo tabulkový, který pak určí, jak se může použít.

Pokud chcete optimalizovat více použití uživatelem definovaných funkcí v rámci jednoho dotazu, přečtěte si téma Optimalizace dotazů, které používají pojmenované výrazy.

Vytvořili jsme řadu uživatelem definovaných funkcí, které můžete použít ve svých dotazech. Další informace najdete v tématu Knihovna funkcí.

Skalární funkce

• Má nulové vstupní argumenty nebo všechny vstupní argumenty jsou skalární hodnoty.
• Vytvoří jednu skalární hodnotu.
• Lze použít všude, kde je povolený skalární výraz.
• Může používat pouze kontext řádku, ve kterém je definovaný.
• Může odkazovat pouze na tabulky (a zobrazení), které jsou ve schématu s podporou přístupnosti.

Tabulková funkce

• Přijímá jeden nebo více tabulkových vstupních argumentů a nula nebo více skalárních vstupních argumentů a/nebo:
• Vytvoří jednu tabulkovou hodnotu.

Názvy funkcí

Platné uživatelsky definované názvy funkcí musí dodržovat stejná pravidla pojmenování identifikátoru jako jiné entity.

Název musí být také jedinečný v jeho oboru definice.

Poznámka:

Pokud uložená funkce i tabulka mají stejný název, všechny odkazy na tento název se přeloží na uloženou funkci, nikoli na název tabulky. Místo toho můžete na tabulku odkazovat pomocí funkce tabulky .

Vstupní argumenty

Platné uživatelem definované funkce se řídí těmito pravidly:

• Uživatelem definovaná funkce má seznam nulových nebo více vstupních argumentů.
• Vstupní argument má název, typ a (pro skalární argumenty) výchozí hodnotu.
• Název vstupního argumentu je identifikátor.
• Typ vstupního argumentu je buď jeden ze skalárních datových typů, nebo tabulkové schéma.

Seznam vstupních argumentů je syntakticky seznam definic argumentů oddělený čárkami, který je zabalený do závorek. Každá definice argumentu je určena jako

ArgName:ArgType [= ArgDefaultValue]

U tabulkových argumentů má ArgType stejnou syntaxi jako definice tabulky (závorky a seznam dvojic názvů a typů sloupců) s přidáním solitárního (*) schématu označujícího "jakékoli tabulkové schéma".

Například:

Syntaxe	Popis seznamu vstupních argumentů
()	Žádné argumenty
(s:string)	Jeden skalární argument, který se nazývá s přebírání hodnoty typu string
(a:long, b:bool=true)	Dva skalární argumenty, druhý z nichž má výchozí hodnotu
(T1:(*), T2:(r:real), b:bool)	Tři argumenty (dva tabulkové argumenty a jeden skalární argument)

Poznámka:

Při použití tabulkových vstupních argumentů i skalárních vstupních argumentů vložte všechny tabulkové vstupní argumenty před skalární vstupní argumenty.

Examples

Skalární funkce

Spuštění dotazu

let Add7 = (arg0:long = 5) { arg0 + 7 };
range x from 1 to 10 step 1
| extend x_plus_7 = Add7(x), five_plus_seven = Add7()

Tabulková funkce bez argumentů

Spuštění dotazu

let tenNumbers = () { range x from 1 to 10 step 1};
tenNumbers
| extend x_plus_7 = x + 7

Tabulková funkce s argumenty

Spuštění dotazu

let MyFilter = (T:(x:long), v:long) {
  T | where x >= v
};
MyFilter((range x from 1 to 10 step 1), 9)

Výstup

x
9
10

Tabulková funkce, která používá tabulkový vstup bez zadaného sloupce. Do funkce lze předat libovolnou tabulku a uvnitř funkce se nedají odkazovat žádné sloupce tabulky.

Spuštění dotazu

let MyDistinct = (T:(*)) {
  T | distinct *
};
MyDistinct((range x from 1 to 3 step 1))

Výstup

x
1
2
3

Deklarace uživatelem definovaných funkcí

Deklarace uživatelem definované funkce poskytuje:

• Název funkce
• Schéma funkce (parametry, které přijímá, pokud existuje)
• Tělo funkce

Poznámka:

Přetížení funkcí není podporováno. Nemůžete vytvořit více funkcí se stejným názvem a různými vstupními schématy.

Návod

Funkce lambda nemají název a jsou svázané s názvem pomocí příkazu let. Proto je lze považovat za uživatelem definované uložené funkce. Příklad: Deklarace funkce lambda, která přijímá dva argumenty (volaný strings a volaný longi). Vrátí součin prvního (po převodu na číslo) a druhý. Lambda je svázaná s názvem f:

let f=(s:string, i:long) {
    tolong(s) * i
};

Tělo funkce zahrnuje :

• Přesně jeden výraz, který poskytuje návratovou hodnotu funkce (skalární nebo tabulková hodnota).
• Libovolné číslo (nula nebo více) příkazů let, jejichž oborem je tělo funkce. Pokud je zadáno, příkazy let musí předcházet výrazu definujícím návratovou hodnotu funkce.
• Libovolné číslo (nula nebo více) příkazů parametrů dotazu, které deklarují parametry dotazu používané funkcí. Pokud je zadáno, musí před výraz definující návratovou hodnotu funkce.

Poznámka:

Jiné druhy příkazů dotazu, které jsou podporovány na nejvyšší úrovni dotazu, nejsou podporovány v těle funkce. Všechny dva příkazy musí být oddělené středníkem.

Příklady uživatelem definovaných funkcí

Následující část ukazuje příklady použití uživatelem definovaných funkcí.

Uživatelem definovaná funkce, která používá příkaz let

Následující příklad ukazuje uživatelem definovanou funkci (lambda), která přijímá parametr s názvem ID. Funkce je svázaná s názvem Test a používá tři příkazy let , ve kterých definice Test3 používá parametr ID . Při spuštění je výstup z dotazu 70:

Spuštění dotazu

let Test = (id: int) {
  let Test2 = 10;
  let Test3 = 10 + Test2 + id;
  let Test4 = (arg: int) {
      let Test5 = 20;
      Test2 + Test3 + Test5 + arg
  };
  Test4(10)
};
range x from 1 to Test(10) step 1
| count

Uživatelem definovaná funkce, která definuje výchozí hodnotu parametru

Následující příklad ukazuje funkci, která přijímá tři argumenty. Tyto dvě mají výchozí hodnotu a nemusí být přítomné na webu volání.

Spuštění dotazu

let f = (a:long, b:string = "b.default", c:long = 0) {
  strcat(a, "-", b, "-", c)
};
print f(12, c=7) // Returns "12-b.default-7"

Vyvolání uživatelem definované funkce

Metoda vyvolání uživatelem definované funkce závisí na argumentech, které funkce očekává přijímat. Následující části obsahují informace o tom, jak vyvolat uživatelem definovanou uživatelem bez argumentů, vyvolat uživatelem definovanou uživatelem pomocí skalárních argumentů a vyvolat UDF s tabulkovými argumenty.

Vyvolání funkce definované uživatelem bez argumentů

Uživatelem definovaná funkce, která nepřijímá žádné argumenty a nelze ji vyvolat buď podle názvu, nebo podle názvu a prázdného seznamu argumentů v závorkách.

Spuštění dotazu

// Bind the identifier a to a user-defined function (lambda) that takes
// no arguments and returns a constant of type long:
let a=(){123};
// Invoke the function in two equivalent ways:
range x from 1 to 10 step 1
| extend y = x * a, z = x * a()

Spuštění dotazu

// Bind the identifier T to a user-defined function (lambda) that takes
// no arguments and returns a random two-by-two table:
let T=(){
  range x from 1 to 2 step 1
  | project x1 = rand(), x2 = rand()
};
// Invoke the function in two equivalent ways:
// (Note that the second invocation must be itself wrapped in
// an additional set of parentheses, as the union operator
// differentiates between "plain" names and expressions)
union T, (T())

Vyvolání uživatelem definovaného uživatelem s skalárními argumenty

Uživatelem definovaná funkce, která přebírá jeden nebo více skalárních argumentů, lze vyvolat pomocí názvu funkce a konkrétního seznamu argumentů v závorkách:

Spuštění dotazu

let f=(a:string, b:string) {
  strcat(a, " (la la la)", b)
};
print f("hello", "world")

Vyvolání funkce definované uživatelem s tabulkovými argumenty

Uživatelem definovaná funkce, která přebírá jeden nebo více argumentů tabulky (s libovolným počtem skalárních argumentů) a lze ji vyvolat pomocí názvu funkce a konkrétního seznamu argumentů v závorkách:

Spuštění dotazu

let MyFilter = (T:(x:long), v:long) {
  T | where x >= v
};
MyFilter((range x from 1 to 10 step 1), 9)

Pomocí operátoru invoke můžete také vyvolat uživatelem definovanou funkci, která přebírá jeden nebo více argumentů tabulky a vrací tabulku. Tato funkce je užitečná, když první argument konkrétní tabulky funkce je zdrojem operátoru invoke :

Spuštění dotazu

let append_to_column_a=(T:(a:string), what:string) {
    T | extend a=strcat(a, " ", what)
};
datatable (a:string) ["sad", "really", "sad"]
| invoke append_to_column_a(":-)")

Výchozí hodnoty

Funkce můžou poskytovat výchozí hodnoty některým z jejich parametrů za následujících podmínek:

• Výchozí hodnoty mohou být poskytovány pouze pro skalární parametry.
• Výchozí hodnoty jsou vždy literály (konstanty). Nemůžou být libovolné výpočty.
• Parametry bez výchozí hodnoty vždy předchází parametrům, které mají výchozí hodnotu.
• Volající musí zadat hodnotu všech parametrů bez výchozích hodnot uspořádaných ve stejném pořadí jako deklarace funkce.
• Volající nemusí zadávat hodnotu parametrů s výchozími hodnotami, ale můžou to udělat.
• Volající můžou poskytovat argumenty v pořadí, které neodpovídá pořadí parametrů. Pokud ano, musí své argumenty pojmenovat.

Následující příklad vrátí tabulku se dvěma identickými záznamy. Při prvním vyvolání jsou argumenty zcela "zakódované", takže každému fz nich je explicitně přidělen název:

Spuštění dotazu

let f = (a:long, b:string = "b.default", c:long = 0) {
  strcat(a, "-", b, "-", c)
};
union
  (print x=f(c=7, a=12)), // "12-b.default-7"
  (print x=f(12, c=7))    // "12-b.default-7"

Výstup

x
12-b.default-7
12-b.default-7

Zobrazit funkce

Uživatelem definovaná funkce, která nepřijímá žádné argumenty a vrací tabulkový výraz, lze označit jako zobrazení. Označení uživatelem definované funkce jako zobrazení znamená, že se funkce chová jako tabulka při každém provedení překladu názvů zástupných znaků.

Následující příklad ukazuje dvě uživatelem definované funkce a T_viewa ukazuje, T_notview jak pouze první z nich je vyřešen zástupným znakem v :union

let T_view = view () { print x=1 };
let T_notview = () { print x=2 };
union T*

Restrictions

Platí následující omezení:

• Uživatelem definované funkce nemůžou předávat informace o vyvolání toscalar(), které závisí na kontextu řádku, ve kterém je funkce volána.
• Uživatelem definované funkce, které vracejí tabulkový výraz, nelze vyvolat pomocí argumentu, který se liší podle kontextu řádku.

• Funkci, která přijímá alespoň jeden tabulkový vstup, nejde vyvolat ve vzdáleném clusteru.
• Skalární funkci nelze vyvolat ve vzdáleném clusteru.

Jediné místo, kde je funkce definovaná uživatelem, může být vyvolána argumentem, který se liší podle kontextu řádku, je, když se uživatelem definovaná funkce skládá pouze ze skalárních funkcí a nepoužívá toscalar().

Examples

Podporovaná skalární funkce

Následující dotaz je podporovaný, protože f skalární funkce, která neodkazuje na žádný tabulkový výraz.

Spuštění dotazu

let Table1 = datatable(xdate:datetime)[datetime(1970-01-01)];
let Table2 = datatable(Column:long)[1235];
let f = (hours:long) { now() + hours*1h };
Table2 | where Column != 123 | project d = f(10)

Následující dotaz je podporován, protože f je skalární funkce, která odkazuje na tabulkový výraz Table1 , ale je vyvolána bez odkazu na kontext f(10)aktuálního řádku:

Spuštění dotazu

let Table1 = datatable(xdate:datetime)[datetime(1970-01-01)];
let Table2 = datatable(Column:long)[1235];
let f = (hours:long) { toscalar(Table1 | summarize min(xdate) - hours*1h) };
Table2 | where Column != 123 | project d = f(10)

Nepodporovaná skalární funkce

Následující dotaz není podporován, protože f je skalární funkce, která odkazuje na tabulkový výraz Table1a je vyvolána s odkazem na kontext f(Column)aktuálního řádku:

let Table1 = datatable(xdate:datetime)[datetime(1970-01-01)];
let Table2 = datatable(Column:long)[1235];
let f = (hours:long) { toscalar(Table1 | summarize min(xdate) - hours*1h) };
Table2 | where Column != 123 | project d = f(Column)

Nepodporovaná tabulková funkce

Následující dotaz není podporovaný, protože f jde o tabulkovou funkci, která se vyvolá v kontextu, který očekává skalární hodnotu.

let Table1 = datatable(xdate:datetime)[datetime(1970-01-01)];
let Table2 = datatable(Column:long)[1235];
let f = (hours:long) { range x from 1 to hours step 1 | summarize make_list(x) };
Table2 | where Column != 123 | project d = f(Column)

Funkce, které aktuálně nejsou podporovány uživatelem definovanými funkcemi

Pro úplnost tady jsou některé běžně požadované funkce pro uživatelem definované funkce, které se v současné době nepodporují:

1. Přetížení funkcí: V současné době neexistuje způsob, jak funkci přetížit (způsob, jak vytvořit více funkcí se stejným názvem a jiným vstupním schématem).

2. Výchozí hodnoty: Výchozí hodnota skalárního parametru pro funkci musí být skalární literál (konstanta).

Související obsah

• Uložené funkce
• zobrazení