Présentation du connecteur BigQuery
Le connecteur BigQuery vous permet d'exporter les métadonnées du document (y compris les propriétés) stockées dans Document AI Warehouse vers votre BigQuery. Une fois vos données dans BigQuery, vous pouvez effectuer des analyses, créer des rapports et des tableaux de bord pour vous aider à prendre des décisions commerciales.
Pour activer le connecteur BigQuery, vous devez configurer une table BigQuery avec les autorisations nécessaires et configurer les tâches asynchrones via l'API. Le connecteur BigQuery exporte les données de Document AI Warehouse vers vos tables BigQuery.
Avant de commencer
Configurez Document AI Warehouse et ingérez vos documents. Pour en savoir plus, suivez le guide de démarrage rapide.
Vous devez vous assurer que le projet qui héberge votre table BigQuery est le même que celui utilisé par Document AI Warehouse pour stocker vos documents. En d'autres termes, les données doivent toujours être exportées de Document AI Warehouse vers la table BigQuery du même projet.
Dans le projet, vous devez disposer du rôle Owner (roles/owner) ou des rôles resourcemanager.projects.getIamPolicy et resourcemanager.projects.setIamPolicy
des autorisations.
Configurer l'accès à BigQuery
Liez le compte de service doc-ai-warehouse-dw-bq-connector@system.gserviceaccount.com
au rôle 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
Configurer l'ensemble de données et la table BigQuery
Configurez un ensemble de données et une table BigQuery pour que Document AI Warehouse puisse exporter les données. Si vous ne disposez pas d'ensemble de données BigQuery, suivez la procédure de création d'ensembles de données pour en créer un.
Créez une table BigQuery dans votre ensemble de données BigQuery. En suivant les instructions BigQuery, vous créez des tables avec les exemples d'instructions LDD :
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 LDD crée une table BigQuery pour vous. La table est partitionnée par heure, et la partition est supprimée au bout de 150 jours.
Configurer le connecteur BigQuery
Créer une configuration d'exportation de données
Les instructions suivantes créent une tâche d'exportation de données, qui configure les tâches asynchrones pour exporter les données. Nous vous recommandons de commencer par une table vide pour chaque nouvelle tâche d'exportation de données. Pour en savoir plus sur la configuration, consultez la documentation de référence de l'API reference.
Vous disposez des options d'exécution suivantes. Elles peuvent être configurées à l'aide de FREQUENCY.
Reportez-vous à la documentation de référence de l'API
reference.
- ADHOC : la tâche ne s'exécute qu'une seule fois. Toutes les données sont exportées vers votre table BigQuery.
- DAILY : la tâche s'exécute quotidiennement. Lors de la première exécution, toutes les données sont exportées vers votre table BigQuery. Une fois l'exportation initiale terminée, seules les modifications apportées aux données du jour précédent (ou le delta par rapport à la dernière synchronisation réussie) sont exportées vers votre table BigQuery.
- HOURLY : la tâche s'exécute toutes les heures. Lors de la première exécution, toutes les données sont exportées vers votre table BigQuery. Une fois l'exportation initiale terminée, seules les modifications apportées aux données de l'heure précédente (ou le delta par rapport à la dernière synchronisation réussie) sont exportées vers votre table BigQuery.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_NUMBER : votre Google Cloud numéro de projet
- LOCATION : emplacement de votre Document AI Warehouse (par exemple, `us`)
- DATASET_LOCATION : emplacement de votre ensemble de données
- DATASET_NAME : nom de votre ensemble de données
- TABLE_NAME : nom de votre table
-
FREQUENCY :
ADHOC,DAILYouHOURLY
Corps JSON de la requête :
{
"projectNumber": PROJECT_NUMBER,
"location": "DATASET_LOCATION",
"dataset": "DATASET_NAME",
"table": "TABLE_NAME",
"frequency": "FREQUENCY",
"state": "ACTIVE"
}
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
Exécution du job
Une fois que vous avez créé une tâche, elle s'exécute en fonction de votre configuration. Notez que les tâches s'exécutent de manière asynchrone, car leur exécution prend du temps. Selon la quantité de données à exporter, la première exécution peut prendre du temps. Pour une tâche quotidienne, prévoyez 24 heures pour que les résultats s'affichent dans la table BigQuery.
Supprimer la configuration d'exportation de données
La commande suivante supprime (en archivant) une tâche que vous avez créée.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_NUMBER : votre Google Cloud numéro de projet
- LOCATION : emplacement de votre Document AI Warehouse (par exemple, `us`)
- JOB_ID : ID de votre tâche, dans la réponse lorsque vous l'avez créée
Corps JSON de la requête :
{}
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
Votre tâche d'exportation est alors supprimée (archivée) et Document AI Warehouse ne l'exécute plus.
Explorer les données ingérées dans BigQuery
Pour extraire les métadonnées et les propriétés des documents dans des champs de table distincts dans BigQuery pour vos besoins d'analyse, vous pouvez utiliser les exemples de requêtes LDD ci-dessous. Ces champs extraits peuvent également être utilisés dans Looker Studio ou tout autre outil de tableau de bord de BI pour visualiser les relations au sein des données.
Extraire les champs clés de document_json
Cette requête sélectionne les champs pertinents de l'exportation de données, y compris les champs clés des métadonnées du document (stockées dans le champ 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`;
Supprimer l'imbrication des propriétés de document_json
Cette requête supprime l'imbrication des propriétés des métadonnées du document (document_json) pour créer des paires clé-valeur (nom de la propriété, valeur). Ces paires clé-valeur seront transformées en champs de table individuels dans la requête suivante pour permettre l'exploration des données au niveau des propriétés et la visualisation du tableau de bord.
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);
Pivoter les propriétés de document_json pour créer des champs de table dans BigQuery
Les procédures suivantes créent une table avec toutes les propriétés du document transformées en champs de table individuels en pivotant les propriétés et les valeurs associées. Les résultats de cette table peuvent être exploités pour obtenir des insights supplémentaires grâce à des requêtes ultérieures dans Looker Studio et dans d'autres outils de visualisation de 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);
Procédures de nettoyage et de transformation des données (spécifiques au cas d'utilisation)
Selon les données ingérées dans BigQuery, vous devrez peut-être effectuer des procédures supplémentaires de nettoyage et de transformation des données pour permettre une analyse plus approfondie. Ces procédures varient d'un cas à l'autre (d'un ensemble de données à l'autre) et doivent être effectuées le cas échéant.
Voici quelques exemples de procédures de nettoyage des données (liste non exhaustive) :
- Unification des formats de date.
- Consolidation des valeurs de propriété.
- Casting des types de données en chaînes, flottants et entiers, par exemple.
Visualiser les données dans Looker Studio
Une fois vos données extraites, nettoyées et transformées dans BigQuery, votre ensemble de données final peut être exporté vers Looker Studio pour une analyse visuelle.
Tableaux de bord Looker
Les exemples de tableaux de bord présentés illustrent les visualisations possibles qui peuvent être créées à partir de votre ensemble de données. Dans ce scénario, l'exemple d'exportation de données de Document AI Warehouse se compose de formulaires W2 et de factures (deux schémas).
Tableaux de bord Looker publics
Exemple de vue : présentation des analyses de Document AI Warehouse
Le tableau de bord suivant vous donne un aperçu du type de documents ingérés dans votre instance Document AI Warehouse.
Vous pouvez afficher des détails au niveau du document, y compris :
- Nombre total de documents.
- Nombre total de schémas de documents.
- Nombre d'enregistrements par schéma de document.
- Type de fichier de document (PDF, texte, type non spécifié, etc.).
Vous pouvez également utiliser les propriétés extraites des métadonnées du document (document_json) pour créer des répartitions clés pour les factures et les formulaires W2 ingérés dans BigQuery.
Exemple de vue : tableau de bord d'insights spécifiques à l'entreprise (factures)
Le tableau de bord suivant fournit à l'utilisateur une vue détaillée d'un seul schéma de document (factures) pour permettre d'obtenir des insights sur toutes les factures ingérées dans Document AI Warehouse.
Vous pouvez afficher des détails spécifiques au schéma sur les factures, par exemple :
- Principaux fournisseurs par montant de facture.
- Fournisseurs par emplacement.
- Dates de facturation et dates d'échéance correspondantes.
- Tendances des factures d'un mois à l'autre par montant et nombre d'enregistrements.
Associer une source de données à des tableaux de bord
Pour utiliser ces exemples de tableaux de bord comme point de départ pour visualiser votre ensemble de données, vous pouvez associer votre source de données à partir de BigQuery.
Avant d'associer les exemples de tableaux de bord à votre source de données BigQuery, assurez-vous d'être connecté au compte associé à votre Google Cloud environnement.
Sélectionnez le bouton en surbrillance pour afficher les options du menu déroulant.
Sélectionnez Créer une copie.
Dans la sous-section "Nouvelle source de données", sélectionnez Créer une source de données.
Sélectionnez BigQuery.
Sélectionnez le projet dans lequel votre ensemble de données est stocké, puis suivez les instructions pour sélectionner votre ensemble de données et votre table. Cliquez sur Connect (Se connecter).
Cliquez sur Ajouter au rapport.
Cliquez sur Copier le rapport.
Si vous choisissez de modifier les widgets de votre tableau de bord, vous pouvez le faire, car vous disposez d'une copie du tableau de bord avec les propriétés extraites.