Scenario: query sui dati IoT con Select AI in APEX

• Prima di iniziare
• Carica, personalizza ed esegui lo script Seleziona impostazione AI in APEX
• Esempi di query
• Procedure ottimali
• Domande frequenti
• Operazioni successive

Queste autorizzazioni sono necessarie per leggere i dati IoT e utilizzare la famiglia di risorse AI generativa.

Allow group <your-group-name> to read <iot-domain> in compartment <compartment-name>

allow dynamic-group <your-group-name> to manage generative-ai-family in compartment <compartment-name>

Amministratori: se non hai familiarità con i criteri, per ulteriori informazioni sull'impostazione dei criteri, vedere Come funzionano i criteri IAM per Oracle Cloud Infrastructure. Per esempi specifici, vedere Dettagli dei criteri per la piattaforma Internet of Things (IoT).

Confermare di avere:

• Accesso configurato all'area di lavoro APEX per l'utente del database IoT.
• Criteri IAM obbligatori in modo da disporre delle autorizzazioni per eseguire query sul database o sull'origine dati di destinazione.

1. Copiare questo esempio di script SQL e salvare lo snippet di codice come file da caricare, ad esempio: select_ai_apex_setup.sql
   Lo script crea un object_list per gli oggetti dello schema IoT, inclusi RAW_DATA, HISTORIZED_DATA, SNAPSHOT_DATA, DIGITAL_TWIN_MODELS, DIGITAL_TWIN_INSTANCES e DIGITAL_TWIN_ADAPTERS.

   Script SQL di esempio

   -- APEX SQL Commands setup script.
   -- Run this code block first in APEX SQL Commands or SQL Scripts.
   
   alter session set nls_language = 'ENGLISH';
   
   declare
     c_domain_short_id       constant varchar2(128)  := '<domain short id in upper case>';
     c_genai_user_ocid       constant varchar2(4000) := 'ocid1.user.oc1..unique';
     c_genai_tenancy_ocid    constant varchar2(4000) := 'ocid1.tenancy.oc1..unique';
     c_genai_fingerprint     constant varchar2(4000) := 'unique';
     c_genai_region          constant varchar2(128)  := 'region';
     c_genai_model           constant varchar2(4000) := 'xai.grok-4.20-reasoning';
     c_genai_credential_name constant varchar2(128)  := 'GENAI_CRED';
     c_genai_profile_name    constant varchar2(128)  := 'GENAI_XAI_GROK_420';
   
     c_private_key constant clob := q'~-----BEGIN PRIVATE KEY-----
   <private key>
   -----END PRIVATE KEY-----~';
   
     type t_name_list is table of varchar2(128);
     l_objects t_name_list := t_name_list(
       'RAW_DATA',
       'HISTORIZED_DATA',
       'REJECTED_DATA',
       'SNAPSHOT_DATA',
       'RAW_COMMAND_DATA',
       'DIGITAL_TWIN_MODEL_SPECS',
       'DIGITAL_TWIN_MODELS',
       'DIGITAL_TWIN_INSTANCES',
       'DIGITAL_TWIN_RELATIONSHIPS',
       'DIGITAL_TWIN_ADAPTERS'
     );
   
     l_iot_owner   varchar2(130);
     l_attributes  clob;
     l_object_list clob := '[';
   begin
     l_iot_owner := upper(trim(c_domain_short_id)) || '__IOT';
   
     begin
       dbms_cloud_ai.drop_profile(c_genai_profile_name);
     exception
       when others then
         null;
     end;
   
     begin
       dbms_cloud.drop_credential(c_genai_credential_name);
     exception
       when others then
         null;
     end;
   
     dbms_cloud.create_credential(
       credential_name => c_genai_credential_name,
       user_ocid       => c_genai_user_ocid,
       tenancy_ocid    => c_genai_tenancy_ocid,
       private_key     => c_private_key,
       fingerprint     => c_genai_fingerprint
     );
   
     for i in 1 .. l_objects.count loop
       if i > 1 then
         l_object_list := l_object_list || ',';
       end if;
       l_object_list := l_object_list ||
         '{"owner":"' || l_iot_owner || '","name":"' || l_objects(i) || '"}';
     end loop;
     l_object_list := l_object_list || ']';
   
     l_attributes := '{' ||
       '"provider":"oci",' ||
       '"credential_name":"' || c_genai_credential_name || '",' ||
       '"region":"' || c_genai_region || '",' ||
       '"oci_compartment_id":"' || c_genai_tenancy_ocid || '",' ||
       '"model":"' || c_genai_model || '",' ||
       '"annotations":false,' ||
       '"comments":true,' ||
       '"object_list":' || l_object_list ||
     '}';
   
     dbms_cloud_ai.create_profile(
       profile_name => c_genai_profile_name,
       attributes   => l_attributes
     );
   end;
   /

2. In APEX, selezionare SQL Workshop, quindi Script SQL.

3. Selezionare Carica per aggiungere il file select_ai_apex_setup.sql ad APEX.
4. Selezionare Modifica per aggiornare lo script con variabili per l'ambiente in uso.
   Sostituire questi elementi con i valori per l'ambiente in uso:

   c_domain_short_id       constant varchar2(128)  := '<DOMAIN_SHORT_ID>';
   c_genai_region          constant varchar2(128)  := '<region>';
   c_genai_model           constant varchar2(4000) := 'xai.grok-4.20-reasoning';
   c_genai_profile_name    constant varchar2(128)  := 'GENAI_XAI_GROK_420';

   Questo script utilizza il servizio GenAI che utilizza queste costanti e "provider": "oci", se si desidera utilizzare un modello diverso, è possibile aggiornare questi valori nello script. Vedere Configura selezione AI per utilizzare i provider AI supportati.
5. Sostituire il testo select e prompt con la domanda a cui l'intelligenza artificiale deve rispondere.

   Sostituire profile_name con il profilo AI su cui si desidera eseguire l'operazione.

   select 'GENAI_XAI_GROK_420' as profile_name,
          upper(trim('IN2AHR4KWKIRC')) || '__IOT' as iot_owner,
          'Setup complete' as status
   from dual;
   
   
   select 'which digital twin instances with the model spec uri dtmi:com:oracle:iot:sample:hvac:iot-domain-short-id' as prompt_text,
          dbms_lob.substr(
            replace(
              replace(
                dbms_cloud_ai.generate(
                  prompt       => 'which model spec uri has exactly two digital twin instances and both in active state',
                  profile_name => 'GENAI_XAI_GROK_420',

6. Selezionare Esegui, quindi Esegui ora.
7. Selezionare Visualizza, quindi Vai scorrere verso il basso per rivedere l'istruzione SQL generata in base alla domanda IoT nel prompt.
8. Copia l'SQL generato, seleziona SQL Workshop, quindi seleziona Comandi SQL.
9. Incollare l'SQL generato e selezionare Esegui per eseguire l'istruzione SQL generata.
10. Per questo prompt, i risultati mostrano l'OCID dell'istanza gemella digitale, il relativo nome visualizzazione, la temperatura e i valori di umidità.

Utilizzare questi esempi come prompt di avvio in comandi SQL APEX o SQLcl. In APEX, utilizzare il testo tra virgolette come valore prompt.

Trova la telemetria più recente per un dispositivo

'Show the most recent telemetry readings for device <device-id>';

Trova l'istanza HVAC più calda

'Which HVAC instance and model has the highest temperature in the last 1 hour?';

Trova errori recenti del dispositivo

'Which devices reported errors in the last 24 hours?';

Riepiloga l'umidità per dispositivo

'Show average humidity by device for the last 7 days';

Trova dispositivi senza telemetria oggi, identifica i dispositivi che potrebbero essere offline o configurati in modo errato

'List devices that have not sent telemetry today';

Riepiloga letture di fabbrica anomale

'Summarize abnormal readings for factory floor sensors this week';

Conta record dati storici

'How many historized data records are in the IoT domain?';

Conta istanze digital twin con cronologia

'How many digital twin instances are in historized data?';

Trovare l'istanza di dati raw più utilizzata

'What instance sent most of the raw data last day?';

Conta adattatori nel dominio

'How many adapters are in the domain?';

Contare le istanze nel dominio

'How many instances are in the domain?';

Numero medio di istanze per modello

'What is the average number of instances that implement one model?';

Controlla dati rifiutati

'Is there rejected data in the domain?';

Velocità di inclusione dati non elaborati per ora

'What is the average raw data ingestion rate per hour last day, each hour?';

Dimensione payload record raw

'What is the average and max raw record payload size?';

Dimensione payload record storicizzato

'What is the average and max historized record payload size?';

Andamento della temperatura per ora

'Show the average temperature by hour for the last day';

Raggruppa errori dispositivo per tipo

'Show devices with error events in the last 7 days grouped by error type';

• Utilizzare prima showsql per esaminare l'istruzione SQL generata prima dell'esecuzione.
• Fai una domanda IoT alla volta.
• Includere il tipo di dispositivo, il nome della metrica, l'URI della specifica del modello o l'intervallo di tempo quando è importante.
• Utilizzare nomi di profilo separati per modelli separati, ad esempio OpenAI, GOOGLE_GEMINI o CLAUDE.

• Configurare una connessione diretta al database del dominio IoT.
• Rivedere lo schema di database del dominio IoT.
• Impostare una connessione al server MCP IoT.