Introdução ao conector do BigQuery
O conector do BigQuery ajuda a exportar os metadados do documento (incluindo propriedades) armazenados no Document AI Warehouse para sua tabela do BigQuery. Com seus dados no BigQuery, é possível fazer análises, criar relatórios e painéis para ajudar você a tomar decisões de negócios.
Para ativar o conector do BigQuery, configure uma tabela do BigQuery com as permissões necessárias e configure as tarefas assíncronas pela API. O conector do BigQuery exporta os dados do Document AI Warehouse para suas tabelas do BigQuery.
Antes de começar
Configure o Document AI Warehouse e ingira seus documentos. Para mais informações, siga o início rápido.
Verifique se o projeto que hospeda sua tabela do BigQuery é o mesmo usado pelo Document AI Warehouse para armazenar seus documentos. Em outras palavras, os dados precisam sempre ser exportados do Document AI Warehouse para a tabela do BigQuery no mesmo projeto.
No projeto, você precisa ter o papel Owner (roles/owner) ou os papéis resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy.
mais permissões.
Configurar o acesso ao BigQuery
Vincule a conta de serviço doc-ai-warehouse-dw-bq-connector@system.gserviceaccount.com
ao papel 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
Configurar um conjunto de dados e uma tabela do BigQuery
Configure um conjunto de dados e uma tabela do BigQuery para que o Document AI Warehouse exporte os dados. Se você não tiver um conjunto de dados do BigQuery, siga as etapas para criar um.
Crie uma tabela do BigQuery no conjunto de dados do BigQuery. Seguindo as instruções do BigQuery, crie tabelas com as instruções de exemplo DDL:
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"
);
A DDL cria uma tabela do BigQuery para você. A tabela é particionada por hora, e a partição é excluída em 150 dias.
Configurar o conector do BigQuery
Criar uma configuração de exportação de dados
As instruções a seguir criam um job de exportação de dados, que configura os jobs assíncronos para exportar dados. Recomendamos começar com uma tabela vazia para cada novo job de exportação de dados. Consulte a referência da API para mais detalhes sobre a configuração.
Você tem as seguintes opções de execução. Eles podem ser configurados usando o
FREQUENCY.
Consulte a referência da API.
- ADHOC:o job é executado apenas uma vez. Todos os dados são exportados para sua tabela do BigQuery.
- DIÁRIO:o job é executado diariamente. Na primeira execução, todos os dados são exportados para a tabela do BigQuery. Depois que a exportação inicial for concluída, apenas as mudanças nos dados do dia anterior (ou o delta da última sincronização bem-sucedida) serão exportadas para sua tabela do BigQuery.
- HORÁRIO:o job é executado a cada hora. Na primeira execução, todos os dados são exportados para a tabela do BigQuery. Depois que a exportação inicial for concluída, apenas as mudanças nos dados da hora anterior (ou o delta da última sincronização bem-sucedida) serão exportadas para a tabela do BigQuery.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_NUMBER: o número do projeto do Google Cloud
- LOCATION: o local do Document AI Warehouse (por exemplo, "us")
- DATASET_LOCATION: o local do conjunto de dados
- DATASET_NAME: o nome do conjunto de dados
- TABLE_NAME: o nome da tabela
-
FREQUENCY: um de
ADHOC,DAILYouHOURLY.
Corpo JSON da solicitação:
{
"projectNumber": PROJECT_NUMBER,
"location": "DATASET_LOCATION",
"dataset": "DATASET_NAME",
"table": "TABLE_NAME",
"frequency": "FREQUENCY",
"state": "ACTIVE"
}
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
Execução do trabalho
Depois de criar um job, ele será executado com base na sua configuração. Os jobs são executados de forma assíncrona porque levam tempo para serem executados. Dependendo da quantidade de dados a serem exportados, a primeira execução pode levar tempo para ser concluída. Para jobs diários, aguarde 24 horas para que os resultados apareçam na tabela do BigQuery.
Excluir configuração de exportação de dados
O comando a seguir exclui (arquivando) um job que você criou.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_NUMBER: o número do projeto do Google Cloud
- LOCATION: o local do Document AI Warehouse (por exemplo, "us")
- JOB_ID: o ID do seu job, na resposta de quando você o criou.
Corpo JSON da solicitação:
{}
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
Depois disso, o job de exportação é excluído (arquivado), e o Document AI Warehouse não o executa mais.
Analisar dados ingeridos no BigQuery
Para extrair metadados e propriedades de documentos em campos de tabela distintos no BigQuery para suas necessidades de análise, use as consultas DDL de exemplo abaixo. Esses campos extraídos também podem ser usados no Looker Studio ou em qualquer ferramenta de painel de BI para visualizar relações nos dados.
Extrair campos principais de "document_json"
Essa consulta seleciona campos relevantes da exportação de dados, incluindo campos principais dos metadados do documento (armazenados no 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`;
Remover o aninhamento de propriedades de "document_json"
Essa consulta descompacta as propriedades dos metadados do documento (document_json) para criar pares de chave-valor (nome da propriedade, valor). Esses pares de chave-valor serão transformados em campos de tabela individuais na próxima consulta para permitir a análise detalhada de dados no nível da propriedade e a visualização do painel.
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);
Inverter propriedades de document_json para criar campos de tabela no BigQuery
Os procedimentos a seguir criam uma tabela com todas as propriedades do documento transformadas como campos individuais da tabela ao fazer a rotação das propriedades e dos valores associados. Os resultados dessa tabela podem ser usados para gerar mais insights com consultas subsequentes no Looker Studio e em outras ferramentas de visualização 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);
Procedimentos de limpeza e transformação de dados (específicos para o caso de negócios)
Dependendo dos dados ingeridos no BigQuery, talvez seja necessário realizar outros procedimentos de limpeza e transformação para permitir análises mais detalhadas. Esses procedimentos variam de caso a caso (conjunto de dados a conjunto de dados) e devem ser realizados conforme apropriado.
Alguns exemplos de procedimentos de limpeza de dados incluem (mas não se limitam a):
- Unificação de formatos de data.
- Consolidar valores de propriedades.
- Por exemplo, conversão de tipos de dados em strings, números de ponto flutuante e números inteiros.
Visualizar os dados no Looker Studio
Depois que os dados forem extraídos, limpos e transformados no BigQuery, o conjunto de dados final poderá ser exportado para o Looker Studio para análise visual.
Painéis do Looker
Os painéis de exemplo mostram possíveis visualizações que podem ser criadas com seu conjunto de dados. Neste cenário, a exportação de dados de amostra do Document AI Warehouse consiste em W2s e faturas (dois esquemas).
Exemplo de visualização: visão geral da análise do Document AI Warehouse
O painel a seguir oferece insights de alto nível sobre a variedade de documentos ingeridos na sua instância do Document AI Warehouse.
É possível conferir detalhes no nível do documento, incluindo:
- Número total de documentos.
- Número total de esquemas de documentos.
- Contagem de registros por esquema de documento.
- Tipo de arquivo de documento (como PDF, texto, tipo não especificado).
Você também pode usar propriedades extraídas dos metadados do documento (document_json) para criar detalhamentos principais das faturas e dos formulários W-2 ingeridos no BigQuery.
Exemplo de visualização: painel de insights específicos para empresas (faturas)
O painel a seguir oferece ao usuário uma análise detalhada de um único esquema de documento (faturas) para ativar insights sobre todas as faturas ingeridas no warehouse da Document AI.
É possível conferir detalhes específicos do esquema nas faturas, por exemplo:
- Principais fornecedores por valores de faturas.
- Fornecedores por local.
- Datas de faturamento e os respectivos vencimentos.
- Tendências nas faturas mês a mês por valor e contagem de registros.
Como conectar fontes de dados aos painéis
Para usar esses exemplos de painel como ponto de partida para visualizar seu conjunto de dados, conecte sua fonte de dados do BigQuery.
Antes de conectar os painéis de amostra à sua fonte de dados do BigQuery, verifique se você fez login na conta associada ao seu ambiente Google Cloud.
Selecione o botão destacado para abrir as opções do menu suspenso.
Selecione Fazer uma cópia.
Na subseção "Nova fonte de dados", selecione Criar fonte de dados.
Selecione BigQuery.
Selecione o projeto em que o conjunto de dados está armazenado e siga as instruções para selecionar o conjunto de dados e a tabela. Clique em Conectar.
Clique em Adicionar ao relatório.
Clique em Copiar relatório.
Se você optar por editar e atualizar os widgets no painel, poderá fazer isso, porque tem uma cópia do painel com as propriedades extraídas.