FlowsGuia

Passos SQL em flows

Um passo SQL roda uma consulta numa das conexões PostgreSQL ou MySQL do projeto, e as linhas viram a saída do passo — prontas para um loop, um Transformar, um e-mail ou um script abaixo. Com um passo SQL, um loop e um passo Enviar e-mail, uma campanha inteira roda sem nenhum script.

9 min de leituraAntes: O que é um flow, IntegraçõesAbrir no Waiso
O que você vai aprender
  • Adicionar um passo SQL e dar uma conexão a ele
  • Passar valores do flow para a consulta como parâmetros :name
  • Ler a saída, o limite de linhas e a marca limited
  • Percorrer as linhas, inclusive resultados grandes demais para passar direto

Uma consulta como passo

No menu Adicionar nó, PostgreSQL e MySQL ficam ao lado das linguagens de script em Scripts. Escolher um deles adiciona um passo cujo código é SQL; Script existente vincula um script SQL do projeto. De um jeito ou de outro o passo roda no banco pela conexão do projeto — as credenciais nunca chegam ao seu código — e responde com as linhas como objetos com o nome de cada coluna.

Um passo PostgreSQL soma o dia, um passo MySQL grava os totais, um e-mail os envia — nenhum passo de script.
Saída esperadaSucessoA saída de um passo SQL
{
  "columns": [
    "region",
    "total"
  ],
  "rows": [
    {
      "region": "South",
      "total": 1840.5
    },
    {
      "region": "North",
      "total": 1312
    }
  ],
  "rowCount": 2,
  "count": 2,
  "durationMs": 4,
  "warnings": [],
  "limited": false,
  "limit": 10000
}

Colunas numeric, date, time, timestamp e UUID são convertidas em valores JSON — um total numeric chega como número — então o próximo passo já pode ligar rows.0.total.

Dê uma conexão a ele

  1. Adicione o passo

    Clique num + e escolha PostgreSQL ou MySQL em Scripts.

  2. Abra o código

    Clique no passo e depois em Abrir editor de código. Escreva a consulta; os parâmetros declarados aparecem na aba Parâmetros.

  3. Escolha a conexão

    Na aba Conexão, escolha uma conexão do mesmo motor em Para este passo. Um script SQL vinculado mostra o próprio padrão (Padrão do script: crm-db); uma conexão escolhida no passo vence o padrão, e Usar o padrão do script volta para ele.

  4. Defina o limite de linhas

    Limite de linhas, na mesma aba, é quantas linhas a consulta pode devolver — 10.000 se você não mudar, até 100.000.

Parâmetros numa consulta

Declare cada entrada num cabeçalho -- @param e use como :name na instrução. O valor vai para o banco como um parâmetro de verdade, nunca colado no texto, então um valor nunca muda a consulta. No passo, ligue cada parâmetro como qualquer outra entrada — From node, Expression, Variável ou uma constante.

active_customers.pg.sql
PostgreSQL
-- @param min_total number = 100
-- @param country string = BR
SELECT id, email, first_name AS "First Name", total
FROM customers
WHERE active AND total >= :min_total AND country = :country
ORDER BY total DESC;

O limite de linhas e “limited”

Uma leitura — uma instrução que começa com SELECT ou WITH — é envolvida para o limite valer qualquer que seja a forma da consulta: SELECT * FROM (<sua consulta>) AS _waiso LIMIT n+1. O seu próprio LIMIT continua valendo quando é menor. A linha a mais separa “exatamente n” de “mais que n”: quando havia mais, a saída diz limited: true com o limit, e o cabeçalho do passo na execução mostra Limitado a 10.000 linhas. Escritas (INSERT, UPDATE, DELETE…) nunca são envolvidas; as linhas que devolvem continuam limitadas.

OndeLinhas devolvidas
Um passo SQL num flow (e a execução de um script SQL)10.000 por padrão, até 100.000
O SQL Workbench500 — ele serve para olhar, não para mover dados

Percorrendo as linhas

Defina os Items de um loop como From Node → o passo SQL e ele percorre as rows sozinho; o painel mostra as colunas (Cada linha: id · email · First Name). Dentro do corpo, ligue item.email, item["First Name"] e index. Um loop em paralelo com um passo Enviar e-mail dentro envia a lista inteira em ondas de até 20.

Resultados grandes

As linhas passam direto entre os passos até 5 MB. Um resultado maior que isso fica guardado no bucket S3 do projeto — ou no da plataforma, se o projeto não tiver um — e a saída muda de forma: rows fica vazio, preview guarda as primeiras 100 linhas, offloaded vale true e downloadPath aponta para o resultado inteiro. O painel do passo avisa Resultado grande — ele passa entre os passos pelo S3.

Saída esperadaSucessoUm resultado guardado fora (prévia cortada em uma linha aqui)
{
  "columns": [
    "id",
    "email"
  ],
  "rows": [],
  "preview": [
    {
      "id": 1,
      "email": "ana@example.com"
    }
  ],
  "offloaded": true,
  "sizeBytes": 7340032,
  "rowCount": 61234,
  "count": 61234,
  "limited": false,
  "limit": 100000,
  "downloadPath": "/api/projects/<project>/runs/<run>/result"
}
  • Um loop ligado a ele continua percorrendo todas as linhas: ele as lê do armazenamento numa página de 1.000 por vez.
  • Um passo de script ligado a rows recebe a referência do resultado guardado, com o downloadPath, em vez das linhas — e lê as linhas de lá.
  • downloadPath responde com um link de download de curta duração; quando o objeto guardado não existe mais, responde 410 result_unavailable.

Limites

  • Uma instrução por passo para o limite valer: um script com várias instruções roda como foi escrito e só as linhas devolvidas são limitadas.
  • Limite de linhas: de 1 a 100.000 (10.000 por padrão). Resultados diretos até 5 MB; maiores vão para o armazenamento.
  • A conexão precisa ser do motor do passo — um passo PostgreSQL não usa uma conexão MySQL.

Assuntos relacionados