Visualização WRITE_API_TIMELINE

A visualização INFORMATION_SCHEMA.WRITE_API_TIMELINE contém estatísticas agregadas por minuto de ingestão da API BigQuery Storage Write para o projeto atual.

Consulte as INFORMATION_SCHEMA visualizações da API Write para recuperar informações históricas e em tempo real sobre a ingestão de dados no BigQuery que usa essa API. Consulte API BigQuery Storage Write para mais informações.

Permissão necessária

Para consultar a visualização INFORMATION_SCHEMA.WRITE_API_TIMELINE, você precisa da permissão bigquery.tables.list do Identity and Access Management (IAM) para o projeto.

Cada um dos seguintes papéis predefinidos do IAM inclui a permissão necessária:

roles/bigquery.user
roles/bigquery.dataViewer
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.metadataViewer
roles/bigquery.resourceAdmin
roles/bigquery.admin

Para mais informações sobre as permissões do BigQuery, consulte Controle de acesso com o IAM.

Esquema

Quando você consulta as visualizações INFORMATION_SCHEMA da API BigQuery Storage Write, os resultados da consulta contêm informações históricas e em tempo real sobre a ingestão de dados no BigQuery usando a API BigQuery Storage Write. Cada linha nas visualizações a seguir representa estatísticas para ingestão em uma tabela específica, agregadas em um intervalo de um minuto a partir de start_timestamp. As estatísticas são agrupadas por tipo de stream e código de erro. Portanto, haverá uma linha para cada tipo de stream e cada um encontrou o código do erro durante o intervalo de um minuto para cada combinação de carimbo de data/hora e tabela. As solicitações bem-sucedidas têm o código do erro definido como OK. Se nenhum dado foi ingerido em uma tabela durante um determinado período, nenhuma linha estará presente para os carimbos de data/hora correspondentes dessa tabela.

As visualizações INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_* têm o seguinte esquema:

Nome da coluna	Tipo de dados	Valor
`start_timestamp`	`TIMESTAMP`	(Coluna de particionamento) Carimbo de data/hora de início do intervalo de 1 minuto das estatísticas agregadas.
`project_id`	`STRING`	(Coluna de clustering) ID do projeto.
`project_number`	`INTEGER`	Número do projeto.
`dataset_id`	`STRING`	(Coluna de clustering) ID do conjunto de dados.
`table_id`	`STRING`	(Coluna de clustering) ID da tabela.
`stream_type`	`STRING`	O tipo de stream usado para a ingestão de dados com a API BigQuery Storage Write. Deve ser "DEFAULT", "COMMITTED", "BUFFERED" ou "PENDING".
`error_code`	`STRING`	Código de erro retornado para as solicitações especificadas por essa linha. "OK" para solicitações bem-sucedidas.
`total_requests`	`INTEGER`	Número total de solicitações dentro do intervalo de 1 minuto.
`total_rows`	`INTEGER`	Número total de linhas de todas as solicitações dentro do intervalo de 1 minuto.
`total_input_bytes`	`INTEGER`	Número total de bytes de todas as linhas dentro do intervalo de um minuto.

Retenção de dados

Esta visualização contém o histórico de processamento dos últimos 180 dias da API BigQuery Storage Write.

Escopo e sintaxe

As consultas nessa visualização precisam incluir um qualificador de região. Se você não especificar um qualificador regional, os metadados serão recuperados de todas as regiões. A tabela a seguir explica o escopo da região dessa visualização:

Nome da visualização	Escopo do recurso	Escopo da região
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.WRITE_API_TIMELINE[_BY_PROJECT]	Nível do projeto	`REGION`

Substitua:

Opcional: PROJECT_ID: o ID do seu projeto do Google Cloud. Se não for especificado, o projeto padrão será usado.

+ REGION: qualquer nome da região do conjunto de dados. Por exemplo, region-us.

Observação: é necessário usar um qualificador de região para consultar visualizações INFORMATION_SCHEMA. O local de execução da consulta precisa corresponder à região da visualização INFORMATION_SCHEMA.

Exemplo

Para consultar dados na multirregião EUA, use `region-us`.INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT.
Para consultar dados na multirregião UE, utilize `region-eu`.INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT.
Para consultar dados na região asia-northeast1, use `region-asia-northeast1`.INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT.

Para obter uma lista de regiões disponíveis, consulte locais do conjunto de dados.

Exemplos

Exemplo 1: falhas recentes na ingestão da API BigQuery Storage Write

O exemplo a seguir calcula o detalhamento por minuto do total de solicitações com falha de todas as tabelas do projeto nos últimos 30 minutos, dividido pelo tipo de transmissão e o código de erro:

SELECT
  start_timestamp,
  stream_type,
  error_code,
  SUM(total_requests) AS num_failed_requests
FROM
  `region-us`.INFORMATION_SCHEMA.WRITE_API_TIMELINE
WHERE
  error_code != 'OK'
  AND start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP, INTERVAL 30 MINUTE)
GROUP BY
  start_timestamp,
  stream_type,
  error_code
ORDER BY
  start_timestamp DESC;

O resultado será semelhante ao seguinte:

+---------------------+-------------+------------------+---------------------+
|   start_timestamp   | stream_type |    error_code    | num_failed_requests |
+---------------------+-------------+------------------+---------------------+
| 2023-02-24 00:25:00 | PENDING     | NOT_FOUND        |                   5 |
| 2023-02-24 00:25:00 | DEFAULT     | INVALID_ARGUMENT |                   1 |
| 2023-02-24 00:25:00 | DEFAULT     | DEADLINE_EXCEEDED|                   4 |
| 2023-02-24 00:24:00 | PENDING     | INTERNAL         |                   3 |
| 2023-02-24 00:24:00 | DEFAULT     | INVALID_ARGUMENT |                   1 |
| 2023-02-24 00:24:00 | DEFAULT     | DEADLINE_EXCEEDED|                   2 |
+---------------------+-------------+------------------+---------------------+

Exemplo 2: detalhamento por minuto de todas as solicitações com códigos de erro

O exemplo a seguir calcula um detalhamento por minuto de solicitações de anexo bem-sucedidas e com falha, divididas em categorias de código de erro. Essa consulta pode ser usada para preencher um painel.

SELECT
  start_timestamp,
  SUM(total_requests) AS total_requests,
  SUM(total_rows) AS total_rows,
  SUM(total_input_bytes) AS total_input_bytes,
  SUM(
    IF(
      error_code IN (
        'INVALID_ARGUMENT', 'NOT_FOUND', 'CANCELLED', 'RESOURCE_EXHAUSTED',
        'ALREADY_EXISTS', 'PERMISSION_DENIED', 'UNAUTHENTICATED',
        'FAILED_PRECONDITION', 'OUT_OF_RANGE'),
      total_requests,
      0)) AS user_error,
  SUM(
    IF(
      error_code IN (
        'DEADLINE_EXCEEDED','ABORTED', 'INTERNAL', 'UNAVAILABLE',
        'DATA_LOSS', 'UNKNOWN'),
      total_requests,
      0)) AS server_error,
  SUM(IF(error_code = 'OK', 0, total_requests)) AS total_error,
FROM
  `region-us`.INFORMATION_SCHEMA.WRITE_API_TIMELINE
GROUP BY
  start_timestamp
ORDER BY
  start_timestamp DESC;

O resultado será semelhante ao seguinte:

+---------------------+----------------+------------+-------------------+------------+--------------+-------------+
|   start_timestamp   | total_requests | total_rows | total_input_bytes | user_error | server_error | total_error |
+---------------------+----------------+------------+-------------------+------------+--------------+-------------+
| 2020-04-15 22:00:00 |         441854 |     441854 |       23784853118 |          0 |           17 |          17 |
| 2020-04-15 21:59:00 |         355627 |     355627 |       26101982742 |          8 |            0 |          13 |
| 2020-04-15 21:58:00 |         354603 |     354603 |       26160565341 |          0 |            0 |           0 |
| 2020-04-15 21:57:00 |         298823 |     298823 |       23877821442 |          2 |            0 |           2 |
+---------------------+----------------+------------+-------------------+------------+--------------+-------------+

Exemplo 3: tabelas com o maior tráfego de entrada

O exemplo a seguir retorna as estatísticas de ingestão da API BigQuery Storage Write para as 10 tabelas com mais tráfego de entrada:

SELECT
  project_id,
  dataset_id,
  table_id,
  SUM(total_rows) AS num_rows,
  SUM(total_input_bytes) AS num_bytes,
  SUM(total_requests) AS num_requests
FROM
  `region-us`.INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT
GROUP BY
  project_id,
  dataset_id,
  table_id
ORDER BY
  num_bytes DESC
LIMIT 10;

O resultado será semelhante ao seguinte:

+----------------------+------------+-------------------------------+------------+----------------+--------------+
|      project_id      | dataset_id |           table_id            |  num_rows  |   num_bytes    | num_requests |
+----------------------+------------+-------------------------------+------------+----------------+--------------+
| my-project           | dataset1   | table1                        | 8016725532 | 73787301876979 |   8016725532 |
| my-project           | dataset1   | table2                        |   26319580 | 34199853725409 |     26319580 |
| my-project           | dataset2   | table1                        |   38355294 | 22879180658120 |     38355294 |
| my-project           | dataset1   | table3                        |  270126906 | 17594235226765 |    270126906 |
| my-project           | dataset2   | table2                        |   95511309 | 17376036299631 |     95511309 |
| my-project           | dataset2   | table3                        |   46500443 | 12834920497777 |     46500443 |
| my-project           | dataset2   | table4                        |   25846270 |  7487917957360 |     25846270 |
| my-project           | dataset1   | table4                        |   18318404 |  5665113765882 |     18318404 |
| my-project           | dataset1   | table5                        |   42829431 |  5343969665771 |     42829431 |
| my-project           | dataset1   | table6                        |    8771021 |  5119004622353 |      8771021 |
+----------------------+------------+-------------------------------+------------+----------------+--------------+

Exemplo 4: proporção de erros de ingestão da API BigQuery Storage Write em uma tabela

No exemplo a seguir, calculamos uma análise detalhada dos erros por dia em uma tabela específica, dividida por código de erro:

SELECT
  TIMESTAMP_TRUNC(start_timestamp, DAY) as day,
  project_id,
  dataset_id,
  table_id,
  error_code,
  SUM(total_rows) AS num_rows,
  SUM(total_input_bytes) AS num_bytes,
  SUM(total_requests) AS num_requests
FROM
  `region-us`.INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT
WHERE
  table_id LIKE 'my_table'
GROUP BY
  project_id, dataset_id, table_id, error_code, day
ORDER BY
  day, project_id, dataset_id DESC;

O resultado será semelhante ao seguinte:

+---------------------+-------------+------------+----------+----------------+----------+-----------+--------------+
|         day         |  project_id | dataset_id | table_id |   error_code   | num_rows | num_bytes | num_requests |
+---------------------+-------------+------------+----------+----------------+----------+-----------+--------------+
| 2020-04-21 00:00:00 | my_project  | my_dataset | my_table | OK             |       41 |    252893 |           41 |
| 2020-04-20 00:00:00 | my_project  | my_dataset | my_table | OK             |     2798 |  10688286 |         2798 |
| 2020-04-19 00:00:00 | my_project  | my_dataset | my_table | OK             |     2005 |   7979495 |         2005 |
| 2020-04-18 00:00:00 | my_project  | my_dataset | my_table | OK             |     2054 |   7972378 |         2054 |
| 2020-04-17 00:00:00 | my_project  | my_dataset | my_table | OK             |     2056 |   6978079 |         2056 |
| 2020-04-17 00:00:00 | my_project  | my_dataset | my_table | INTERNAL       |        4 |     10825 |            4 |
+---------------------+-------------+------------+----------+----------------+----------+-----------+--------------+