Introduzione al connettore BigQuery
Il connettore BigQuery ti aiuta a esportare i metadati del documento (incluse le proprietà) archiviati in Document AI Warehouse nella tua tabella BigQuery. Con i tuoi dati in BigQuery, puoi eseguire analisi, creare report e dashboard per aiutarti a prendere decisioni aziendali.
Per abilitare il connettore BigQuery, devi configurare una tabella BigQuery con le autorizzazioni necessarie e configurare le attività asincrone tramite l'API. Il connettore BigQuery esporta i dati da Document AI Warehouse alle tue tabelle BigQuery.
Prima di iniziare
Configura Document AI Warehouse e importa i tuoi documenti. Per saperne di più, segui la guida rapida.
Devi assicurarti che il progetto che ospita la tabella BigQuery sia lo stesso utilizzato da Document AI Warehouse per archiviare i documenti. In altre parole, i dati devono sempre essere esportati da Document AI Warehouse nella tabella BigQuery nello stesso progetto.
Nel progetto, devi disporre del ruolo Owner (roles/owner) oppure dei ruoli resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy.
autorizzazioni aggiuntive.
Configurare l'accesso a BigQuery
Associa il account di servizio doc-ai-warehouse-dw-bq-connector@system.gserviceaccount.com
al ruolo BigQuery Admin:
gcloud projects add-iam-policy-binding <var>PROJECT_ID</var> --member serviceAccount:doc-ai-warehouse-dw-bq-connector@system.gserviceaccount.com --role=roles/bigquery.admin
Configura il set di dati e la tabella BigQuery
Configura un set di dati e una tabella BigQuery per Document AI Warehouse per esportare i dati. Se non hai un set di dati BigQuery, segui la procedura per creare set di dati.
Crea una tabella BigQuery nel tuo set di dati BigQuery. Seguendo le istruzioni BigQuery, crea tabelle con le istruzioni DDL di esempio:
CREATE TABLE `PROJECT_ID.DATASET_NAME.TABLE_NAME`
(
project_number INT64,
location STRING,
mod_type STRING,
document_id STRING,
document_json JSON,
create_time TIMESTAMP,
creator STRING,
update_time TIMESTAMP,
updater STRING,
document_state STRING,
export_time TIMESTAMP
)
PARTITION BY TIMESTAMP_TRUNC(export_time, HOUR)
OPTIONS(
partition_expiration_days=150,
description="table partitioned by export_time on hour with expiry"
);
La DDL crea una nuova tabella BigQuery. La tabella è partizionata per ora e la partizione viene eliminata dopo 150 giorni.
Configura il connettore BigQuery
Creare la configurazione dell'esportazione dati
Le seguenti istruzioni creano un nuovo job di esportazione dei dati, che configura i job asincroni per esportare i dati. Ti consigliamo di iniziare con una tabella vuota per ogni nuovo job di esportazione dei dati. Per i dettagli della configurazione, consulta il riferimento API.
Hai a disposizione le seguenti opzioni di corsa. Possono essere configurati utilizzando
FREQUENCY.
Consulta il riferimento
API.
- ADHOC:il job viene eseguito una sola volta. Tutti i dati vengono esportati nella tabella BigQuery.
- DAILY (GIORNALIERO): il job viene eseguito ogni giorno. Per la prima esecuzione, tutti i dati vengono esportati nella tabella BigQuery. Una volta completata l'esportazione iniziale, nella tabella BigQuery vengono esportate solo le modifiche ai dati del giorno precedente (o la differenza rispetto all'ultima sincronizzazione riuscita).
- ORARIO:il job viene eseguito ogni ora. Per la prima esecuzione, tutti i dati vengono esportati nella tabella BigQuery. Una volta completata l'esportazione iniziale, nella tabella BigQuery vengono esportate solo le modifiche ai dati dell'ora precedente (o la differenza rispetto all'ultima sincronizzazione riuscita).
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_NUMBER: il tuo Google Cloud numero di progetto
- LOCATION: la posizione di Document AI Warehouse (ad esempio `us`)
- DATASET_LOCATION: la posizione del set di dati
- DATASET_NAME: il nome del set di dati
- TABLE_NAME: il nome della tabella
-
FREQUENCY: uno tra
ADHOC,DAILYoHOURLY.
Corpo JSON della richiesta:
{
"projectNumber": PROJECT_NUMBER,
"location": "DATASET_LOCATION",
"dataset": "DATASET_NAME",
"table": "TABLE_NAME",
"frequency": "FREQUENCY",
"state": "ACTIVE"
}
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
Esecuzione del job
Una volta creato correttamente un job, questo viene eseguito in base alla configurazione. Tieni presente che i job vengono eseguiti in modo asincrono perché l'esecuzione richiede tempo. A seconda della quantità di dati da esportare, la prima esecuzione può richiedere tempo per essere completata. Per il job giornaliero, attendi 24 ore prima che i risultati vengano visualizzati nella tabella BigQuery.
Elimina configurazione esportazione dati
Il seguente comando elimina (archiviando) un job che hai creato.
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_NUMBER: il tuo Google Cloud numero di progetto
- LOCATION: la posizione di Document AI Warehouse (ad esempio `us`)
- JOB_ID: l'ID del job, nella risposta quando l'hai creato
Corpo JSON della richiesta:
{}
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
Dopodiché, il job di esportazione viene eliminato (archiviato) e Document AI Warehouse non lo esegue più.
Esplorare i dati importati in BigQuery
Per estrarre i metadati e le proprietà dei documenti in campi di tabella distinti in BigQuery per le tue esigenze di analisi, puoi utilizzare le query DDL di esempio di seguito. Questi campi estratti possono essere utilizzati anche in Looker Studio o in qualsiasi strumento di dashboard BI per visualizzare le relazioni all'interno dei dati.
Estrai i campi chiave da document_json
Questa query seleziona i campi pertinenti dall'esportazione dei dati, inclusi i campi chiave dai metadati del documento (memorizzati nel campo document_json).
DROP VIEW IF EXISTS
`DATASET_NAME.VIEW_NAME_1`;
CREATE VIEW
`DATASET_NAME.VIEW_NAME_1` AS
SELECT
project_number,
document_id,
mod_type,
create_time,
update_time,
location,
creator,
updater,
document_state,
SPLIT(JSON_EXTRACT_SCALAR(document_json,'$.documentSchemaName' ), '/')[SAFE_OFFSET(ARRAY_LENGTH(SPLIT(JSON_EXTRACT_SCALAR(document_json,'$.documentSchemaName' ), '/')) - 1)] AS document_schema_name,
JSON_EXTRACT_SCALAR(document_json,'$.name') AS document_name,
JSON_EXTRACT_SCALAR(document_json,'$.rawDocumentFileType')
AS raw_document_file_type,
JSON_EXTRACT(document_json,'$.properties') AS properties
FROM
`DATASET_NAME.SYSTEM_METADATA_AND_DOC_PROPERTIES_TABLE_EXPORT_NAME`;
Estrazione delle proprietà da document_json
Questa query estrae le proprietà dai metadati del documento (document_json) per creare coppie chiave-valore (nome proprietà, valore). Queste coppie chiave-valore verranno trasformate in singoli campi della tabella nella query successiva per consentire l'esplorazione dei dati a livello di proprietà e la visualizzazione della dashboard.
DROP VIEW IF EXISTS
`DATASET_NAME.VIEW_NAME_2`;
CREATE VIEW
`DATASET_NAME.VIEW_NAME_2` AS
SELECT
* EXCEPT(key_value_pair,
properties,raw_document_file_type)
FROM (
SELECT
*,
REPLACE(JSON_VALUE(key_value_pair,'$.name'),'/','-') property_name,
-- Note: values are either text OR float values
CASE
WHEN JSON_VALUE(key_value_pair,'$.textValues.values[0]') IS NULL THEN JSON_VALUE(key_value_pair,'$.floatValues.values[0]')
ELSE
JSON_VALUE(key_value_pair,'$.textValues.values[0]')
END
AS value,
CASE
WHEN raw_document_file_type IS NULL THEN "RAW_DOCUMENT_FILE_TYPE_UNSPECIFIED"
ELSE
raw_document_file_type
END
AS document_file_type
FROM
`DATASET_NAME.VIEW_NAME_1`,
UNNEST(JSON_EXTRACT_ARRAY(properties)) AS key_value_pair);
Pivot delle proprietà da document_json per creare campi della tabella in BigQuery
Le seguenti procedure creano una tabella con tutte le proprietà del documento trasformate in singoli campi della tabella mediante la rotazione delle proprietà e dei valori associati. I risultati di questa tabella possono essere utilizzati per ottenere ulteriori approfondimenti tramite query successive in Looker Studio e in altri strumenti di visualizzazione della BI.
DECLARE
property_field STRING;
-- Extracting distinct property_names from the previous view and storing it in property_field, declared above
EXECUTE IMMEDIATE
"""SELECT string_agg(CONCAT("'",property_name,"'")) from (select distinct property_name from DATASET.VIEW_NAME_2)""" INTO property_field;
DROP TABLE IF EXISTS `DATASET_NAME.ANALYTICS_TABLE_NAME`;
-- Creating pivot table with the aid of extracted distinct property_names
-- Casting numerical values to float/int
-- Pivot on property_name and value (ie. create a new column for each of the property_name, substitute the value)
EXECUTE IMMEDIATE
FORMAT ("""
CREATE TABLE `DATASET_NAME.ANALYTICS_TABLE_NAME` AS
SELECT * FROM `DATASET_NAME.VIEW_NAME_2`
PIVOT(min(value) FOR property_name IN (%s))""", property_field);
Procedure di pulizia e trasformazione dei dati (specifiche per il business case)
A seconda dei dati importati in BigQuery, potrebbe essere necessario eseguire ulteriori procedure di pulizia e trasformazione dei dati per consentire ulteriori analisi. Queste procedure variano a seconda del caso (set di dati) e devono essere eseguite in modo appropriato.
Alcuni esempi di procedure di pulizia dei dati potrebbero includere (senza alcuna limitazione):
- Unificazione dei formati della data.
- Consolidamento dei valori delle proprietà.
- Ad esempio, il casting dei tipi di dati in stringhe, numeri in virgola mobile e numeri interi.
Visualizzare i dati in Looker Studio
Una volta estratti, puliti e trasformati in BigQuery, i dati possono essere esportati in Looker Studio per l'analisi visiva.
Dashboard di Looker
Le dashboard di esempio descritte mostrano le possibili visualizzazioni che possono essere create dal tuo set di dati. In questo scenario, l'esportazione dei dati di esempio da Document AI Warehouse è costituita da W2 e fatture (due schemi).
Dashboard di Looker rivolte al pubblico
Visualizzazione di esempio: panoramica di Document AI Warehouse Analytics
La seguente dashboard fornisce informazioni di alto livello sulla varietà di documenti inseriti nell'istanza di Document AI Warehouse.
Puoi visualizzare i dettagli a livello di documento, tra cui:
- Numero totale di documenti.
- Numero totale di schemi di documenti.
- Conteggio dei record per schema del documento.
- Tipo di file del documento (ad esempio PDF, testo, tipo non specificato).
Puoi anche utilizzare le proprietà estratte dai metadati del documento (document_json) per creare suddivisioni chiave per le fatture e i moduli W-2 acquisiti in BigQuery.
Visualizzazione di esempio: dashboard degli approfondimenti specifici per l'attività (fatture)
La seguente dashboard fornisce all'utente una visione dettagliata di un singolo schema di documento (fatture) per consentire di ottenere approfondimenti su tutte le fatture inserite in Document AI Warehouse.
Puoi visualizzare dettagli specifici dello schema sulle fatture, ad esempio:
- I principali fornitori in base agli importi delle fatture.
- Fornitori per località.
- Date delle fatture e relative date di scadenza.
- Tendenze delle fatture mese per mese in base all'importo e al numero di record.
Collegamento dell'origine dati alle dashboard
Per utilizzare questi esempi di dashboard come punto di partenza per visualizzare il tuo set di dati, puoi connettere l'origine dati da BigQuery.
Prima di connettere i dashboard di esempio all'origine dati BigQuery, assicurati di aver eseguito l'accesso al tuo account associato al tuo Google Cloud ambiente.
Seleziona il pulsante evidenziato per visualizzare le opzioni del menu a discesa.
Seleziona Crea una copia.
Nella sezione secondaria Nuova origine dati, seleziona Crea origine dati.
Seleziona BigQuery.
Seleziona il progetto in cui è archiviato il set di dati, quindi segui le istruzioni per selezionare il set di dati e la tabella. Fai clic su Connetti.
Fai clic su Aggiungi al report.
Fai clic su Copia report.
Se scegli di modificare e aggiornare i widget nella dashboard, puoi farlo, perché hai una copia della dashboard con le proprietà estratte.