Como processar alterações de esquema em tabelas de dados do BigQuery Export

Nesta página, você verá como processar as alterações de esquema feitas em 28 de outubro de 2020 para os dados do Cloud Billing exportados para tabelas no BigQuery.

Noções básicas sobre as alterações

O esquema da tabela dos dados de custo de uso padrão do Cloud Billing exportados para o BigQuery foi atualizado para fornecer mais clareza com campos de dados adicionais. Essa tabela é denominada gcp_billing_export_v1_<BILLING_ACCOUNT_ID> no conjunto de dados do BigQuery.

Os campos de dados a seguir foram adicionados ao esquema de exportação de uso do Cloud Billing no BigQuery:

  • project.number
  • adjustment_info
  • adjustment_info.id
  • adjustment_info.mode
  • adjustment_info.description
  • adjustment_info.type

Esses dados são novos a partir de 29 de outubro de 2020 e não estão disponíveis para uso antes dessa data. Atualize suas integrações ou automações com base no novo esquema realizando migrações se e quando necessário. Para informações sobre os dados fornecidos por esses novos campos, consulte Noções básicas sobre tabelas de dados do Cloud Billing no BigQuery.

Impacto nas tabelas e consultas existentes

Como a estrutura da tabela da exportação de dados de custo de uso padrão foi alterada, todas as consultas que fazem referência direta às tabelas exportadas não fornecem mais todos os dados disponíveis. Para resolver esse problema, recomendamos criar visualizações do BigQuery que consultem as tabelas exportadas e apresentem as informações na sua estrutura preferida. É possível ajustar as consultas que alimentam os relatórios e painéis para extrair as visualizações e não as tabelas exportadas.

Ao usar as visualizações, é possível padronizar a estrutura dos dados usados nas consultas e nos painéis.

As visualizações criadas precisam normalizar os dados para que todas as tabelas relevantes apresentem o mesmo esquema às consultas. Isso protege você contra futuras alterações do esquema, permitindo modificar a consulta subjacente da visualização nessas instâncias quando o esquema de dados é alterado.

Como criar visualizações para lidar com alterações de esquema

Se for preciso manter tabelas que usam o esquema anterior, recomendamos criar visualizações do BigQuery para essas tabelas para normalizar o esquema de dados. Ao criar uma visualização para migrar do esquema anterior para o novo, é possível usar uma instrução UNION para combinar tabelas com esquemas incompatíveis. A visualização que você cria dependerá dos campos de dados usados nas consultas e nos painéis.

Um ou mais dos exemplos a seguir podem ser aplicados à sua situação, em que suas consultas podem ou não usar os novos campos project.number e adjustment_info.

  1. Use tabelas que incluam propriedades de esquemas preexistentes e novas, como credits.type, credits.id, credits.full, project.number e adjustment_info. Para conferir um exemplo de como criar essa visualização, consulte Como criar uma visualização para tabelas com todos os campos no esquema atualizado.
  2. Você usa tabelas que não incluem as propriedades de esquemas preexistentes credits.type, credits.id e credits.full. Para ver um exemplo de como criar essa visualização, consulte Como criar uma visualização para tabelas sem credits.type, credits.id e credits.full.
  3. Use tabelas que incluam propriedades de esquemas preexistentes credits.type, credits.id e credits.full, mas não incluam as novas propriedades do esquema project.number e adjustment_info. Para ver um exemplo de como criar essa visualização, consulte Como criar uma visualização para tabelas sem project.number e adjustment_info.

É possível criar uma visualização compondo uma consulta SQL que é usada para definir os dados acessíveis para a exibição. Para mais detalhes, consulte Como criar uma visualização.

Veja a seguir um resumo das etapas para criar uma visualização do BigQuery.

  1. Selecione a consulta para criar a visualização
  2. Execute a consulta e observe os resultados
  3. Salve a visualização
  4. Insira o nome da nova visualização
  5. Observe o esquema da nova visualização

1. Como criar uma visualização para tabelas com todos os campos no esquema atualizado

Veja a seguir uma consulta que criará uma nova visualização usando os esquemas preexistentes e os atualizados. Esse tipo de visualização limita a exposição a alterações futuras do esquema.

Ao usar essa visualização para suas consultas, todas elas terão o mesmo esquema e permitirão que as instruções UNION funcionem corretamente. Essa consulta preserva os valores e campos credits.type, credits.id, credits.full, project.number e adjustment_info das tabelas subjacentes.

SQL padrão

SELECT
    billing_account_id,
    STRUCT(service.id as id,
        service.description as description) as service,
    STRUCT(sku.id as id,
        sku.description as description) as sku,
    usage_start_time,
    usage_end_time,
    STRUCT(
        project.id as id,
        project.name as name,
        project.number as number,
        ARRAY(SELECT AS STRUCT
            label.key as key,
            label.value as value,
            FROM UNNEST(project.labels) as label) as labels,
        project.ancestry_numbers as ancestry_numbers) as project,
    ARRAY(SELECT AS STRUCT
        label.key as key,
        label.value as value,
        FROM UNNEST(labels) as label) as labels,
    ARRAY(SELECT AS STRUCT
        system_label.key as key,
        system_label.value as value,
        FROM UNNEST(system_labels) as system_label) as system_labels,
    STRUCT(
        location.location as location,
        location.country as country,
        location.region as region,
        location.zone as zone) as location,
    export_time,
    cost,
    currency,
    currency_conversion_rate,
    STRUCT(
        usage.amount as amount,
        usage.unit as unit,
        usage.amount_in_pricing_units as amount_in_pricing_units,
        usage.pricing_unit as pricing_unit) as usage,
    ARRAY(SELECT AS STRUCT
        credit.name as name,
        credit.amount as amount,
        credit.type as type,
        credit.id as id,
        credit.full_name as full_name,
        FROM UNNEST(credits) as credit) as credits,
    STRUCT(
        invoice.month as month) as invoice,
    cost_type,
    STRUCT(
        adjustment_info.id as id,
        adjustment_info.description as description,
        adjustment_info.mode as mode,
        adjustment_info.type as type) as adjustment_info,
    FROM TABLE_WITH_CREDITINFO_PROJECT_NUMBER_AND_ADJUSTMENT_INFO

2. Como criar uma visualização para tabelas sem credits.type, credits.id e credits.full

Veja a seguir uma consulta que criará uma nova visualização usando tabelas que não incluem as propriedades de esquemas preexistentes credits.type, credits.id e credits.full.

SQL padrão

SELECT
    billing_account_id,
    STRUCT(service.id as id,
        service.description as description) as service,
    STRUCT(sku.id as id,
        sku.description as description) as sku,
    usage_start_time,
    usage_end_time,
    STRUCT(
        project.id as id,
        project.name as name,
        CAST(NULL as string) as number,
        ARRAY(SELECT AS STRUCT
            label.key as key,
            label.value as value,
            FROM UNNEST(project.labels) as label) as labels,
        project.ancestry_numbers as ancestry_numbers) as project,
    ARRAY(SELECT AS STRUCT
        label.key as key,
        label.value as value,
        FROM UNNEST(labels) as label) as labels,
    ARRAY(SELECT AS STRUCT
        system_label.key as key,
        system_label.value as value,
        FROM UNNEST(system_labels) as system_label) as system_labels,
    STRUCT(
        location.location as location,
        location.country as country,
        location.region as region,
        location.zone as zone) as location,
    export_time,
    cost,
    currency,
    currency_conversion_rate,
    STRUCT(
        usage.amount as amount,
        usage.unit as unit,
        usage.amount_in_pricing_units as amount_in_pricing_units,
        usage.pricing_unit as pricing_unit) as usage,
    ARRAY(SELECT AS STRUCT
        credit.name as name,
        credit.amount as amount,
        CAST(NULL as STRING) as type,
        CAST(NULL as STRING) as id,
        CAST(NULL as STRING) as full_name,
        FROM UNNEST(credits) as credit) as credits,
    STRUCT(
        invoice.month as month) as invoice,
    cost_type,
    STRUCT(
        CAST(NULL as STRING) as id,
        CAST(NULL as STRING) as description,
        CAST(NULL as STRING) as mode,
        CAST(NULL as STRING) as type) as adjustment_info,
FROM TABLE_WITHOUT_CREDIT_ID_TYPE_FULL_NAME

3. Como criar uma visualização para tabelas sem project.number e adjustment_info

Veja a seguir uma consulta que criará uma nova visualização usando tabelas que incluem as propriedades de esquemas preexistentes credits.type, credits.id e credits.full, mas não incluem as novas propriedades de esquemas project.number e adjustment_info.

SQL padrão

SELECT
    billing_account_id,
    STRUCT(service.id as id,
        service.description as description) as service,
    STRUCT(sku.id as id,
        sku.description as description) as sku,
    usage_start_time,
    usage_end_time,
    STRUCT(
        project.id as id,
        project.name as name,
        CAST(NULL as string) as number,
        ARRAY(SELECT AS STRUCT
            label.key as key,
            label.value as value,
            FROM UNNEST(project.labels) as label) as labels,
        project.ancestry_numbers as ancestry_numbers) as project,
    ARRAY(SELECT AS STRUCT
        label.key as key,
        label.value as value,
        FROM UNNEST(labels) as label) as labels,
    ARRAY(SELECT AS STRUCT
        system_label.key as key,
        system_label.value as value,
        FROM UNNEST(system_labels) as system_label) as system_labels,
    STRUCT(
        location.location as location,
        location.country as country,
        location.region as region,
        location.zone as zone) as location,
    export_time,
    cost,
    currency,
    currency_conversion_rate,
    STRUCT(
        usage.amount as amount,
        usage.unit as unit,
        usage.amount_in_pricing_units as amount_in_pricing_units,
        usage.pricing_unit as pricing_unit) as usage,
    ARRAY(SELECT AS STRUCT
        credit.name as name,
        credit.amount as amount,
        credit.type as type,
        credit.id as id,
        credit.full_name as full_name,
        FROM UNNEST(credits) as credit) as credits,
    STRUCT(
        invoice.month as month) as invoice,
    cost_type,
    STRUCT(
        CAST(NULL as STRING) as id,
        CAST(NULL as STRING) as description,
        CAST(NULL as STRING) as mode,
        CAST(NULL as STRING) as type) as adjustment_info,
FROM TABLE_WITHOUT_PROJECTNUMBER_AND_ADJUSTMENT_INFO

4. Como verificar se as visualizações são consistentes com as tabelas originais

Com as consultas a seguir, é possível verificar se as visualizações criadas fornecem dados consistentes com as tabelas originais que você estava consultando. As consultas usam a visualização criada no exemplo sem credits.type, credits.id e credits.full. Para mais detalhes sobre como criar essa visualização, consulte Como criar uma visualização para tabelas sem credits.type, credits.id e credits.full.

Essa consulta fornece uma comparação linha por linha do custo entre a tabela original e a visualização criada sem credits.type, credits.id e credits.full.

SQL padrão

-- ROW BY ROW COMPARISON OF COST BETWEEN ORIGINAL TABLE AND CONVERTED TABLE
SELECT cost FROM TABLE_WITHOUT_CREDIT_ID_TYPE_FULL_NAME
EXCEPT DISTINCT
SELECT cost FROM TABLE_WITHOUT_CREDIT_ID_TYPE_FULL_NAME_VIEW

Esta consulta fornece uma comparação linha por linha dos créditos entre a tabela original e a visualização criada sem credits.type, credits.id e credits.full.

SQL padrão

-- ROW BY ROW COMPARISON OF CREDITS BETWEEN ORIGINAL TABLE AND CONVERTED TABLE
WITH CONCAT_AMOUNTS AS (SELECT ARRAY_CONCAT_AGG(ARRAY(SELECT amount FROM UNNEST(credits) as cred)) as amounts FROM TABLE_WITHOUT_CREDIT_ID_TYPE_FULL_NAME),
CONCAT_AMOUNTS_CONVERTED AS (SELECT ARRAY_CONCAT_AGG(ARRAY(SELECT amount FROM UNNEST(credits) as cred)) as amounts FROM TABLE_WITHOUT_CREDIT_ID_TYPE_FULL_NAME_VIEW)

SELECT amounts FROM CONCAT_AMOUNTS, UNNEST(amounts) as amounts
EXCEPT DISTINCT
SELECT amounts FROM CONCAT_AMOUNTS_CONVERTED, UNNEST(amounts) as amounts