Visualização INFORMATION_SCHEMA.SHARED_DATASET_USAGE

A visualização INFORMATION_SCHEMA.SHARED_DATASET_USAGE contém os metadados quase em tempo real sobre o consumo das tabelas de conjuntos de dados compartilhados. Para começar a compartilhar seus dados entre organizações, consulte o Analytics Hub.

Funções exigidas

Para receber a permissão necessária para consultar a visualização INFORMATION_SCHEMA.SHARED_DATASET_USAGE, peça ao administrador para conceder a você o papel do IAM proprietário de dados do BigQuery (roles/bigquery.dataOwner) no seu projeto de origem. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém a permissão bigquery.datasets.listSharedDatasetUsage, que é necessária para consultar a visualização INFORMATION_SCHEMA.SHARED_DATASET_USAGE.

Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Esquema

Os dados subjacentes são particionados pela coluna job_start_time e agrupados por project_id e dataset_id.

INFORMATION_SCHEMA.SHARED_DATASET_USAGE tem o seguinte esquema:

Nome da coluna Tipo de dado Valor
project_id STRING (Coluna de clustering) O ID do projeto que contém o conjunto de dados compartilhado.
dataset_id STRING (Coluna de clustering) O ID do conjunto de dados compartilhado.
table_id STRING O ID da tabela acessada.
data_exchange_id STRING O caminho do recurso da troca de dados.
listing_id STRING O caminho do recurso da listagem.
job_start_time TIMESTAMP (Coluna de particionamento) O horário de início deste job.
job_end_time TIMESTAMP O horário de término deste job.
job_id STRING O ID do job. Por exemplo, bquxjob_1234.
job_project_number INTEGER O número do projeto a que este job pertence.
job_location STRING O local do job.
linked_project_number INTEGER O número do projeto do assinante.
linked_dataset_id STRING O ID do conjunto de dados vinculado do conjunto de dados do assinante.
subscriber_org_number INTEGER O número da organização em que o job foi executado. Esse é o número da organização do assinante. Este campo está vazio para projetos que não têm uma organização.
subscriber_org_display_name STRING Uma string legível por humanos que se refere à organização em que o job foi executado. Esse é o número da organização do assinante. Este campo está vazio para projetos que não têm uma organização.
num_rows_processed INTEGER O número de linhas processadas dessa tabela pelo job.
total_bytes_processed INTEGER O total de bytes processados dessa tabela pelo job.

Retenção de dados

A visualização INFORMATION_SCHEMA.SHARED_DATASET_USAGE contém jobs em execução e o histórico de jobs dos últimos 180 dias.

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 da região dos EUA. A tabela a seguir explica o escopo da região dessa visualização:

Acessar nome Escopo do recurso Escopo da região
[PROJECT_ID.]INFORMATION_SCHEMA.SHARED_DATASET_USAGE Nível do projeto Região dos EUA
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.SHARED_DATASET_USAGE 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.

Exemplos

Para executar a consulta em um projeto diferente do projeto padrão, adicione o ID do projeto no seguinte formato:

PROJECT_ID.region-REGION_NAME.INFORMATION_SCHEMA.SHARED_DATASET_USAGE

Por exemplo, myproject.region-us.INFORMATION_SCHEMA.SHARED_DATASET_USAGE.

Conferir o número total de jobs executados em todas as tabelas compartilhadas

O exemplo a seguir calcula o total de jobs executados por assinantes em um projeto:

SELECT
  COUNT(DISTINCT job_id) AS num_jobs
FROM
  `region-us`.INFORMATION_SCHEMA.SHARED_DATASET_USAGE

O resultado será semelhante ao seguinte:

+------------+
| num_jobs   |
+------------+
| 1000       |
+------------+

Para verificar o total de jobs executados pelos assinantes, use a cláusula WHERE:

  • Para conjuntos de dados, use WHERE dataset_id = "...".
  • Para tabelas, use WHERE dataset_id = "..." AND table_id = "...".

Acessar a tabela mais usada com base no número de linhas processadas

A consulta a seguir calcula a tabela mais usada com base no número de linhas processadas pelos assinantes.

SELECT
  dataset_id,
  table_id,
  SUM(num_rows_processed) AS usage_rows
FROM
  `region-us`.INFORMATION_SCHEMA.SHARED_DATASET_USAGE
GROUP BY
  1,
  2
ORDER BY
  3 DESC
LIMIT
  1

O resultado será assim:

+---------------+-------------+----------------+
| dataset_id    | table_id      | usage_rows     |
+---------------+-------------+----------------+
| mydataset     | mytable     | 15             |
+---------------+-------------+----------------+

Encontrar as principais organizações que consomem suas tabelas

A consulta a seguir calcula os principais assinantes com base no número de bytes processados nas tabelas. Também é possível usar a coluna num_rows_processed como métrica.

SELECT
  subscriber_org_number,
  ANY_VALUE(subscriber_org_display_name) AS subscriber_org_display_name,
  SUM(total_bytes_processed) AS usage_bytes
FROM
  `region-us`.INFORMATION_SCHEMA.SHARED_DATASET_USAGE
GROUP BY
  1

O resultado será assim:

+--------------------------+--------------------------------+----------------+
|subscriber_org_number     | subscriber_org_display_name    | usage_bytes    |
+-----------------------------------------------------------+----------------+
| 12345                    | myorganization                 | 15             |
+--------------------------+--------------------------------+----------------+

Para assinantes sem uma organização, use job_project_number em vez de subscriber_org_number.

Receber métricas de uso para sua troca de dados

Se a troca de dados e o conjunto de dados de origem estiverem em projetos diferentes, siga estas etapas para visualizar as métricas de uso da troca de dados:

  1. Encontre todas as listagens que pertencem à sua troca de dados.
  2. Recupere o conjunto de dados de origem anexado à página de detalhes.
  3. Para visualizar as métricas de uso da sua troca de dados, use a seguinte consulta:
SELECT
  *
FROM
  source_project_1.`region-us`.INFORMATION_SCHEMA.SHARED_DATASET_USAGE
WHERE
  dataset_id='source_dataset_id'
AND data_exchange_id="projects/4/locations/us/dataExchanges/x1"
UNION ALL
SELECT
  *
FROM
  source_project_2.`region-us`.INFORMATION_SCHEMA.SHARED_DATASET_USAGE
WHERE
  dataset_id='source_dataset_id'
AND data_exchange_id="projects/4/locations/us/dataExchanges/x1"