Kueri graf kembar Azure Digital Twins

Artikel ini menawarkan contoh kueri dan instruksi untuk menggunakan bahasa kueri Azure Digital Twins untuk meminta informasi pada grafik kembar Anda. (Untuk pengenalan bahasa kueri, lihat Bahasa kueri.)

Artikel berisi kueri sampel yang menggambarkan struktur bahasa kueri dan operasi kueri umum untuk kembar digital. Ini juga menjelaskan cara menjalankan kueri setelah Anda menulisnya, menggunakan Api Kueri Azure Digital Twins atau SDK.

Catatan

Jika Anda menjalankan kueri sampel berikut dengan panggilan API atau SDK, Anda perlu mengerucutkan teks kueri menjadi satu baris.

Dokumentasi rujukan

Referensi bahasa kueri dapat ditemukan di bawah Referensi di daftar isi kiri untuk dokumentasi Azure Digital Twins. Anda juga dapat langsung masuk ke bagian referensi menggunakan tautan di bawah ini:

• Klausul
  • SELECT
  • DARI
  • PERTANDINGAN
  • IKAT
  • WHERE
• Fungsi
• Operator
• Kata kunci tercadang

Tampilkan semua kembar digital

Berikut adalah kueri dasar yang mengembalikan daftar semua kembar digital dalam instans:

SELECT * FROM DIGITALTWINS

Kueri menurut properti

Dapatkan kembar digital berdasarkan properti (termasuk ID dan metadata):

SELECT  *
FROM DIGITALTWINS T  
WHERE T.firmwareVersion = '1.1'
AND T.$dtId in ['123', '456']
AND T.Temperature = 70

Seperti yang ditunjukkan pada kueri sebelumnya, ID kembar digital dikueri menggunakan bidang $dtIdmetadata .

Kiat

Jika Anda menggunakan Cloud Shell untuk menjalankan kueri dengan bidang metadata yang dimulai dengan $, Anda harus menghindari $ dengan garis miring terbalik untuk memberi tahu Cloud Shell bahwa itu bukan variabel dan harus digunakan sebagai harfiah dalam teks kueri.

Anda juga bisa mendapatkan anak kembar berdasarkan apakah properti tertentu didefinisikan. Berikut adalah kueri yang mendapatkan kembar yang memiliki properti yang ditentukan Location :

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Kueri ini dapat membantu Anda mendapatkan kembarnya berdasarkan propertinya tag, seperti yang dijelaskan dalam Menambahkan tag ke kembar digital. Berikut adalah kueri yang menandai semua kembar dengan red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Anda juga bisa mendapatkan anak kembar berdasarkan jenis properti. Berikut adalah kueri yang mendapatkan kembar yang propertinya Temperature adalah angka:

SELECT * FROM DIGITALTWINS T WHERE IS_NUMBER(T.Temperature)

Properti Peta Kueri

Jika properti berjenis Mapkompleks , Anda bisa menggunakan kunci peta dan nilai langsung dalam kueri, seperti ini:

SELECT * FROM DIGITALTWINS T WHERE T.<propertyName>.<mapKey> = '<mapValue>'

Jika kunci peta dimulai dengan karakter numerik, Anda perlu membungkus kunci dalam tanda kurung siku ganda ([[<mapKey>]]) untuk melepaskannya dalam kueri, mirip dengan strategi untuk mengkueri dengan kata kunci yang dipesan.

Kueri menurut model

Operator IS_OF_MODEL dapat digunakan untuk memfilter berdasarkan model kembar.

Ini mempertimbangkan pewarisan dan versi model, dan mengevaluasi menjadi true untuk twin tertentu jika twin memenuhi salah satu kondisi ini:

• Model kembar secara langsung mengimplementasikan model yang disediakan untuk IS_OF_MODEL(), dan nomor versi model pada model kembar lebih besar dari atau sama dengan nomor versi model yang disediakan.
• Si kembar mengimplementasikan model yang memperluas model yang disediakan untuk IS_OF_MODEL(), dan nomor versi model si kembar yang diperluas lebih besar dari atau sama dengan nomor versi model yang disediakan.

Jadi, misalnya, jika Anda mengajukan kueri untuk kembar model dtmi:example:widget;4, kueri akan mengembalikan semua kembar berdasarkan versi 4 atau lebih tinggi dari model widget, serta kembar dari model mana pun yang mewarisi dari widget berdasarkan versi 4 atau lebih tinggi.

IS_OF_MODEL dapat mengambil beberapa parameter yang berbeda, dan bagian ini lainnya didedikasikan untuk berbagai opsi kelebihan beban.

Penggunaan paling sederhana IS_OF_MODEL hanya membutuhkan twinTypeName parameter: IS_OF_MODEL(twinTypeName). Berikut adalah contoh kueri yang meneruskan nilai dalam parameter ini:

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1')

Untuk menentukan koleksi kembar yang akan dicari saat ada lebih dari satu (seperti saat JOIN digunakan), tambahkan parameter twinCollection: IS_OF_MODEL(twinCollection, twinTypeName). Berikut adalah contoh kueri yang menambahkan nilai untuk parameter ini:

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1')

Untuk melakukan kecocokan persis, tambahkan exact parameter: IS_OF_MODEL(twinTypeName, exact). Berikut adalah contoh kueri yang menambahkan nilai untuk parameter ini:

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1', exact)

Anda juga dapat menyampaikan ketiga argumen bersama-sama: IS_OF_MODEL(twinCollection, twinTypeName, exact). Berikut adalah contoh kueri yang menentukan nilai untuk ketiga parameter:

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1', exact)

Kueri menurut hubungan

Untuk mengkueri berdasarkan hubungan kembar digital, bahasa kueri Azure Digital Twins menyediakan sintaks khusus.

Hubungan ditarik ke dalam lingkup kueri dalam klausa FROM. Tidak seperti dalam bahasa jenis SQL "klasik", setiap ekspresi dalam klausul FROM bukanlah tabel; melainkan, klausul FROM mengungkapkan traversal hubungan lintas entitas. Untuk menjelajahi hubungan, Azure Digital Twins menggunakan versi khusus dari JOIN.

Ingat bahwa dengan kemampuan model Azure Digital Twins, hubungan tidak ada secara independen dari kembar. Hasilnya adalah bahwa hubungan tidak dapat ditanyakan secara independen dan harus terikat dengan kembaran. Untuk mencerminkan fakta ini, kata kunci RELATED digunakan dalam klausul JOIN untuk menarik serangkaian jenis hubungan tertentu yang berasal dari kumpulan kembar. Kueri kemudian harus memfilter dalam WHERE klausa, untuk menunjukkan kembaran tertentu mana yang akan digunakan dalam kueri hubungan (menggunakan nilai kembar $dtId ).

Bagian berikut ini memberikan contoh seperti apa tampilan ini.

Kueri relasi dasar

Berikut adalah sampel kueri berbasis hubungan. Cuplikan kode ini memilih semua kembar digital yang memiliki properti ID dari ABC, dan semua kembar digital yang terkait dengan kembar digital ini melalui hubungan contains.

SELECT T, CT
FROM DIGITALTWINS T
JOIN CT RELATED T.contains
WHERE T.$dtId = 'ABC'

Jenis hubungan (contains dalam contoh sebelumnya) ditunjukkan menggunakan bidang hubungan dari definisi DTDL-nyaname.

Catatan

Pengembang tidak perlu menghubungkan JOIN ini dengan nilai kunci dalam klausul WHERE (atau menentukan nilai kunci langsung di definisi JOIN). Sistem secara otomatis menghitung korelasi ini, karena properti hubungan itu sendiri mengidentifikasi entitas target.

Kueri menurut sumber atau target hubungan

Anda bisa menggunakan struktur kueri hubungan untuk mengidentifikasi kembaran digital yang menjadi sumber atau target hubungan.

Misalnya, Anda dapat memulai dengan kembaran sumber dan mengikuti hubungannya untuk menemukan kembaran target dari hubungan tersebut. Berikut adalah contoh kueri yang menemukan kembar target hubungan feeds yang berasal dari kembar sumber kembar.

SELECT target 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE source.$dtId = 'source-twin'

Anda juga dapat mulai dari target hubungan dan melacak hubungan ke belakang untuk menemukan kembaran sumber. Berikut adalah contoh kueri yang menemukan kembar sumber dari suatu hubungan ke kembar target.

SELECT source 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE target.$dtId = 'target-twin'

Mengkueri properti hubungan

Mirip dengan cara kembar digital memiliki properti yang dijelaskan melalui DTDL, hubungan juga dapat memiliki properti. Anda dapat melakukan query terhadap kembar berdasarkan atribut hubungan mereka. Bahasa kueri Azure Digital Twins memungkinkan pemfilteran dan proyeksi hubungan, dengan menetapkan alias ke hubungan dalam klausa JOIN.

Sebagai contoh, pertimbangkan servicedBy hubungan yang memiliki reportedCondition properti. Dalam kueri berikut, hubungan ini diberi alias R untuk mereferensikan propertinya.

SELECT T, SBT, R
FROM DIGITALTWINS T
JOIN SBT RELATED T.servicedBy R
WHERE T.$dtId = 'ABC'
AND R.reportedCondition = 'clean'

Dalam contoh sebelumnya, perhatikan bagaimana reportedCondition merupakan properti dari hubungan servicedBy itu sendiri (BUKAN dari kembar digital tertentu yang memiliki hubungan servicedBy).

Kueri dengan beberapa JOIN

Hingga lima JOIN didukung dalam satu kueri, yang memungkinkan Anda melintasi beberapa tingkat hubungan sekaligus.

Untuk mengkueri beberapa tingkat hubungan, gunakan satu pernyataan FROM yang diikuti oleh pernyataan JOIN N, di mana pernyataan JOIN menyatakan hubungan pada hasil dari pernyataan FROM atau JOIN sebelumnya.

Berikut adalah contoh kueri dengan banyak penggabungan, yang mendapatkan semua bola lampu yang terdapat di panel lampu dalam ruangan 1 dan 2.

SELECT LightBulb
FROM DIGITALTWINS Room
JOIN LightPanel RELATED Room.contains
JOIN LightBulb RELATED LightPanel.contains
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb ;1')
AND Room.$dtId IN ['room1', 'room2']

Menghitung barang

Anda bisa menghitung jumlah item dalam kumpulan hasil menggunakan klausa Select COUNT:

SELECT COUNT()
FROM DIGITALTWINS

Tambahkan klausa WHERE untuk menghitung jumlah item yang memenuhi kriteria tertentu. Contoh berikut menunjukkan penghitungan dengan filter yang diterapkan berdasarkan jenis model kembar. Untuk informasi selengkapnya tentang sintaks ini, lihat Kueri menurut model.

SELECT COUNT()
FROM DIGITALTWINS
WHERE IS_OF_MODEL('dtmi:sample:Room;1')

SELECT COUNT()
FROM DIGITALTWINS c
WHERE IS_OF_MODEL('dtmi:sample:Room;1') AND c.Capacity > 20

Anda juga dapat menggunakan COUNT bersama dengan klausa JOIN. Berikut adalah kueri yang menghitung semua bola lampu yang terdapat di panel lampu kamar 1 dan 2:

SELECT COUNT()  
FROM DIGITALTWINS Room  
JOIN LightPanel RELATED Room.contains  
JOIN LightBulb RELATED LightPanel.contains  
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')  
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb;1')  
AND Room.$dtId IN ['room1', 'room2']

Hasil filter: pilih item teratas

Anda dapat memilih beberapa item "atas" dalam kueri menggunakan klausa Select TOP.

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Hasil filter: tentukan kembalian set dengan proyeksi

Dengan menggunakan proyeksi dalam SELECT pernyataan, Anda dapat memilih kolom mana yang dikembalikan kueri. Proyeksi sekarang didukung untuk properti primitif dan properti kompleks. Untuk informasi selengkapnya tentang proyeksi dengan Azure Digital Twins, lihat dokumentasi referensi klausa SELECT.

Berikut adalah contoh kueri yang menggunakan proyeksi untuk menampilkan kembar dan hubungan. Kueri berikut memproyeksikan Konsumen, Pabrik, dan Edge dari skenario di mana Pabrik dengan ID ABC terkait dengan Konsumen melalui hubungan Factory.customer, dan hubungan itu disajikan sebagai Edge.

SELECT Consumer, Factory, Edge
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Anda juga dapat menggunakan proyeksi untuk mengembalikan properti kembar. Kueri berikut memproyeksikan properti Name dari Konsumen yang dihubungkan dengan Pabrik yang memiliki ID ABC melalui hubungan Factory.customer.

SELECT Consumer.name
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Anda juga dapat menggunakan proyeksi untuk mengembalikan properti hubungan. Seperti dalam contoh sebelumnya, kueri berikut memproyeksikan properti Name Konsumen yang terkait dengan Pabrik dengan ID ABC melalui hubungan Factory.customer; tetapi sekarang juga menghasilkan dua properti dari hubungan tersebut, prop1 dan prop2. Kueri mengembalikan kedua properti tersebut dengan memberikan nama pada hubungan Edge serta mengumpulkan propertinya.

SELECT Consumer.name, Edge.prop1, Edge.prop2, Factory.area
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Anda juga dapat menggunakan alias untuk menyederhanakan kueri dengan proyeksi.

Kueri berikut ini melakukan operasi yang sama seperti contoh sebelumnya, tetapi alias nama properti menjadi consumerName, first, second, dan factoryArea.

SELECT Consumer.name AS consumerName, Edge.prop1 AS first, Edge.prop2 AS second, Factory.area AS factoryArea
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Berikut adalah kueri serupa yang mengkueri kumpulan yang sama dengan kueri sebelumnya, tetapi hanya memproyeksikan Consumer.name properti sebagai consumerName, dan memproyeksikan Pabrik secara utuh sebagai duplikat.

SELECT Consumer.name AS consumerName, Factory
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Membuat kueri yang efisien dengan operator IN

Anda dapat secara signifikan mengurangi jumlah kueri yang Anda butuhkan dengan membuat array kembar dan kueri dengan operator IN.

Misalnya, pertimbangkan skenario di mana Bangunan berisi Lantai dan Lantai berisi Kamar. Untuk mencari kamar di dalam gedung yang panas, salah satu caranya adalah dengan mengikuti langkah-langkah ini.

1. Temukan lantai di gedung berdasarkan hubungan contains.

   SELECT Floor
   FROM DIGITALTWINS Building
   JOIN Floor RELATED Building.contains
   WHERE Building.$dtId = @buildingId
   

2. Untuk menemukan ruang, alih-alih mempertimbangkan lantai satu per satu dan menjalankan JOIN kueri untuk menemukan ruang untuk masing-masing ruang, Anda dapat mengkueri dengan kumpulan lantai di gedung (dinamai Floor dalam kueri berikut).

   Di aplikasi klien

   var floors = "['floor1','floor2', ..'floorn']"; 
   

   Dalam kueri:

   SELECT Room
   FROM DIGITALTWINS Floor
   JOIN Room RELATED Floor.contains
   WHERE Floor.$dtId IN ['floor1','floor2', ..'floorn']
   AND Room. Temperature > 72
   AND IS_OF_MODEL(Room, 'dtmi:com:contoso:Room;1')
   

Contoh kueri gabungan lainnya

Anda dapat menggabungkan salah satu jenis kueri yang dijelaskan sebelumnya menggunakan operator kombinasi untuk menyertakan detail selengkapnya dalam satu kueri. Berikut adalah beberapa contoh kueri majemuk lainnya yang mengkueri lebih dari satu jenis pendeskripsi kembar sekaligus.

• Dari perangkat yang dimiliki Ruang 123, kembalikan perangkat MxChip yang melayani peran Operator

  SELECT device
  FROM DIGITALTWINS space
  JOIN device RELATED space.has
  WHERE space.$dtid = 'Room 123'
  AND device.$metadata.model = 'dtmi:contoso:com:DigitalTwins:MxChip:3'
  AND has.role = 'Operator'
  

• Temukan kembar yang memiliki hubungan bernama Contains dengan kembar lainnya yang memiliki ID id1

  SELECT Room
  FROM DIGITALTWINS Room
  JOIN Thermostat RELATED Room.Contains
  WHERE Thermostat.$dtId = 'id1'
  

• Dapatkan semua kamar dari model kamar ini yang berada di lantai11

  SELECT Room
  FROM DIGITALTWINS Floor
  JOIN Room RELATED Floor.Contains
  WHERE Floor.$dtId = 'floor11'
  AND IS_OF_MODEL(Room, 'dtmi:contoso:com:DigitalTwins:Room;1')
  

Jalankan kueri dengan API

Setelah Anda memutuskan string kueri, Anda menjalankannya dengan melakukan panggilan ke API Kueri.

Anda dapat menghubungi API secara langsung, atau menggunakan salah satu SDK yang tersedia untuk Azure Digital Twins.

Cuplikan kode berikut mengilustrasikan panggilan .NET (C#) SDK dari aplikasi klien:

// Run a query for all twins   
string query = "SELECT * FROM DIGITALTWINS";
AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>(query);

Kueri yang digunakan dalam panggilan ini mengembalikan daftar kembar digital, yang diwakili contoh sebelumnya dengan objek BasicDigitalTwin . Jenis pengembalian data Anda untuk setiap kueri bergantung pada istilah apa yang Anda tentukan dengan SELECT pernyataan:

• Kueri yang dimulai dengan SELECT * FROM ... mengembalikan daftar kembar digital (yang dapat diserialisasikan sebagai BasicDigitalTwin objek, atau jenis kembar digital kustom lainnya yang mungkin Anda buat).
• Kueri yang dimulai dalam format SELECT <A>, <B>, <C> FROM ... akan mengembalikan sebuah kamus dengan kunci <A>, <B>, dan <C>.
• Format pernyataan SELECT lain dapat dibuat untuk mengembalikan data kustom. Anda dapat mempertimbangkan untuk membuat kelas Anda sendiri untuk menangani himpunan hasil yang disesuaikan.

Kueri dengan pengaturan halaman

Kueri mendukung pemanggilan data per halaman. Berikut adalah contoh lengkap menggunakan BasicDigitalTwin sebagai jenis hasil kueri dengan penanganan kesalahan dan penomoran:

AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>("Select * From DigitalTwins");
try
{
    await foreach (BasicDigitalTwin twin in result)
    {
        // You can include your own logic to print the result
        // The logic below prints the twin's ID and contents
        Console.WriteLine($"Twin ID: {twin.Id} \nTwin data");
        foreach (KeyValuePair<string, object> kvp in twin.Contents)
        {
            Console.WriteLine($"{kvp.Key}  {kvp.Value}");
        }
    }
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Error {ex.Status}, {ex.ErrorCode}, {ex.Message}");
    throw;
}

Langkah berikutnya

Pelajari selengkapnya tentang API dan SDK Azure Digital Twins, termasuk API Kueri yang digunakan untuk menjalankan kueri dari artikel ini.