Kullanıcı tanımlı işlevler

Kullanıcı tanımlı işlevler , sorgunun parçası olarak tanımlanabilen (sorgu tanımlı işlevler) veya veritabanı meta verilerinin (depolanan işlevler) parçası olarak depolanabilen yeniden kullanılabilir alt sorgulardır. Kullanıcı tanımlı işlevler bir ad aracılığıyla çağrılır, sıfır veya daha fazla giriş bağımsız değişkeniyle (skaler veya tablolu olabilir) sağlanır ve işlev gövdesine göre tek bir değer (skaler veya tablolu olabilir) üretir.

Kullanıcı tanımlı bir işlev iki kategoriden birine aittir:

• Skaler işlevler
• Tablosal işlevler

İşlevin giriş bağımsız değişkenleri ve çıkışı, skaler mi yoksa tablosal mı olduğunu belirler ve bu da nasıl kullanılabileceğini belirler.

Tek bir sorguda kullanıcı tanımlı işlevlerin birden çok kullanımını iyileştirmek için bkz. Adlandırılmış ifadeler kullanan sorguları iyileştirme.

Skaler işlev

• Giriş bağımsız değişkenleri sıfırdır veya tüm giriş bağımsız değişkenleri skaler değerlerdir
• Tek bir skaler değer üretir
• Skaler ifadeye izin verilen her yerde kullanılabilir
• Yalnızca tanımlandığı satır bağlamını kullanabilir
• Yalnızca erişilebilir şemadaki tablolara (ve görünümlere) başvurabilir

Tablo işlevi

• Bir veya daha fazla tablosal giriş bağımsız değişkeni ve sıfır veya daha fazla skaler giriş bağımsız değişkeni kabul eder ve/veya:
• Tek bir tablosal değer üretir

İşlev adları

Geçerli kullanıcı tanımlı işlev adları, diğer varlıklarla aynı tanımlayıcı adlandırma kurallarına uymalıdır .

Adın tanım kapsamında da benzersiz olması gerekir.

Not

Hem depolanan işlev hem de tablo aynı ada sahipse, bu ada yapılan tüm başvurular tablo adını değil saklı işleve çözümler. Bunun yerine tabloya başvurmak için table işlevini kullanın.

Giriş bağımsız değişkenleri

Geçerli kullanıcı tanımlı işlevler şu kurallara uyar:

• Kullanıcı tanımlı bir işlevin kesin olarak belirlenmiş bir sıfır veya daha fazla giriş bağımsız değişkeni listesi vardır.
• Giriş bağımsız değişkeninin adı, türü ve (skaler bağımsız değişkenler için) varsayılan değeri vardır.
• Giriş bağımsız değişkeninin adı bir tanımlayıcıdır.
• Giriş bağımsız değişkeninin türü skaler veri türlerinden biridir veya tablo şemasıdır.

Giriş bağımsız değişkenleri listesi, bağımsız değişken tanımlarının virgülle ayrılmış ve parantez içinde sarmalanmış bir listesidir. Her bağımsız değişken tanımı şu şekilde belirtilir:

ArgName:ArgType [= ArgDefaultValue]

Tablosal bağımsız değişkenler için ArgType , tablo tanımıyla (parantez ve sütun adı/tür çiftlerinin listesi) aynı söz dizimine sahiptir ve "herhangi bir tablo şeması" belirten bir tekil (*) eklenmiştir.

Örnek:

Syntax	Giriş bağımsız değişkenleri listesi açıklaması
()	Bağımsız değişken yok
(s:string)	Tür değeri alma adlı s tek skaler bağımsız değişken string
(a:long, b:bool=true)	İkincisinde varsayılan değer bulunan iki skaler bağımsız değişken
(T1:(*), T2(r:real), b:bool)	Üç bağımsız değişken (iki tablosal bağımsız değişken ve bir skaler bağımsız değişken)

Not

Hem tablosal giriş bağımsız değişkenlerini hem de skaler giriş bağımsız değişkenlerini kullanırken, tüm tablosal giriş bağımsız değişkenlerini skaler giriş bağımsız değişkenlerinden önce yerleştirin.

Örnekler

Skaler işlev

Sorguyu çalıştır

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()

Bağımsız değişken içermeyen tablosal işlev

Sorguyu çalıştır

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

Bağımsız değişkenler içeren tablosal işlev

Sorguyu çalıştır

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

Çıkış

x
9
10

Sütun belirtilmemiş bir tablosal giriş kullanan tablosal işlev. Herhangi bir tablo bir işleve geçirilebilir ve işlevin içinde hiçbir tablo sütununa başvuruda bulunılamaz.

Sorguyu çalıştır

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

Çıkış

x
1
2
3

Kullanıcı tanımlı işlevleri bildirme

Kullanıcı tanımlı bir işlevin bildirimi aşağıdakileri sağlar:

• İşlev adı
• İşlev şeması (varsa kabul eder parametreler)
• İşlev gövdesi

Not

İşlevlerin aşırı yüklenmesi desteklenmez. Aynı ada ve farklı giriş şemalarına sahip birden çok işlev oluşturamazsınız.

İpucu

Lambda işlevlerinin adı yoktur ve let deyimi kullanılarak bir ada bağlanır. Bu nedenle, bunlar kullanıcı tanımlı saklı işlevler olarak kabul edilebilir. Örnek: İki bağımsız değişkeni kabul eden bir lambda işlevinin bildirimi ( string çağrılır s ve long çağrılır i). Birincinin (bir sayıya dönüştürdükten sonra) ve ikincisinin çarpımını döndürür. Lambda adıyla filişkilidir:

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

İşlev gövdesi şunları içerir:

• İşlevin dönüş değerini (skaler veya tablosal değer) sağlayan tam olarak bir ifade.
• Kapsamı işlev gövdesininki olan let deyimlerinin herhangi bir sayısı (sıfır veya daha fazla). Belirtilirse, işlevin dönüş değerini tanımlayan ifadeden önce let deyimleri gelmelidir.
• İşlev tarafından kullanılan sorgu parametrelerini bildiren herhangi bir sayıda (sıfır veya daha fazla) sorgu parametresi deyimi. Belirtilirse, işlevin dönüş değerini tanımlayan ifadeden önce olmaları gerekir.

Not

"En üst düzey" sorguda desteklenen diğer sorgu deyimleri , işlev gövdesinde desteklenmez. İki deyim noktalı virgülle ayrılmalıdır.

Kullanıcı tanımlı işlev örnekleri

Aşağıdaki bölümde kullanıcı tanımlı işlevlerin nasıl kullanılacağına ilişkin örnekler gösterilmektedir.

let deyimi kullanan kullanıcı tanımlı işlev

Aşağıdaki örnekte ID adlı parametreyi kabul eden kullanıcı tanımlı bir işlev (lambda) gösterilmektedir. İşlev Test adına bağlıdır ve Test3 tanımının ID parametresini kullandığı üç let deyimini kullanır. Çalıştırıldığında sorgunun çıkışı 70'tir:

Sorguyu çalıştır

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

Parametre için varsayılan değeri tanımlayan kullanıcı tanımlı işlev

Aşağıdaki örnekte üç bağımsız değişken kabul eden bir işlev gösterilmektedir. İkinci ikisinin varsayılan değeri vardır ve çağrı sitesinde mevcut olması gerekmez.

Sorguyu çalıştır

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"

Kullanıcı tanımlı bir işlevi çağırma

Kullanıcı tanımlı bir işlevi çağırma yöntemi, işlevin almayı beklediği bağımsız değişkenlere bağlıdır. Aşağıdaki bölümlerde bağımsız değişkenler olmadan UDF çağırma, skaler bağımsız değişkenlerle UDF çağırma ve tablosal bağımsız değişkenlerle UDF çağırma işlemleri ele alınıyor.

Bağımsız değişkenler olmadan UDF çağırma

Bağımsız değişken içermeyen ve adıyla veya adıyla ve parantez içinde boş bir bağımsız değişken listesiyle çağrılabilen kullanıcı tanımlı bir işlev.

Sorguyu çalıştır

// 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()

Sorguyu çalıştır

// 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())

Skaler bağımsız değişkenlerle UDF çağırma

Bir veya daha fazla skaler bağımsız değişken alan kullanıcı tanımlı bir işlev, işlev adı ve parantez içinde somut bir bağımsız değişken listesi kullanılarak çağrılabilir:

Sorguyu çalıştır

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

Tablosal bağımsız değişkenlerle UDF çağırma

Bir veya daha fazla tablo bağımsız değişkeni (herhangi bir sayıda skaler bağımsız değişkenle) alan ve işlev adı ve parantez içindeki somut bağımsız değişken listesi kullanılarak çağrılabilen kullanıcı tanımlı bir işlev:

Sorguyu çalıştır

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

Bir veya daha fazla tablo bağımsız değişkeni alan ve tablo döndüren kullanıcı tanımlı bir işlevi çağırmak için işlecini invoke de kullanabilirsiniz. İşlevin ilk somut tablo bağımsız değişkeni işlecin kaynağı invoke olduğunda bu işlev yararlıdır:

Sorguyu çalıştır

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(":-)")

Varsayılan değerler

İşlevler, aşağıdaki koşullar altında bazı parametrelerine varsayılan değerler sağlayabilir:

• Yalnızca skaler parametreler için varsayılan değerler sağlanabilir.
• Varsayılan değerler her zaman değişmez değerlerdir (sabitler). Rastgele hesaplamalar olamaz.
• Varsayılan değeri olmayan parametreler her zaman varsayılan değere sahip parametrelerin önündedir.
• Çağıranların, işlev bildirimiyle aynı sırada düzenlenmiş varsayılan değerler olmadan tüm parametrelerin değerini sağlaması gerekir.
• Çağıranların varsayılan değerlere sahip parametreler için değer sağlaması gerekmez, ancak bunu yapabilir.
• Çağıranlar, parametrelerin sırasıyla eşleşmeyen bir sırada bağımsız değişkenler sağlayabilir. Öyleyse, bağımsız değişkenlerini adlandırmaları gerekir.

Aşağıdaki örnek, iki özdeş kayıt içeren bir tablo döndürür. öğesinin ilk çağrısında fbağımsız değişkenler tamamen "karıştırılır", bu nedenle her birine açıkça bir ad verilir:

Sorguyu çalıştır

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"

Çıkış

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

İşlevleri görüntüleme

Bağımsız değişken içermeyen ve tablosal ifade döndüren kullanıcı tanımlı bir işlev görünüm olarak işaretlenebilir. Kullanıcı tanımlı bir işlevi görünüm olarak işaretlemek, joker tablo adı çözümlemesi her gerçekleştirildiğinde işlevin tablo gibi davrandığı anlamına gelir.

Aşağıdaki örnek, ve kullanıcı tanımlı iki işlevi T_viewT_notviewgösterir ve içindeki joker karakter başvurusuyla unionyalnızca ilkinin nasıl çözüldüğünü gösterir:

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

Kısıtlamalar

Aşağıdaki kısıtlamalar geçerlidir:

• Kullanıcı tanımlı işlevler, işlevin çağrıldığı satır bağlamını temel alan toscalar() çağrı bilgilerine geçiremez.
• Tablosal ifade döndüren kullanıcı tanımlı işlevler, satır bağlamıyla değişen bir bağımsız değişkenle çağrılamıyor.
• En az bir tablosal giriş alan bir işlev uzak kümede çağrılamıyor.
• Skaler işlev uzak kümede çağrılamaz.

Kullanıcı tanımlı bir işlevin satır bağlamıyla değişen bir bağımsız değişkenle çağrılabileceği tek yer, kullanıcı tanımlı işlevin yalnızca skaler işlevlerden oluştuğu ve kullanmadığı toscalar()durumlardır.

Örnekler

Desteklenen skaler işlev

Aşağıdaki sorgu, hiçbir tablosal ifadeye başvurmayan skaler bir işlev olduğundan f desteklenir.

Sorguyu çalıştır

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)

Tablosal ifadeye Table1 başvuran ancak geçerli satır bağlamı f(10)başvurusu olmadan çağrılan skaler bir işlev olduğundan aşağıdaki sorgu desteklenirf:

Sorguyu çalıştır

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)

Desteklenmeyen skaler işlev

Tablosal ifadeye Table1başvuran bir skaler işlev olduğundan ve geçerli satır bağlamı f(Column)başvurusuyla çağrıldığından aşağıdaki sorgu desteklenmezf:

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)

Desteklenmeyen tablosal işlev

Skaler değer bekleyen bir bağlamda çağrılan tablosal bir işlev olduğundan aşağıdaki sorgu desteklenmez f .

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)

Şu anda kullanıcı tanımlı işlevler tarafından desteklenmeyen özellikler

Tamlık için, şu anda desteklenmeyen kullanıcı tanımlı işlevler için yaygın olarak istenen bazı özellikler şunlardır:

1. İşlev aşırı yüklemesi: Şu anda bir işlevi aşırı yüklemenin bir yolu yoktur (aynı ada ve farklı giriş şemasına sahip birden çok işlev oluşturmanın bir yolu).

2. Varsayılan değerler: bir işlevin skaler parametresi için varsayılan değer skaler değişmez değer (sabit) olmalıdır.

İlgili içerik

• Depolanan işlevler
• Görünümler