Creare query continue

Questo documento descrive come eseguire una query continua in BigQuery.

Le query continue di BigQuery sono istruzioni SQL eseguite continuamente. Le query continue ti consentono di analizzare i dati in entrata in BigQuery in tempo reale, quindi di esportare i risultati in Bigtable o Pub/Sub oppure di scrivere i risultati in una tabella BigQuery.

Scegli un tipo di account

Puoi creare ed eseguire un job di query continua utilizzando un account utente oppure puoi creare un job di query continua utilizzando un account utente e poi eseguirlo utilizzando un account di servizio. Devi utilizzare un account di servizio per eseguire una query continua che esporterà i risultati in un argomento Pub/Sub.

Quando utilizzi un account utente, viene eseguita una query continua per un massimo di due giorni. Quando utilizzi un account di servizio, una query continua viene eseguita per un massimo di 150 giorni. Per ulteriori informazioni, consulta Autorizzazione.

Autorizzazioni obbligatorie

Questa sezione descrive le autorizzazioni necessarie per creare ed eseguire una query continua. In alternativa ai ruoli IAM (Identity and Access Management) elencati, puoi ottenere le autorizzazioni richieste tramite ruoli personalizzati.

Autorizzazioni per l'utilizzo di un account utente

Questa sezione fornisce informazioni sui ruoli e sulle autorizzazioni necessarie per creare ed eseguire una query continua utilizzando un account utente.

Per creare un job in BigQuery, l'account utente deve disporre dell'autorizzazione IAM bigquery.jobs.create. Ciascuno dei seguenti ruoli IAM concede l'autorizzazione bigquery.jobs.create:

• Utente BigQuery (roles/bigquery.user)
• Utente job BigQuery (roles/bigquery.jobUser)
• Amministratore BigQuery (roles/bigquery.admin)

Per esportare i dati da una tabella BigQuery, l'account utente deve disporre dell'bigquery.tables.exportautorizzazione IAM . Ciascuno dei seguenti ruoli IAM concede l'autorizzazione bigquery.tables.export:

• Visualizzatore dei dati BigQuery (roles/bigquery.dataViewer)
• BigQuery Data Editor (roles/bigquery.dataEditor)
• Proprietario dei dati BigQuery (roles/bigquery.dataOwner)
• Amministratore BigQuery (roles/bigquery.admin)

Per aggiornare i dati in una tabella BigQuery, l'account utente deve disporre dell'autorizzazione IAM bigquery.tables.updateData. Ciascuno dei seguenti ruoli IAM concede l'autorizzazione bigquery.tables.updateData:

• BigQuery Data Editor (roles/bigquery.dataEditor)
• Proprietario dei dati BigQuery (roles/bigquery.dataOwner)
• Amministratore BigQuery (roles/bigquery.admin)

Se l'account utente deve attivare le API richieste per il tuo caso d'uso di query continue, deve disporre del ruolo Amministratore utilizzo servizio (roles/serviceusage.serviceUsageAdmin).

Autorizzazioni quando si utilizza un account di servizio

Questa sezione fornisce informazioni sui ruoli e sulle autorizzazioni richiesti dall'account utente che crea la query continua e dall'account di servizio che esegue la query continua.

Autorizzazioni dell'account utente

Per creare un job in BigQuery, l'account utente deve disporre dell'autorizzazione IAM bigquery.jobs.create. Ciascuno dei seguenti ruoli IAM concede l'autorizzazione bigquery.jobs.create:

• Utente BigQuery (roles/bigquery.user)
• Utente job BigQuery (roles/bigquery.jobUser)
• Amministratore BigQuery (roles/bigquery.admin)

Per inviare un job che viene eseguito utilizzando un account di servizio, l'account utente deve disporre del ruolo Utente account di servizio (roles/iam.serviceAccountUser). Se utilizzi lo stesso account utente per creare l'account di servizio, questo deve disporre del ruolo Amministratore account di servizio (roles/iam.serviceAccountAdmin). Per informazioni su come limitare l'accesso di un utente a un singolo account di servizio, piuttosto che a tutti gli account di servizio all'interno di un progetto, consulta Concedere un singolo ruolo.

Se l'account utente deve attivare le API richieste per il tuo caso d'uso di query continue, deve disporre del ruolo Amministratore utilizzo servizio (roles/serviceusage.serviceUsageAdmin).

Autorizzazioni service account

Per esportare i dati da una tabella BigQuery, l'account di servizio deve avere l'autorizzazione IAM bigquery.tables.export. Ciascuno dei seguenti ruoli IAM concede l'autorizzazione bigquery.tables.export:

• Visualizzatore dei dati BigQuery (roles/bigquery.dataViewer)
• BigQuery Data Editor (roles/bigquery.dataEditor)
• Proprietario dei dati BigQuery (roles/bigquery.dataOwner)
• Amministratore BigQuery (roles/bigquery.admin)

• BigQuery Data Editor (roles/bigquery.dataEditor)
• Proprietario dei dati BigQuery (roles/bigquery.dataOwner)
• Amministratore BigQuery (roles/bigquery.admin)

Prima di iniziare

1. In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.

   Go to project selector

2. Make sure that billing is enabled for your Trusted Cloud project.

3. Enable the BigQuery API.

   Enable the API

Crea una prenotazione

Crea una prenotazione per la versione Enterprise o Enterprise Plus, poi crea un'assegnazione della prenotazione con un tipo di job CONTINUOUS. Questa prenotazione può utilizzare la scalabilità automatica. Esistono limitazioni delle prenotazioni che si applicano alle assegnazioni delle prenotazioni per le query continue.

Esporta in Pub/Sub

Per esportare i dati in Pub/Sub sono Trusted Cloud by S3NS necessarie API, autorizzazioni IAM e risorse aggiuntive. Per saperne di più, consulta la sezione Esportare in Pub/Sub.

Embedding di attributi personalizzati come metadati nei messaggi Pub/Sub

Puoi utilizzare gli attributi Pub/Sub per fornire informazioni aggiuntive sul messaggio, come priorità, origine, destinazione o metadati aggiuntivi. Puoi anche utilizzare gli attributi per filtrare i messaggi nell'abbonamento.

All'interno di un risultato di query continua, se una colonna è denominata _ATTRIBUTES, i relativi valori vengono copiati negli attributi del messaggio Pub/Sub. I campi forniti in _ATTRIBUTES vengono utilizzati come chiavi degli attributi.

La colonna _ATTRIBUTES deve essere di tipo JSON, nel formato ARRAY<STRUCT<STRING, STRING>> o STRUCT<STRING>.

Per un esempio, consulta esportare i dati in un argomento Pub/Sub.

Esporta in Bigtable

Per esportare i dati in Bigtable sono necessarie API, autorizzazioni IAM e Trusted Cloud risorse aggiuntive. Per ulteriori informazioni, consulta Esportare in Bigtable.

Scrivere dati in una tabella BigQuery

Puoi scrivere dati in una tabella BigQuery utilizzando un istruzione INSERT.

Utilizzare le funzioni di IA

Per utilizzare una funzione di AI supportata in una query continua sono necessarie API, autorizzazioni IAM e Trusted Cloud risorse aggiuntive. Per ulteriori informazioni, consulta uno dei seguenti argomenti in base al tuo caso d'uso:

• Generare testo utilizzando la funzione ML.GENERATE_TEXT
• Genera embedding di testo utilizzando la funzione ML.GENERATE_EMBEDDING
• Comprendere il testo con la funzione ML.UNDERSTAND_TEXT
• Tradurre il testo con la funzione ML.TRANSLATE

Quando utilizzi una funzione AI in una query continua, valuta se l'output della query rimarrà entro la quota per la funzione. Se superi la quota, potresti dover gestire separatamente i record che non vengono elaborati.

Specifica un punto di partenza

Devi utilizzare la funzione APPENDS nella clausola FROM di una query continua per specificare i dati più antichi da elaborare. Ad esempio, APPENDS(TABLE my_table, CURRENT_TIMESTAMP() - INTERVAL 10 MINUTE) indica a BigQuery di elaborare i dati aggiunti alla tabella my_table al massimo 10 minuti prima dell'inizio della query continua. I dati aggiunti a my_table vengono elaborati non appena arrivano. Non viene imposto alcun ritardo nell'elaborazione dei dati. Non fornire un argomento end_timestamp alla funzione APPENDS quando la utilizzi in una query continua.

L'esempio seguente mostra come avviare una query continua da un determinato momento nel tempo utilizzando la funzione APPENDS, quando esegui una query su una tabella BigQuery che riceve informazioni in streaming sulle corse in taxi:

EXPORT DATA
  OPTIONS (format = 'CLOUD_PUBSUB',
    uri = 'https://pubsub.googleapis.com/projects/myproject/topics/taxi-real-time-rides') AS (
  SELECT
    TO_JSON_STRING(STRUCT(ride_id,
        timestamp,
        latitude,
        longitude)) AS message
  FROM
    APPENDS(TABLE `myproject.real_time_taxi_streaming.taxirides`,
      -- Configure the APPENDS TVF start_timestamp to specify when you want to
      -- start processing data using your continuous query.
      -- This example starts processing at 10 minutes before the current time.
      CURRENT_TIMESTAMP() - INTERVAL 10 MINUTE)
  WHERE
    ride_status = 'enroute');

Specifica un punto di partenza precedente all'ora corrente

Se vuoi elaborare i dati precedenti al momento corrente, puoi utilizzare la funzione APPENDS per specificare un punto di inizio precedente per la query. Il punto di partenza specificato deve rientrare nella finestra di spostamento temporale per la tabella da cui stai selezionando. Per impostazione predefinita, la finestra di spostamento cronologico copre gli ultimi sette giorni.

Per includere i dati al di fuori della finestra di viaggio nel tempo, utilizza una query standard per inserire o esportare i dati fino a un determinato punto nel tempo, quindi avvia una query continua da quel punto nel tempo.

Esempio

L'esempio seguente mostra come caricare i dati precedenti da una tabella BigQuery che riceve informazioni in streaming sulle corse in taxi fino a un determinato momento in una tabella e poi avviare una query continua dal punto di taglio per i dati precedenti.

1. Esegui una query standard per eseguire il backfill dei dati fino a un determinato punto nel tempo:

   INSERT INTO `myproject.real_time_taxi_streaming.transformed_taxirides`
   SELECT
     timestamp,
     meter_reading,
     ride_status,
     passenger_count,
     ST_Distance(
       ST_GeogPoint(pickup_longitude, pickup_latitude),
       ST_GeogPoint(dropoff_longitude, dropoff_latitude)) AS euclidean_trip_distance,
       SAFE_DIVIDE(meter_reading, passenger_count) AS cost_per_passenger
   FROM `myproject.real_time_taxi_streaming.taxirides`
     -- Include all data inserted into the table up to this point in time.
     -- This timestamp must be within the time travel window.
     FOR SYSTEM_TIME AS OF '2025-01-01 00:00:00 UTC'
   WHERE
     ride_status = 'dropoff';

2. Esegui una query continua dal punto in cui la query è stata interrotta:

   INSERT INTO `myproject.real_time_taxi_streaming.transformed_taxirides`
   SELECT
     timestamp,
     meter_reading,
     ride_status,
     passenger_count,
     ST_Distance(
       ST_GeogPoint(pickup_longitude, pickup_latitude),
       ST_GeogPoint(dropoff_longitude, dropoff_latitude)) AS euclidean_trip_distance,
       SAFE_DIVIDE(meter_reading, passenger_count) AS cost_per_passenger
   FROM
     APPENDS(TABLE `myproject.real_time_taxi_streaming.taxirides`,
       -- Configure the APPENDS TVF start_timestamp to start processing
       -- data right where the batch query left off.
       -- This timestamp must be within the time travel window.
       TIMESTAMP '2025-01-01 00:00:00 UTC' + INTERVAL 1 MICROSECOND)
   WHERE
     ride_status = 'dropoff';

Eseguire una query continua utilizzando un account utente

Questa sezione descrive come eseguire una query continua utilizzando un account utente. Una volta avviata la query continua, puoi chiudere la Trusted Cloud console, la finestra del terminale o l'applicazione senza interrompere l'esecuzione della query. Una query continua eseguita da un account utente viene eseguita per un massimo di due giorni e poi si interrompe automaticamente. Per continuare a elaborare i nuovi dati in arrivo, avvia una nuova query continua e specifica un punto di partenza. Per automatizzare questa procedura, consulta Rieseguire le query non riuscite.

Per eseguire una query continua:

curl --request POST \
  "https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/jobs" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Content-Type: application/json; charset=utf-8" \
  --data '{"configuration":{"query":{"query":"QUERY","useLegacySql":false,"continuous":true}}}' \
  --compressed

Esegui una query continua utilizzando un account di servizio

Questa sezione descrive come eseguire una query continua utilizzando un account di servizio. Una volta avviata la query continua, puoi chiudere la Trusted Cloud console, la finestra del terminale o l'applicazione senza interrompere l'esecuzione della query. Una query continua eseguita utilizzando un account di servizio può essere eseguita per un massimo di 150 giorni, poi si interrompe automaticamente. Per continuare a elaborare i nuovi dati in arrivo, avvia una nuova query continua e specifica un punto di partenza. Per automatizzare questa procedura, consulta Rieseguire le query non riuscite.

Per utilizzare un account di servizio per eseguire una query continua:

Creare un ID job personalizzato

A ogni job di query viene assegnato un ID job che puoi utilizzare per cercare e gestire il job. Per impostazione predefinita, gli ID job vengono generati in modo casuale. Per semplificare la ricerca dell'ID job di una query continua utilizzando la cronologia dei job o l'esploratore dei job, puoi assegnare un prefisso ID job personalizzato:

1. Nella console Trusted Cloud , vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, fai clic su Altro.

3. Nella sezione Scegli la modalità di query, scegli Query continua.

4. Fai clic su Conferma.

5. Nell'editor delle query, fai clic su Altro > Impostazioni query.

6. Nella sezione Prefisso ID job personalizzato, inserisci un prefisso del nome personalizzato.

7. Fai clic su Salva.

Esempi

I seguenti esempi di SQL mostrano casi d'uso comuni per le query continue.

Esportare i dati in un argomento Pub/Sub

L'esempio seguente mostra una query continua che filtra i dati di una tabella BigQuery che riceve informazioni in streaming sulle corse in taxi e li pubblica in tempo reale in un argomento Pub/Sub con attributi dei messaggi:

EXPORT DATA
  OPTIONS (
    format = 'CLOUD_PUBSUB',
    uri = 'https://pubsub.googleapis.com/projects/myproject/topics/taxi-real-time-rides')
AS (
  SELECT
    TO_JSON_STRING(
      STRUCT(
        ride_id,
        timestamp,
        latitude,
        longitude)) AS message,
    TO_JSON(
      STRUCT(
        CAST(passenger_count AS STRING) AS passenger_count)) AS _ATTRIBUTES
  FROM
    APPENDS(TABLE `myproject.real_time_taxi_streaming.taxi_rides`,
      -- Configure the APPENDS TVF start_timestamp to specify when you want to
      -- start processing data using your continuous query.
      -- This example starts processing at 10 minutes before the current time.
      CURRENT_TIMESTAMP() - INTERVAL 10 MINUTE)
  WHERE ride_status = 'enroute'
);

Esportare i dati in una tabella Bigtable

L'esempio seguente mostra una query continua che filtra i dati di una tabella BigQuery che riceve informazioni in streaming sulle corse in taxi e li esporta in tempo reale nella tabella Bigtable:

EXPORT DATA
  OPTIONS (
    format = 'CLOUD_BIGTABLE',
    truncate = TRUE,
    overwrite = TRUE,
    uri = 'https://bigtable.googleapis.com/projects/myproject/instances/mybigtableinstance/tables/taxi-real-time-rides')
AS (
  SELECT
    CAST(CONCAT(ride_id, timestamp, latitude, longitude) AS STRING) AS rowkey,
    STRUCT(
      timestamp,
      latitude,
      longitude,
      meter_reading,
      ride_status,
      passenger_count) AS features
  FROM
    APPENDS(TABLE `myproject.real_time_taxi_streaming.taxirides`,
      -- Configure the APPENDS TVF start_timestamp to specify when you want to
      -- start processing data using your continuous query.
      -- This example starts processing at 10 minutes before the current time.
      CURRENT_TIMESTAMP() - INTERVAL 10 MINUTE)
  WHERE ride_status = 'enroute'
);

Scrivere dati in una tabella BigQuery

L'esempio seguente mostra una query continua che filtra e trasforma i dati da una tabella BigQuery che riceve informazioni in streaming sulle corse in taxi, quindi scrive i dati in un'altra tabella BigQuery in tempo reale. In questo modo, i dati sono disponibili per ulteriori analisi a valle.

INSERT INTO `myproject.real_time_taxi_streaming.transformed_taxirides`
SELECT
  timestamp,
  meter_reading,
  ride_status,
  passenger_count,
  ST_Distance(
    ST_GeogPoint(pickup_longitude, pickup_latitude),
    ST_GeogPoint(dropoff_longitude, dropoff_latitude)) AS euclidean_trip_distance,
    SAFE_DIVIDE(meter_reading, passenger_count) AS cost_per_passenger
FROM
  APPENDS(TABLE `myproject.real_time_taxi_streaming.taxirides`,
    -- Configure the APPENDS TVF start_timestamp to specify when you want to
    -- start processing data using your continuous query.
    -- This example starts processing at 10 minutes before the current time.
    CURRENT_TIMESTAMP() - INTERVAL 10 MINUTE)
WHERE
  ride_status = 'dropoff';

Elaborare i dati utilizzando un modello Vertex AI

L'esempio seguente mostra una query continua che utilizza un modello Vertex AI per generare un annuncio per i passeggeri di taxi in base alla loro latitudine e longitudine attuali, quindi esporta i risultati in un argomento Pub/Sub in tempo reale:

EXPORT DATA
  OPTIONS (
    format = 'CLOUD_PUBSUB',
    uri = 'https://pubsub.googleapis.com/projects/myproject/topics/taxi-real-time-rides')
AS (
  SELECT
    TO_JSON_STRING(
      STRUCT(
        ride_id,
        timestamp,
        latitude,
        longitude,
        prompt,
        ml_generate_text_llm_result)) AS message
  FROM
    ML.GENERATE_TEXT(
      MODEL `myproject.real_time_taxi_streaming.taxi_ml_generate_model`,
      (
        SELECT
          timestamp,
          ride_id,
          latitude,
          longitude,
          CONCAT(
            'Generate an ad based on the current latitude of ',
            latitude,
            ' and longitude of ',
            longitude) AS prompt
        FROM
          APPENDS(TABLE `myproject.real_time_taxi_streaming.taxirides`,
            -- Configure the APPENDS TVF start_timestamp to specify when you
            -- want to start processing data using your continuous query.
            -- This example starts processing at 10 minutes before the current time.
            CURRENT_TIMESTAMP() - INTERVAL 10 MINUTE)
        WHERE ride_status = 'enroute'
      ),
      STRUCT(
        50 AS max_output_tokens,
        1.0 AS temperature,
        40 AS top_k,
        1.0 AS top_p,
        TRUE AS flatten_json_output))
      AS ml_output
);

Modificare il codice SQL di una query continua

Non puoi aggiornare il codice SQL utilizzato in una query continua mentre il job di query continua è in esecuzione. Devi annullare il job di query continua, modificare il codice SQL e avviare un nuovo job di query continua dal punto in cui hai interrotto il job di query continua originale.

Per modificare il codice SQL utilizzato in una query continua:

1. Visualizza i dettagli del job per il job di query continua che vuoi aggiornare e prendi nota dell'ID job.
2. Se possibile, metti in pausa la raccolta dei dati a monte. Se non riesci a farlo, potresti riscontrare una duplicazione dei dati al riavvio della query continua.
3. Annulla la query continua che vuoi modificare.

4. Ottieni il valore end_time per il job di query continua originale utilizzando la INFORMATION_SCHEMA JOBS visualizzazione:

   SELECT end_time
   FROM `PROJECT_ID.region-REGION`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
   WHERE
     EXTRACT(DATE FROM creation_time) = current_date()
   AND error_result.reason = 'stopped'
   AND job_id = 'JOB_ID';

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto.
   • REGION: la regione utilizzata dal progetto.
   • JOB_ID: l'ID job di query continua che hai identificato nel passaggio 1.

5. Modifica l'istruzione SQL della query continua per avviarla da un determinato punto nel tempo, utilizzando il valore end_time recuperato nel passaggio 5 come punto di partenza.

6. Modifica l'istruzione SQL della query continua in base alle modifiche necessarie.

7. Esegui la query continua modificata.

Annullare una query continua

Puoi annullare un job di query continua come qualsiasi altro job. Potrebbe essere necessario fino a un minuto prima che la query smetta di essere eseguita dopo l'annullamento del job.

Se annulli e poi riavvii una query, la query riavviata si comporta come una nuova query indipendente. La query riavviata non inizia a elaborare i dati dove si è interrotto il job precedente e non può fare riferimento ai risultati della query precedente. Consulta Avviare una query continua da un determinato punto nel tempo.

Monitora le query e gestisci gli errori

Una query continua potrebbe essere interrotta a causa di fattori quali incoerenze dei dati, modifiche allo schema, interruzioni temporanee del servizio o manutenzione. Sebbene BigQuery gestisca alcuni errori temporanei, le best practice per migliorare la resilienza dei job includono quanto segue:

• Monitora le query continue.
• Avviso sulle query non riuscite.
• Riesegui le query non riuscite.

Passaggi successivi

• Monitorare le query continue