Usar o Dataflow SQL

Cuidado: o Dataflow SQL está descontinuado. Desde 31 de julho de 2024, não é mais possível acessar o Dataflow SQL no console do Google Cloud. A partir de 31 de janeiro de 2025, não será mais possível usar o Dataflow SQL na CLI do Google Cloud. Para informações sobre métodos alternativos de criação de consultas SQL com o Dataflow, consulte o comando mágico do Beam SQL e beam_sql.

Esta página explica como usar o SQL do Dataflow e como criar jobs do SQL do Dataflow.

Para criar um job do SQL do Dataflow, write e execute uma consulta do SQL do Dataflow.

Observação: para usar o Dataflow SQL, talvez seja necessário ativar a API Data Catalog no projeto do Google Cloud que você está usando para escrever e executar consultas. Para executar consultas do Dataflow SQL, sua conta de usuário precisa ter o papel Administrador do Storage para criar e gravar em um bucket de armazenamento temporário.

Usar o editor do Dataflow SQL

O editor do Dataflow SQL é uma página no Console do Google Cloud em que você grava e executa consultas para criar jobs do Dataflow SQL.

Para acessar o editor do Dataflow SQL, siga estas etapas:

• No console do Google Cloud, acesse a página Editor SQL do Dataflow.

  Acessar o editor do SQL do Dataflow

Também é possível acessar o editor SQL do Dataflow na interface de monitoramento do Dataflow seguindo estas etapas:

1. No console do Google Cloud, acesse a página Jobs do Dataflow.

   Acessar "Jobs"

2. No menu de navegação, clique em Espaço de trabalho do SQL.

Criar consultas SQL do Dataflow

As consultas do SQL do Dataflow usam a sintaxe de consulta SQL do Dataflow. A sintaxe de consulta SQL do Dataflow é semelhante ao SQL padrão do BigQuery.

É possível usar as extensões de streaming do SQL do Dataflow para agregar dados de fontes do Dataflow de atualização contínua, como o Pub/Sub.

Por exemplo, a consulta a seguir conta os passageiros em um fluxo do Pub/Sub de corridas de táxi a cada minuto:

SELECT
  DATETIME(tr.window_start) AS starttime,
  SUM(tr.passenger_count) AS pickup_count
FROM TUMBLE ((SELECT * FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`),
DESCRIPTOR(event_timestamp), 'INTERVAL 1 MINUTE') AS tr
WHERE
  tr.ride_status = "pickup"
GROUP BY DATETIME(tr.window_start)

Executar consultas SQL do Dataflow

Quando você executa uma consulta do SQL do Dataflow, o Dataflow transforma a consulta em um pipeline do Apache Beam e executa o pipeline.

É possível executar uma consulta SQL do Dataflow usando o console do Google Cloud ou a CLI do Google Cloud.

Console

Para executar uma consulta do SQL do Dataflow, use editor do SQL do Dataflow:

1. Acesse a página Editor do SQL do Dataflow.

   Acessar o editor do SQL do Dataflow

2. Digite a consulta do Dataflow SQL no editor de consultas.

3. Clique em Criar job para abrir um painel de opções de job.

4. (Opcional) Em Nome do job, digite um nome exclusivo.

5. Em Endpoint regional, selecione um valor no menu.

6. Opcional: clique em Mostrar parâmetros opcionais e insira valores para as opções de pipeline do Dataflow fornecidas.

7. Em Destino, selecione um Tipo de saída e insira valores nos campos fornecidos.

8. Opcional: na seção Parâmetros de consulta SQL, adicione parâmetros e insira valores nos campos fornecidos.

9. Clique em Criar.

Observação: iniciar um job do SQL do Dataflow pode levar vários minutos. Não é possível atualizar um job do SQL do Dataflow depois de criá-lo.

gcloud

Para executar uma consulta do SQL do Dataflow, use o comando gcloud dataflow sql query. Veja a seguir um exemplo de consulta SQL que cria

gcloud dataflow sql query \
  --job-name=JOB_NAME \
  --region=REGION \
  --bigquery-table=BIGQUERY_TABLE \
  --bigquery-dataset=BIGQUERY_DATASET \
  --bigquery-project=BIGQUERY_PROJECT \
'SQL_QUERY'

Substitua:

• JOB_NAME: um nome para o job do Dataflow SQL;
• REGION: o local do Dataflow para implantar o job do Dataflow.
• BIGQUERY_TABLE: o nome da tabela do BigQuery em que você quer gravar a saída;
• BIGQUERY_DATASET: o ID do conjunto de dados do BigQuery que contém a tabela de saída;
• BIGQUERY_PROJECT: o ID do projeto do Google Cloud que contém a tabela de saída do BigQuery.
• SQL_QUERY: a consulta do Dataflow SQL.

Observação: iniciar um job do SQL do Dataflow pode levar vários minutos. Não é possível atualizar um job do SQL do Dataflow depois de criá-lo.

Definir opções de canal

É possível definir opções do pipeline do Dataflow para jobs do SQL do Dataflow. As opções de pipeline do Dataflow são parâmetros de execução que configuram como e onde executar consultas do SQL do Dataflow.

Para definir opções de pipeline para jobs do SQL do Dataflow, especifique os seguintes parâmetros ao executar uma consulta do SQL do Dataflow.

Console

Parâmetro	Tipo	Descrição	Valor padrão
Endpoint regional	String	A região em que a consulta será executada. As consultas SQL do Dataflow podem ser executadas em regiões que têm um local do Dataflow.	Se não for definido, o padrão será us-central1..
Número máximo de workers	int	O número máximo de instâncias do Compute Engine disponíveis para o pipeline durante a execução.	Se não tiver sido especificado, um número adequado de workers será determinado pelo serviço do Dataflow.
Região do worker	String	A região do Compute Engine para iniciar instâncias de worker para executar o pipeline. A região do worker do Compute Engine pode estar em uma região diferente da do job do Dataflow.	Se não for definido, o padrão será a região especificada do Dataflow.
Zona do worker	String	A zona do Compute Engine para inicialização de instâncias de worker a fim de executar o pipeline. A zona do Compute Engine pode estar em uma região diferente da região do job do Dataflow.	Se não for definido, o padrão usado será uma zona na região do worker. Se a região do worker não for definida, o padrão será uma zona na região especificada do Dataflow.
E-mail da conta de serviço	String	O endereço de e-mail da conta de serviço do worker com que o pipeline será executado. O endereço de e-mail precisa estar no formato my-service-account-name@<project-id>.iam.gserviceaccount.com.	Se não for definido, os workers do Dataflow usarão a conta de serviço do Compute Engine do projeto atual como a conta de serviço do worker.
Tipo de máquina	String	O tipo de máquina do Compute Engine que o Dataflow usa ao iniciar os workers. É possível usar qualquer uma das famílias de tipos de máquinas do Compute Engine disponíveis, bem como tipos de máquinas personalizadas. Para melhores resultados, use tipos de máquina n1. Os tipos de máquina com núcleo compartilhado, como workers da série f1 e g1, não recebem suporte de acordo com o Contrato de nível de serviço do Dataflow. O Dataflow cobra pelo número de vCPUs e GB de memória nos workers. O faturamento não depende da família de tipos de máquinas.	Se não for definido, o Dataflow escolherá automaticamente o tipo de máquina.
Outros experimentos	String	Os experimentos a ativar. Um experimento pode ser um valor, como enable_streaming_engine, ou um par de chave-valor, como shuffle_mode=service. Os experimentos precisam estar em uma lista separada por vírgulas.	Se não for especificado, nenhum experimento será ativado.
Configuração do endereço IP do worker	String	Especifica se os workers do Cloud Dataflow usarão endereços IP públicos. Se o valor estiver definido como Private, os workers do Dataflow usarão endereços IP privados para todas as comunicações. O Network ou o Subnetwork especificado precisam ter o Acesso particular do Google ativado. Se o valor for definido como Private e a opção Subnetwork for especificada, a opção Network será ignorada.	Se não for definido, o padrão será Public.
Rede	String	A rede do Compute Engine à qual os workers são atribuídos.	Se não for definido, o padrão será a rede default.
Sub-rede	String	A sub-rede do Compute Engine à qual os workers são atribuídos. A sub-rede precisa estar no formato regions/region/subnetworks/subnetwork.	Se não for definido, o Dataflow determinará automaticamente a sub-rede.

gcloud

Sinalizar	Tipo	Descrição	Valor padrão
‑‑region	String	A região em que a consulta será executada. As consultas SQL do Dataflow podem ser executadas em regiões que têm um local do Dataflow.	Se não está definido, um erro é emitido.
‑‑max‑workers	int	O número máximo de instâncias do Compute Engine disponíveis para o pipeline durante a execução.	Se não for especificado, o Dataflow determinará automaticamente um número apropriado de workers.
‑‑num‑workers	int	O número inicial de instâncias do Compute Engine a serem usadas na execução do pipeline. Esse parâmetro determina quantos workers são iniciados no Dataflow quando o job começa.	Se não for especificado, o Dataflow determinará automaticamente um número apropriado de workers.
‑‑worker‑region	String	A região do Compute Engine para iniciar instâncias de worker a fim de executar o pipeline. A região do worker do Compute Engine pode estar em uma região diferente da do job do Dataflow. É possível especificar ‑‑worker‑region ou ‑‑worker‑zone.	Se não for definido, o padrão será a região especificada do Dataflow.
‑‑worker‑zone	String	A zona do Compute Engine para inicialização de instâncias de worker a fim de executar o pipeline. A zona do Compute Engine pode estar em uma região diferente da região do job do Dataflow. É possível especificar ‑‑worker‑region ou ‑‑worker‑zone.	Se não for definido, o padrão será uma zona na região especificada do Dataflow.
‑‑worker‑machine‑type	String	O tipo de máquina do Compute Engine que o Dataflow usa ao iniciar os workers. É possível usar qualquer uma das famílias de tipos de máquinas do Compute Engine disponíveis, bem como tipos de máquinas personalizadas. Para melhores resultados, use tipos de máquina n1. Os tipos de máquina com núcleo compartilhado, como workers da série f1 e g1, não recebem suporte de acordo com o Contrato de nível de serviço do Dataflow. O Dataflow cobra pelo número de vCPUs e GB de memória nos workers. O faturamento não depende da família de tipos de máquinas.	Se não for definido, o Dataflow escolherá automaticamente o tipo de máquina.
‑‑service‑account‑email	String	O endereço de e-mail da conta de serviço do worker com que o pipeline será executado. O endereço de e-mail precisa estar no formato my-service-account-name@<project-id>.iam.gserviceaccount.com.	Se não for definido, os workers do Dataflow usarão a conta de serviço do Compute Engine do projeto atual como a conta de serviço do worker.
‑‑disable‑public‑ips	boolean	Especifica se os workers do Cloud Dataflow usarão endereços IP públicos. Se definidos, os workers do Dataflow usam endereços IP particulares para todas as comunicações.	Se não forem definidos, os workers do Dataflow usarão endereços IP públicos.
‑‑network	String	A rede do Compute Engine à qual os workers são atribuídos.	Se não for definido, o padrão será a rede default.
‑‑subnetwork	String	A sub-rede do Compute Engine à qual os workers são atribuídos. A sub-rede precisa estar no formato regions/region/subnetworks/subnetwork.	Se não for definido, o Dataflow determinará automaticamente a sub-rede.
‑‑dataflow‑kms‑key	String	A chave de criptografia gerenciada pelo cliente (CMEK, na sigla em inglês) usada para criptografar dados em repouso. É possível controlar a chave de criptografia usando o Cloud KMS. A chave precisa estar no mesmo local do job.	Se não for especificado, o Dataflow usará a criptografia padrão do Google Cloud em vez de um CMEK.

Para mais informações, consulte a referência do comando gcloud dataflow sql query.

Observação: os jobs do SQL do Dataflow usam escalonamento automático e o Dataflow escolhe automaticamente o modo de execução (lote ou streaming). Não é possível controlar esse comportamento para jobs do SQL do Dataflow.

Interromper jobs do Dataflow SQL

Para interromper um job do Dataflow SQL, é necessário cancelar. Não é possível interromper um job do SQL do Dataflow com a opção drain.

Preços

O SQL do Dataflow usa os preços padrão do Dataflow. Ele não tem preços separados. Você é cobrado pelos recursos consumidos pelos jobs do Dataflow criados com base nas suas instruções SQL. As cobranças para esses recursos são as cobranças padrão do Dataflow para vCPU, memória, disco permanente, Streaming Engine e Dataflow Shuffle.

Um job do SQL do Dataflow pode consumir recursos adicionais, como o Pub/Sub e o BigQuery, cada um cobrado de acordo com os próprios preços.

Para obter mais informações sobre preços do Dataflow, consulte Preços do Dataflow.

A seguir

• Veja o tutorial Como mesclar dados de streaming com o SQL do Dataflow.
• Explore a CLI do Google Cloud para o Dataflow SQL.