Fungsi yang ditentukan pengguna (UDF) di Microsoft Azure Cosmos DB

BERLAKU UNTUK: SQL API

SQL API menyediakan dukungan untuk fungsi yang ditentukan pengguna (UDF). Dengan UDF skalar, Anda dapat meneruskan nol atau banyak argumen dan mengembalikan satu hasil argumen. API memeriksa setiap argumen untuk menjadi nilai JSON yang legal.

Kasus penggunaan UDF

API memperluas sintaks Bahasa Permintaan Terstruktur untuk mendukung logika aplikasi kustom menggunakan UDF. Anda dapat mendaftarkan UDF dengan Bahasa Permintaan Terstruktur API, dan mereferensikannya dalam kueri Bahasa Permintaan Terstruktur. Tidak seperti prosedur tersimpan dan pemicu, UDF hanya bisa dilihat.

Menggunakan UDF, Anda dapat memperluas bahasa kueri Microsoft Azure Cosmos DB. UDF adalah cara yang bagus untuk mengekspresikan logika bisnis yang kompleks dalam proyeksi kueri.

Namun, kami merekomendasikan untuk menghindari UDF ketika:

  • Fungsi sistem yang ekuivalen sudah ada di Microsoft Azure Cosmos DB. Fungsi sistem akan selalu menggunakan RU yang lebih sedikit daripada UDF yang ekuivalen.
  • UDF adalah satu-satunya filter dalam WHERE klausul permintaan Anda. UDF tidak menggunakan indeks sehingga mengevaluasi UDF akan memerlukan pemuatan dokumen. Menggabungkan predikat filter tambahan yang menggunakan indeks, dikombinasikan dengan UDF, WHEREdalam klausa akan mengurangi jumlah dokumen yang diproses oleh UDF.

Jika Anda harus menggunakan UDF yang sama beberapa kali dalam permintaan, Anda harus mereferensikan UDF dalam subkueri, memungkinkan Anda menggunakan ekspresi JOIN untuk mengevaluasi UDF sekali tetapi mereferensikannya berkali-kali.

Contoh

Contoh berikut mendaftarkan UDF di bawah kontainer item di database Cosmos. Contohnya buat UDF yang bernama REGEX_MATCH. hal itu menerima dua nilai untai (karakter) JSON, input dan, dan memeriksa apakah yang pertama cocok dengan pola yang ditentukan di yang kedua menggunakan fungsi patternstring.match() JavaScript.

       UserDefinedFunction regexMatchUdf = new UserDefinedFunction
       {
           Id = "REGEX_MATCH",
           Body = @"function (input, pattern) {
                      return input.match(pattern) !== null;
                   };",
       };

       UserDefinedFunction createdUdf = client.CreateUserDefinedFunctionAsync(
           UriFactory.CreateDocumentCollectionUri("myDatabase", "families"),
           regexMatchUdf).Result;  

Sekarang, gunakan UDF ini dalam proyeksi permintaan. Anda harus memenuhi syarat UDF dengan awalan pekapeka huruf besar/keciludf. saat melakukan panggilan dari dalam kueri.

    SELECT udf.REGEX_MATCH(Families.address.city, ".*eattle")
    FROM Families

Hasilnya adalah:

    [
      {
        "$1": true
      },
      {
        "$1": false
      }
    ]

Anda dapat menggunakan UDF yang memenuhi syarat dengan udf. awalan di dalam filter, seperti dalam contoh berikut:

    SELECT Families.id, Families.address.city
    FROM Families
    WHERE udf.REGEX_MATCH(Families.address.city, ".*eattle")

Hasilnya adalah:

    [{
        "id": "AndersenFamily",
        "city": "Seattle"
    }]

Intinya, UDF adalah ekspresi skalar valid yang dapat Anda gunakan dalam proyeksi dan filter.

Untuk memperluas daya UDF, lihat contoh lain dengan logika kondisional:

       UserDefinedFunction seaLevelUdf = new UserDefinedFunction()
       {
           Id = "SEALEVEL",
           Body = @"function(city) {
                   switch (city) {
                       case 'Seattle':
                           return 520;
                       case 'NY':
                           return 410;
                       case 'Chicago':
                           return 673;
                       default:
                           return -1;
                    }"
            };

            UserDefinedFunction createdUdf = await client.CreateUserDefinedFunctionAsync(
                UriFactory.CreateDocumentCollectionUri("myDatabase", "families"),
                seaLevelUdf);

Contoh berikut menggunakan UDF:

    SELECT f.address.city, udf.SEALEVEL(f.address.city) AS seaLevel
    FROM Families f

Hasilnya adalah:

     [
      {
        "city": "Seattle",
        "seaLevel": 520
      },
      {
        "city": "NY",
        "seaLevel": 410
      }
    ]

Jika properti yang dimaksud oleh parameter UDF tidak tersedia dalam nilai JSON, parameter dianggap tidak terdefinisi dan pemanggilan UDF dilewati. Demikian pula, jika hasil UDF tidak terdefinisi, itu tidak termasuk di dalam hasil.

Seperti yang ditunjukkan oleh contoh sebelumnya, UDF mengintegrasikan kekuatan bahasa JavaScript dengan SQL API. UDF menyediakan antarmuka yang dapat diprogram yang kaya untuk melakukan logika prosedural bersyarat yang kompleks dengan bantuan kemampuan runtime bahasa umum JavaScript bawaan. Bahasa Permintaan Terstruktur API menyediakan argumen ke UDF untuk setiap item sumber pada tahap pemrosesan klausul WHERE atau SELECT saat ini. Hasilnya dimasukkan dengan mulus dalam alur eksekusi keseluruhan. Singkatnya, UDF adalah alat yang hebat untuk melakukan logika bisnis yang kompleks sebagai bagian dari kueri.

Langkah berikutnya