{"id":1275,"date":"2020-11-17T07:34:59","date_gmt":"2020-11-17T07:34:59","guid":{"rendered":"https:\/\/www.gudusoft.com\/?page_id=1275"},"modified":"2026-07-13T18:34:43","modified_gmt":"2026-07-14T02:34:43","slug":"sqlflow-restful-api","status":"publish","type":"page","link":"https:\/\/www.gudusoft.com\/pt\/api-restful-sqlflow\/","title":{"rendered":"API REST do SQLFlow: Automatize a extra\u00e7\u00e3o da linhagem de dados SQL"},"content":{"rendered":"

UM API de linhagem de dados<\/strong> Permite extrair a linhagem programaticamente: voc\u00ea envia o c\u00f3digo SQL via HTTP e recebe um gr\u00e1fico de linhagem estruturado em JSON, listando cada tabela e coluna de origem, cada destino e as rela\u00e7\u00f5es de transforma\u00e7\u00e3o entre eles. API REST Gudu SQLFlow<\/strong> Faz exatamente isso para 39 dialetos SQL, com granularidade em n\u00edvel de coluna, incluindo procedimentos armazenados e SQL din\u00e2mico. A mesma an\u00e1lise que alimenta os diagramas interativos do SQLFlow est\u00e1 dispon\u00edvel como dados de linhagem estruturados via HTTP.<\/p>\n\n\n\n

\n
39<\/b>dialetos SQL, cada um com um analisador sint\u00e1tico dedicado.<\/span><\/div>\n
N\u00edvel da coluna<\/b>gr\u00e1fico de linhagem, direta e indireta<\/span><\/div>\n
JSON<\/b>via HTTP \u2014 um POST, entrada SQL, sa\u00edda gr\u00e1fica<\/span><\/div>\n
Zero<\/b>Acesso aos seus dados \u2014 somente an\u00e1lise est\u00e1tica<\/span><\/div>\n<\/div>\n\n\n\n
\n\n

Veja primeiro o resultado:<\/strong> Cole uma consulta no Visualizador de linhagem SQLFlow gratuito<\/a>Em seguida, exporte o gr\u00e1fico como JSON para ver como a linhagem se apresenta como dados antes de escrever uma \u00fanica linha de c\u00f3digo de integra\u00e7\u00e3o.<\/p>\n\n<\/div><\/div>\n\n\n\n

Por que incluir uma API de linhagem de dados em sua infraestrutura?<\/h2>\n\n\n\n

Os diagramas de linhagem interativos s\u00e3o a forma como os humanos exploram a linhagem. Mas os usos de maior valor da linhagem s\u00e3o automatizados: bloquear uma solicita\u00e7\u00e3o de pull que silenciosamente quebra um relat\u00f3rio subsequente, manter a linhagem de um cat\u00e1logo de dados atualizada sem curadoria manual ou responder \u00e0 pergunta "o que alimenta esta coluna?" dentro de suas pr\u00f3prias ferramentas internas. Todos esses usos exigem linhagem como dados, sob demanda, de um servi\u00e7o que voc\u00ea pode invocar.<\/p>\n\n\n\n

A abordagem do SQLFlow \u00e9 a an\u00e1lise est\u00e1tica de SQL. A API analisa o texto SQL que voc\u00ea envia e nunca acessa as linhas das suas tabelas, o que mant\u00e9m a revis\u00e3o de seguran\u00e7a curta: a \u00fanica coisa que trafega pela rede \u00e9 o c\u00f3digo SQL, e com o edi\u00e7\u00e3o para instala\u00e7\u00e3o local<\/a> at\u00e9 isso permanece dentro da sua rede. O mecanismo subjacente \u00e9 o Analisador SQL geral<\/a>Trata-se de um front-end comercial para compilador SQL desenvolvido desde meados dos anos 2000 e validado com aproximadamente 13.600 conjuntos de testes por dialeto, portanto, a linhagem retornada \u00e9 constru\u00edda a partir de um modelo sem\u00e2ntico completo do SQL, e n\u00e3o de correspond\u00eancia com express\u00f5es regulares.<\/p>\n\n\n\n

O que a API REST do SQLFlow retorna<\/h2>\n\n\n\n

Conceitualmente, a API exp\u00f5e toda a superf\u00edcie de an\u00e1lise do SQLFlow como JSON sobre HTTP:<\/p>\n\n\n\n

\n
Capacidade<\/th>Voc\u00ea envia<\/th>Voc\u00ea volta<\/th><\/tr><\/thead>
Gr\u00e1fico de linhagem<\/td>Texto SQL mais um identificador de dialeto<\/td>O grafo de linhagem completo em n\u00edvel de coluna em formato JSON: tabelas, colunas e rela\u00e7\u00f5es de origem para destino.<\/td><\/tr>\n
rastreamento a montante\/a jusante<\/td>Uma tabela ou coluna de interesse<\/td>Apenas o subgrafo que alimenta esse objeto (a montante) ou que \u00e9 alimentado por ele (a jusante), para an\u00e1lise de impacto direcionada.<\/td><\/tr>\n
linhagem em n\u00edvel de tabela<\/td>Texto SQL, granularidade da tabela solicitada<\/td>Um gr\u00e1fico de depend\u00eancia compacto entre tabelas, quando o detalhamento das colunas seria irrelevante.<\/td><\/tr>\n
Linhagem direta versus indireta<\/td>Uma sinaliza\u00e7\u00e3o no pedido<\/td>Rela\u00e7\u00f5es de fluxo de dados puro, ou adicionalmente as colunas que moldam os resultados por meio de ONDE<\/code>, JUNTAR<\/code>, e AGRUPAR POR<\/code> cl\u00e1usulas<\/td><\/tr>\n
Gr\u00e1fico de chamadas de procedimentos armazenados<\/td>Corpos de procedimentos PL\/SQL ou T-SQL<\/td>Quais procedimentos invocam quais, com a linhagem rastreada por meio de par\u00e2metros, tabelas tempor\u00e1rias e SQL din\u00e2mico.<\/td><\/tr>\n
Diagrama ER<\/td>Scripts DDL<\/td>Rela\u00e7\u00f5es inferidas de chave prim\u00e1ria\/estrangeira como um modelo de entidade-relacionamento<\/td><\/tr>\n
Exporta\u00e7\u00f5es<\/td>Um trabalho analisado<\/td>JSON ou CSV para m\u00e1quinas, PNG para documenta\u00e7\u00e3o e bilhetes.<\/td><\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n

Cada solicita\u00e7\u00e3o especifica explicitamente seu dialeto. O SQLFlow fornece analisadores sint\u00e1ticos espec\u00edficos para 39 bancos de dados e mecanismos de consulta, desde Snowflake, BigQuery, Databricks e Redshift at\u00e9 Oracle, SQL Server, Teradata, Hive e Trino. Assim, a sintaxe espec\u00edfica do fornecedor, como tabelas tempor\u00e1rias T-SQL, \u00e9 analisada conforme definida pelo fornecedor, e n\u00e3o aproximada por uma gram\u00e1tica ANSI gen\u00e9rica. A lista completa est\u00e1 dispon\u00edvel em [link para a lista completa]. Vis\u00e3o geral da ferramenta de linhagem de dados SQL<\/a>.<\/p>\n\n\n\n

Um exemplo m\u00ednimo: POST SQL, recebe um gr\u00e1fico de linhagem.<\/h2>\n\n\n\n

A intera\u00e7\u00e3o principal consiste em uma chamada HTTP. Voc\u00ea envia um texto SQL e um dialeto; a resposta \u00e9 o grafo de linhagem. Os caminhos dos endpoints, a autentica\u00e7\u00e3o e a refer\u00eancia completa dos par\u00e2metros residem no... Documenta\u00e7\u00e3o da API SQLFlow<\/a>; o formato da troca de valores \u00e9 o seguinte:<\/p>\n\n\n\n

curl -s -X POST "$SQLFLOW_API\/lineage" \\ -H "Authorization: Bearer $SQLFLOW_TOKEN" \\ --form "dbvendor=snowflake" \\ --form 'sqltext=CREATE VIEW customer_ltv AS SELECT c.customer_id, SUM(o.amount) AS lifetime_value FROM customers c JOIN orders o ON o.customer_id = c.customer_id WHERE o.status = ''paid'' GROUP BY c.customer_id;'<\/code><\/pre>\n\n\n\n
A resposta \u00e9 um gr\u00e1fico: uma lista de objetos do banco de dados (tabelas, visualiza\u00e7\u00f5es e suas colunas) e uma lista de relacionamentos entre as colunas. (Vers\u00e3o reduzida e simplificada para fins de ilustra\u00e7\u00e3o)<\/p>\n\n\n\n
{ "relacionamentos": [ { "tipo": "direto", "alvo": {"objeto": "valor_vital\u00edcio_do_cliente", "coluna": "valor_vital\u00edcio"}, "fontes": [{"objeto": "pedidos", "coluna": "quantidade", "via": "SOMA"}] }, { "tipo": "direto", "alvo": {"objeto": "valor_vital\u00edcio_do_cliente", "coluna": "id_do_cliente"}, "fontes": [{"objeto": "clientes", "coluna": "id_do_cliente"}] }, { "tipo": "indireto", "alvo": {"objeto": "valor_vital\u00edcio_do_cliente", "coluna": "valor_vital\u00edcio"}, "fontes": [{"objeto": "pedidos", "coluna": "status", "via": "ONDE"}] } ] }<\/code><\/pre>\n\n\n\n
Observe a terceira rela\u00e7\u00e3o. pedidos.status<\/code> nunca aparece na sa\u00edda da visualiza\u00e7\u00e3o, mas filtra quais linhas s\u00e3o somadas, portanto, afeta definitivamente o resultado. valor_de_vida_total<\/code>O SQLFlow modela isso como linhagem indireta<\/strong>, distinto do fluxo de dados direto e solicit\u00e1vel separadamente. A maioria das ferramentas de linhagem n\u00e3o faz essa distin\u00e7\u00e3o, e \u00e9 exatamente disso que um consumidor de an\u00e1lise de impacto precisa: eliminar pedidos.status<\/code> corromperia essa visualiza\u00e7\u00e3o, mesmo que nenhuma coluna de sa\u00edda "venha" dela.<\/p>\n\n\n\n
\n\n
Caso de uso: verifica\u00e7\u00e3o de linhagem em CI (Integra\u00e7\u00e3o Cont\u00ednua)<\/h2>\n\n\n\n
A integra\u00e7\u00e3o de maior impacto \u00e9 aquela executada antes da publica\u00e7\u00e3o de um SQL incorreto. Em um job de CI, para cada pull request que utiliza SQL:<\/p>\n\n\n\n
  1. Envie os arquivos SQL modificados para o endpoint de linhagem e obtenha o novo gr\u00e1fico.<\/li>\n
  2. Compare com o grafo do ramo principal: quais colunas ganharam ou perderam fontes, quais objetos a jusante alteraram suas entradas.<\/li>\n
  3. A verifica\u00e7\u00e3o falha ou a diferen\u00e7a \u00e9 publicada como um coment\u00e1rio de revis\u00e3o quando uma altera\u00e7\u00e3o afeta colunas que alimentam alvos protegidos, como relat\u00f3rios regulat\u00f3rios ou pain\u00e9is executivos.<\/li><\/ol>\n\n\n\n
    Como a an\u00e1lise \u00e9 est\u00e1tica, ela funciona com c\u00f3digo que nunca foi executado. Voc\u00ea detecta a depend\u00eancia quebrada no momento da revis\u00e3o, n\u00e3o quando a execu\u00e7\u00e3o em lote das 2 da manh\u00e3 falha. O mesmo padr\u00e3o controla as migra\u00e7\u00f5es de esquema: antes de um COLUNA DE REMO\u00c7\u00c3O<\/code> Em "lands", uma \u00fanica chamada de rastreamento downstream informa todos os objetos que consomem a coluna, direta ou indiretamente, por meio de um filtro.<\/p>\n\n<\/div><\/div>\n\n\n\n
    Caso de uso: alimentar seu cat\u00e1logo de dados<\/h2>\n\n\n\n
    As plataformas de cat\u00e1logo s\u00e3o excelentes na organiza\u00e7\u00e3o de metadados, propriedade e descoberta; a linhagem SQL em n\u00edvel de coluna geralmente \u00e9 seu ponto fraco. O SQLFlow atua como o mecanismo de linhagem: analise seu ambiente SQL e, em seguida, envie os resultados para o cat\u00e1logo que voc\u00ea j\u00e1 utiliza. As implanta\u00e7\u00f5es corporativas incluem adaptadores de exporta\u00e7\u00e3o prontos para uso. DataHub, Microsoft Purview e OpenMetadata<\/strong>E as exporta\u00e7\u00f5es em JSON e CSV alimentam qualquer personaliza\u00e7\u00e3o. Em grande escala, isso \u00e9 executado como varreduras em lote e incrementais em conjuntos de mais de 100 bancos de dados e mais de um milh\u00e3o de colunas, com um reposit\u00f3rio de linhagem persistente, de modo que o cat\u00e1logo permane\u00e7a atualizado sem que ningu\u00e9m precise manter a linhagem manualmente.<\/p>\n\n\n\n
    Caso de uso: linhagem dentro de suas pr\u00f3prias ferramentas<\/h2>\n\n\n\n
    As plataformas de dados internas continuam aprimorando os mesmos recursos: um painel "de onde vem esta m\u00e9trica?", um verificador de obsolesc\u00eancia, um mapa de depend\u00eancias de migra\u00e7\u00e3o. Em vez de criar um analisador SQL, chame a API do seu servi\u00e7o e renderize o gr\u00e1fico da maneira que preferir. Se voc\u00ea quiser o pr\u00f3prio diagrama interativo em vez do JSON bruto, o SQLFlow tamb\u00e9m oferece um widget JavaScript incorpor\u00e1vel com uma API de mais de 30 m\u00e9todos que pode ser integrada a qualquer aplicativo web; para integra\u00e7\u00e3o somente com a JVM no backend, existe uma biblioteca Java que exp\u00f5e o mesmo mecanismo. API, widget e biblioteca retornam resultados consistentes porque compartilham o mesmo analisador.<\/p>\n\n\n\n
    \n\n
    Transforme seu SQL em um gr\u00e1fico de linhagem via HTTP<\/h2>\n\n\n\n
    Examine o gr\u00e1fico no visualizador gratuito e, em seguida, envie a mesma consulta SQL para a API REST a partir do seu pipeline.<\/p>\n\n\n\n
    \n
    Experimente o SQLFlow gratuitamente<\/a><\/div>\n\n\n\n
    Leia a documenta\u00e7\u00e3o da API.<\/a><\/div>\n<\/div>\n\n<\/div><\/div>\n\n\n\n
    Como isso se compara a outras op\u00e7\u00f5es de linhagem program\u00e1tica?<\/h2>\n\n\n\n
    Este \u00e9 um servi\u00e7o de an\u00e1lise SQL, n\u00e3o uma biblioteca de an\u00e1lise sint\u00e1tica ou um coletor de dados em tempo de execu\u00e7\u00e3o.<\/strong> Vale a pena conhecer tr\u00eas categorias. Bibliotecas de an\u00e1lise sint\u00e1tica de c\u00f3digo aberto<\/strong> como linhagem sql<\/code> e sqlglot<\/code> S\u00e3o realmente boas para analisar instru\u00e7\u00f5es individuais dentro de um processo Python e, para l\u00f3gica SELECT e INSERT simples, podem ser suficientes; a lacuna aparece em procedimentos armazenados, SQL din\u00e2mico, casos extremos de dialetos e resolu\u00e7\u00e3o de visualiza\u00e7\u00f5es ou expans\u00f5es em estrela que precisam de contexto de esquema. Padr\u00f5es de linhagem de tempo de execu\u00e7\u00e3o<\/strong> Assim como o OpenLineage, que captura a linhagem a partir de eventos de execu\u00e7\u00e3o de tarefas, o que \u00e9 excelente para a linhagem em n\u00edvel de orquestrador, execu\u00e7\u00e3o por execu\u00e7\u00e3o, mas s\u00f3 visualiza o c\u00f3digo que realmente foi executado, na granularidade fornecida pela integra\u00e7\u00e3o emissora. Plataformas com foco em cat\u00e1logo<\/strong> As APIs de linhagem do SQLFlow exp\u00f5em toda a linhagem que ingeriram, portanto, suas respostas s\u00e3o limitadas \u00e0 profundidade da ingest\u00e3o. A API REST do SQLFlow \u00e9 uma ferramenta diferente: um servi\u00e7o especializado em an\u00e1lise de SQL que calcula a linhagem em n\u00edvel de coluna a partir do pr\u00f3prio c\u00f3digo, incluindo o SQL que nunca foi executado e os procedimentos que outras ferramentas ignoram. As categorias se complementam bem; muitas equipes usam o SQLFlow para calcular a linhagem e um cat\u00e1logo para disponibiliz\u00e1-la aos usu\u00e1rios finais.<\/p>\n\n\n\n
    Onde a API \u00e9 executada: na nuvem ou na sua pr\u00f3pria rede.<\/h2>\n\n\n\n
    A API REST est\u00e1 dispon\u00edvel em ambas as implementa\u00e7\u00f5es do SQLFlow. Nuvem SQLFlow<\/a> \u00e9 o in\u00edcio mais r\u00e1pido: um SaaS com um n\u00edvel gratuito, premium a $49,99\/m\u00eas, sem necessidade de infraestrutura. SQLFlow no local<\/a> A implanta\u00e7\u00e3o \u00e9 feita via Docker ou Kubernetes dentro da sua rede, funciona totalmente isolada da internet (air-gapped) e tem o pre\u00e7o de \u00a31.300.500\/m\u00eas ou \u00a31.300.4800 (pagamento \u00fanico) por tipo de banco de dados selecionado, instal\u00e1vel em dois servidores. Uma pr\u00e1tica comum \u00e9 prototipar a integra\u00e7\u00e3o na nuvem e, em seguida, migrar as mesmas chamadas de API para um host local, garantindo que o c\u00f3digo SQL nunca saia da sua infraestrutura.<\/p>\n\n\n\n
    Perguntas frequentes<\/h2>\n\n\n\n
    A API retorna a linhagem em n\u00edvel de coluna ou em n\u00edvel de tabela?<\/h3>\n\n\n
    Ambas. O n\u00edvel de coluna \u00e9 a profundidade padr\u00e3o: para cada coluna de sa\u00edda, voc\u00ea obt\u00e9m as colunas de origem exatas e as fun\u00e7\u00f5es, jun\u00e7\u00f5es e opera\u00e7\u00f5es de conjunto entre elas, com distin\u00e7\u00e3o entre linhagem direta e indireta. Voc\u00ea pode solicitar granularidade em n\u00edvel de tabela quando um gr\u00e1fico de depend\u00eancia compacto for tudo o que voc\u00ea precisa.<\/p>\n\n\n\n
    Quais dialetos SQL a API de linhagem de dados suporta?<\/h3>\n\n\n
    39 dialetos, cada um com seu pr\u00f3prio analisador sint\u00e1tico: Snowflake, BigQuery, Redshift, Databricks, Oracle, SQL Server, PostgreSQL, MySQL, Teradata, Hive, Spark SQL, Trino e muitos outros. Voc\u00ea especifica o dialeto em cada requisi\u00e7\u00e3o.<\/p>\n\n\n\n
    Ele consegue analisar procedimentos armazenados e SQL din\u00e2mico?<\/h3>\n\n\n
    Sim. O Oracle PL\/SQL e o SQL Server T-SQL possuem analisadores sint\u00e1ticos procedurais dedicados. A linhagem \u00e9 rastreada por meio de par\u00e2metros de procedimento e tabelas tempor\u00e1rias, o SQL din\u00e2mico constru\u00eddo dentro dos procedimentos \u00e9 resolvido e analisado, e a API pode retornar o grafo de chamadas de procedimento para procedimento.<\/p>\n\n\n\n
    A API precisa acessar meus dados?<\/h3>\n\n\n
    N\u00e3o. Ele realiza uma an\u00e1lise est\u00e1tica do texto SQL que voc\u00ea envia e nunca l\u00ea os dados das linhas da tabela. Na vers\u00e3o local, o pr\u00f3prio texto SQL permanece dentro da sua rede.<\/p>\n\n\n\n
    Quais formatos de sa\u00edda est\u00e3o dispon\u00edveis?<\/h3>\n\n\n
    O JSON \u00e9 o formato principal para uso program\u00e1tico; a exporta\u00e7\u00e3o em CSV \u00e9 adequada para planilhas e carregamentos em massa, e a exporta\u00e7\u00e3o em PNG produz o diagrama renderizado para documenta\u00e7\u00e3o. Implanta\u00e7\u00f5es corporativas adicionam adaptadores de exporta\u00e7\u00e3o para DataHub, Microsoft Purview e OpenMetadata.<\/p>\n\n\n\n
    Onde posso encontrar a refer\u00eancia completa da API?<\/h3>\n\n\n
    No docs.gudusoft.com<\/a>, abrangendo caminhos de endpoints, autentica\u00e7\u00e3o, par\u00e2metros de solicita\u00e7\u00e3o por funcionalidade e o esquema de resposta completo. Para saber quais planos incluem acesso \u00e0 API, consulte Pre\u00e7os do SQLFlow<\/a>.<\/p>\n\n\n\n
    \n\n
    Obtenha a linhagem em formato JSON do seu SQL.<\/h2>\n\n\n
    Cole uma consulta no visualizador gratuito para inspecionar a estrutura do gr\u00e1fico e, em seguida, conecte a API REST ao seu pipeline.<\/p>\n\n\n
    \n
    Experimente o SQLFlow gratuitamente<\/a><\/div>\n\n\n\n
    Fale conosco sobre integra\u00e7\u00e3o de API.<\/a><\/div>\n<\/div>\n\n<\/div><\/div>\n\n\n\n