Warp SQL: execute SQL de qualquer coisa que fale HTTP e receba Arrow de volta
Um protocolo aberto para SQL sobre HTTP simples. Resultados, parâmetros e uploads viajam como streams Apache Arrow IPC; todo o resto é JSON pequeno. Sem gRPC, sem protobuf, sem código gerado. É o protocolo que o Hardcharger fala.
Uma olhada rápida
Três requisições com o curl, e o pyarrow lê a resposta. Esse é o cliente inteiro.
# Get a token, open a session, run a query, read the result with pyarrow.
TOKEN=$(curl -s localhost:31337/warp/v1/auth/token -H 'Content-Type: application/json' \
-d '{"grant_type": "password", "username": "hardcharger", "password": "change-me"}' | jq -r .access_token)
SESSION=$(curl -s localhost:31337/warp/v1/sessions -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{}' | jq -r .session_id)
curl -s localhost:31337/warp/v1/sessions/$SESSION/statements -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -H 'Accept: application/vnd.apache.arrow.stream' \
-d '{"sql": "SELECT 42 AS answer"}' > result.arrows
python -c "import pyarrow.ipc as ipc; print(ipc.open_stream(source='result.arrows').read_all())"Todo servidor se descreve
GET /warp lista as versões do protocolo, as capacidades e os métodos de login que um servidor suporta, para que o cliente saiba o que pode usar. Aqui, o Hardcharger:
{
"protocol": "warp-sql",
"protocol_versions": ["1"],
"server": {"name": "Hardcharger", "version": "2.0.0 (DuckDB v2.0.0)"},
"capabilities": ["prepared_statements", "transactions", "ingest", "partitioned_ingest",
"long_poll", "ipc_compression_zstd", "ipc_compression_lz4_frame",
"result_partitions", "openapi"],
"auth": {"grant_types": ["password"]},
"links": {"openapi": "/warp/v1/openapi.json"}
}- 01Entrar
POST /warp/v1/auth/token retorna um token bearer.
- 02Abra uma sessão
POST /warp/v1/sessions, com opções e transações próprias.
- 03Consulta curta
POST …/statements com Accept: Arrow transmite o resultado na mesma resposta.
- 04Consulta longa
Prefer: respond-async retorna um handle; acompanhe-o por long-poll e depois GET …/result?from_batch=N, retomável.
Qualquer coisa que fale HTTP
Um fetch do navegador, o curl ou a biblioteca HTTP padrão de qualquer linguagem. Sem gRPC, sem protobuf, sem código gerado, e nada que um proxy ou firewall precise aprender.
Arrow na comunicação
Resultados, parâmetros de consulta e uploads em massa são streams Arrow IPC (application/vnd.apache.arrow.stream), então toda biblioteca Arrow os lê diretamente. As mensagens de controle são pequenos documentos JSON.
Consultas curtas continuam em uma única ida e volta
Um POST executa uma consulta e transmite o resultado de volta na mesma resposta.
Resultados grandes vão em paralelo
Um cliente pode pedir um resultado grande como várias partições e lê-las por conexões separadas ao mesmo tempo, além do que um único stream TCP transporta, mantendo a ordem quando a consulta tem uma.
Uploads grandes também vão em paralelo
Ingestão em massa em streaming, enviada em várias partes por conexões separadas e confirmada como uma única transação: tudo ou nada. Os buffers Arrow podem viajar comprimidos com lz4_frame ou zstd, negociados por preferência.
Consultas longas sobrevivem a redes reais
Envie uma consulta, receba um handle, acompanhe-o por long-poll e busque o resultado depois. Um download interrompido retoma do lote em que parou, e nenhuma requisição precisa durar mais que o tempo limite de um proxy.
Segurança no núcleo
As credenciais são tokens bearer, nunca cookies, então não há CSRF contra o que se defender. Cada handle de sessão, instrução e resultado fica vinculado à identidade que o criou e é verificado a cada uso; resultados e metadados seguem a autorização de quem chama. Login por token, troca de tokens, login pelo navegador e certificados de cliente estão na especificação.
Parâmetros de bind
Parâmetros posicionais e nomeados nas instruções, e instruções preparadas que recebem lotes de parâmetros em JSON ou Arrow: os valores viajam como valores, nunca emendados no texto SQL.
OpenAPI 3.1, servida por todo servidor
GET /warp/v1/openapi.json descreve a API para navegadores de API e geradores de clientes, e GET /warp lista o que o servidor suporta.
Uma suíte de conformidade
Uma suíte caixa-preta de 282 testes conversa com um servidor apenas pelo protocolo, então qualquer implementação pode comprovar que está em conformidade.
O código de driver é reaproveitado
As respostas de metadados usam os esquemas de resultado do Arrow Flight SQL, então listagens de catálogos, esquemas e tabelas têm a mesma forma para o código de driver.
Pronto para escalar horizontalmente
Os resultados são descritos como partições, cada uma com uma localização. Hoje, um servidor divide um resultado em si mesmo; um mecanismo distribuído pode apontar partições para outras máquinas sem mudar o protocolo.
Warp SQL vs. Arrow Flight SQL vs. Quack
O Arrow Flight SQL é o protocolo SQL do projeto Apache Arrow, sobre gRPC. O Quack é o protocolo da DuckDB Labs para um DuckDB anexar outro. O Warp SQL mantém o Arrow na comunicação e passa todo o resto para HTTP simples.
| Warp SQL 1.0 | Arrow Flight SQL | DuckDB Quack | |
|---|---|---|---|
| Transporte | HTTP/1.1 simples, com TLS | Arrow Flight RPC, construído sobre gRPC; os comandos são mensagens Protobuf | O protocolo próprio do DuckDB sobre HTTP/1.1 |
| Formato dos resultados | Streams Arrow IPC | Arrow IPC | O formato próprio do DuckDB |
| Do que um cliente precisa | Qualquer cliente HTTP: fetch, curl, uma biblioteca padrão | Uma biblioteca cliente ou driver Flight (gRPC) | DuckDB com a extensão quack (CLI, uma biblioteca DuckDB ou DuckDB-Wasm) |
| Navegadores | fetch simples, CORS para origens permitidas | Por meio do DuckDB-Wasm | |
| Descrição da API | Especificação escrita, mais OpenAPI 3.1 servida por todo servidor | Definições Protobuf na documentação de formatos do Apache Arrow | ParcialMensagens definidas no código-fonte da extensão; nenhuma especificação separada encontrada |
| Suíte de conformidade | 282 testes caixa-preta | Nenhuma encontrada | |
| Estabilidade | 1.0: só muda por adição, então um cliente 1.0 continua funcionando | Parte do Apache Arrow; o conjunto de metadados pode crescer | Versão 3 no DuckDB 2.0; a documentação do DuckDB diz que ainda pode mudar |
| Modelo de segurança no protocolo | Tokens bearer (sem cookies), handles vinculados ao seu principal, resultados controlados; senha, troca de tokens, login pelo navegador, mTLS | ParcialUm token compartilhado por padrão, ou a sua própria função SQL; sem certificados de cliente | |
| Parâmetros de bind | Posicionais e nomeados; lotes de parâmetros em JSON ou Arrow | Instruções preparadas, parâmetros vinculados com DoPut | Somente texto SQL |
| Consultas demoradas | Enviar, long-poll, buscar depois | PollFlightInfo | |
| Retomar um download interrompido | A partir do lote em que parou | ||
| Resultados paralelos (particionados) | Partições lidas por várias conexões, em ordem quando pedido | Endpoints, cada um com localizações, consumíveis em paralelo | |
| Ingestão em massa | Em streaming, em partes paralelas, confirmada de forma atômica | CommandStatementIngest | Para um banco de dados anexado |
| Compressão | lz4_frame ou zstd, negociados por preferência | ||
| Cancelamento | Instrução e sessão | CancelFlightInfo | quack_cancel() |
| Licença | Apache-2.0 | Apache-2.0 (Apache Arrow) | MIT |
Fontes: a especificação do Warp SQL; a documentação do Apache Arrow sobre Flight SQL e Flight; a documentação do Quack do DuckDB e as nossas verificações em servidores em execução (Quack e7a9be3f8c, o commit que o DuckDB 2.0 fixa). Um traço significa que não temos fonte verificada para aquela célula, não que o recurso falte; servidores Flight SQL específicos podem oferecer mais.
Medido em uma rede real
Três servidores DuckDB, cada um com o seu cliente padrão, transferindo tabelas lineitem (dados derivados do TPC-H, gerados com dbgen) e uma tabela de 100 milhões de linhas entre máquinas da AWS. O Hardcharger via Warp SQL foi de 3 a 34 vezes mais rápido que o GizmoSQL via Arrow Flight SQL em todos os testes, e mais rápido que o Quack em cinco de nove.
| Teste (mediana em segundos, quanto menor, melhor) | Warp SQL Hardcharger | Quack ATTACH no DuckDB 2.0 | Arrow Flight SQL GizmoSQL 1.42.0 |
|---|---|---|---|
| Busca do lineitem SF1 (6 milhões de linhas), LAN | 0,126 | 0,164 | 1,48 |
| Busca do lineitem SF10 (60 milhões de linhas), LAN | 0,843 | 0,815 | 16,11 |
| Busca de 100 milhões de linhas estreitas, LAN | 0,453 | 0,390 | 5,33 |
| Carga do lineitem SF1, LAN | 0,538 | 0,600† | 1,61 |
| Carga do lineitem SF10, LAN | 2,84 | 2,67† | 9,42 |
| Busca do lineitem SF1, WAN (46 ms) | 0,383 | 1,51 | 12,97 |
| Carga do lineitem SF1, WAN (46 ms) | 1,11 | 1,80† | 13,80 |
| Busca do lineitem SF10, LAN, plaintext | 0,746 | 0,962 | 13,22 |
| Carga do lineitem SF10, LAN, plaintext | 2,62 | 2,60† | 9,46 |
Como medimos (2026-10-19): máquinas AWS c8gn.8xlarge (Graviton4, 32 vCPUs, 100 Gbit/s), servidor e cliente no mesmo placement group (LAN) ou o cliente em outra região, a cerca de 46 ms (WAN); TLS em todos os servidores, a menos que a linha diga plaintext; threads=32 e memory_limit=40GB em todos os servidores; mediana de cinco execuções depois de um aquecimento, cada carga conferida com a origem. Clientes: o driver ADBC do Warp SQL com as configurações padrão, adbc-driver-gizmosql para o GizmoSQL e o próprio cliente do DuckDB anexando o Quack.
Estas medições comparam servidores inteiros, não apenas protocolos: o Hardcharger e o Quack rodaram a mesma versão de pré-lançamento do DuckDB 2.0, e o GizmoSQL rodou o DuckDB 1.5.6. † Quack sem ordem de inserção (o padrão dele a mantém, e foi mais lento: 1,016 s na carga SF1 em LAN, 2,684 s pela WAN); as partes paralelas de upload do Hardcharger também não mantêm a ordem das linhas. O Quack foi mais rápido nas buscas grandes em LAN (em 3% e 16%) e nas cargas grandes em LAN (em 6%, e em 1% sem TLS).
Os fatores de escala SF1 e SF10 se referem a esses dados gerados. Esta carga de trabalho é derivada do TPC-H Benchmark e não é comparável aos resultados publicados do TPC-H Benchmark, pois esta implementação não atende a todos os requisitos do TPC-H Benchmark. TPC, TPC Benchmark e TPC-H são marcas comerciais do Transaction Processing Performance Council (TPC).
Resultados completos, inclusive uso de CPU e bytes na rede: notas dos benchmarks.
Implementações
Hardcharger™
O servidor DuckDB 2.0 da GizmoData. Ele passa na bateria de testes do GizmoSQL usando apenas o Warp SQL.
Saiba maislibwarpsql e warp-duckdb
Um SDK de servidor em C++20 (os mecanismos implementam um backend; o SDK cuida de login, vinculação de handles, retenção, cancelamento e streaming) e um servidor de referência para testes.
GitHubDriver ADBC
warp-sql-adbc: Go, com bindings para Python, carregável por qualquer gerenciador de drivers ADBC.
GitHubCliente JavaScript
@gizmodata/warp-sql: TypeScript sobre fetch simples e Arrow JS, para Node, navegadores, Deno, Bun e Cloudflare Workers.
GitHubSuíte de conformidade
Testes caixa-preta que iniciam o seu servidor e conversam com ele apenas pelo protocolo; sem um servidor, eles falham, nunca são pulados.
GitHubPerguntas frequentes sobre o Warp SQL
O que é o Warp SQL?
O Warp SQL é um protocolo aberto (Apache-2.0) que permite que qualquer cliente HTTP execute SQL em um servidor de banco de dados e receba dados em Apache Arrow de volta: um fetch do navegador, o curl ou a biblioteca HTTP de qualquer linguagem. Resultados, parâmetros e uploads são streams Arrow IPC; as mensagens de controle são pequenos documentos JSON. O Hardcharger, o servidor DuckDB 2.0 da GizmoData, fala esse protocolo.
Qual é a diferença entre o Warp SQL e o Arrow Flight SQL?
Os dois transportam record batches do Arrow. O Arrow Flight SQL roda sobre gRPC com mensagens Protobuf e precisa de uma biblioteca cliente Flight; o Warp SQL é HTTP simples e JSON, então qualquer coisa que faça uma requisição HTTP é um cliente, inclusive um navegador. O Warp SQL também coloca no protocolo downloads retomáveis, um modelo de segurança com handles vinculados ao seu dono e uma descrição OpenAPI servida por todo servidor, e usa os esquemas de metadados do Flight SQL para que o código de driver seja reaproveitado.
O Warp SQL é mais rápido que o Arrow Flight SQL?
Nas nossas medições na AWS (19/10/2026), o Hardcharger via Warp SQL com o seu driver ADBC transferiu resultados e cargas de 3 a 34 vezes mais rápido que o GizmoSQL 1.42.0 via Arrow Flight SQL, em nove testes de busca e carga. Elas comparam servidores inteiros, inclusive versões diferentes do DuckDB, e não apenas os dois protocolos. Contra o Quack do DuckDB, o Hardcharger foi mais rápido em cinco dos nove testes e mais lento em quatro.
Quais servidores e clientes falam Warp SQL?
Servidor: o Hardcharger, além do warp-duckdb, o servidor de referência para testes. Clientes: o driver ADBC do Warp SQL (Go, com bindings para Python, carregável por qualquer gerenciador de drivers ADBC), um driver JDBC para Java 17 e posterior, um cliente JavaScript para Node, navegadores, Deno, Bun e Cloudflare Workers, e qualquer cliente HTTP.
Posso implementar o Warp SQL no meu próprio mecanismo?
Sim. A especificação, a sua descrição OpenAPI e a suíte de conformidade são Apache-2.0, e o libwarpsql, um SDK de servidor em C++20, cuida da autenticação, da vinculação de handles, da retenção, do cancelamento e do pipeline de streaming enquanto o seu mecanismo implementa um backend. Execute a suíte de conformidade contra o seu servidor para verificá-lo.
O Warp SQL 1.0 vai mudar sem eu esperar?
A versão 1 é estável: só muda por adição (novos endpoints, campos, capacidades e códigos de erro), então um cliente escrito para a 1.0.0 continua funcionando. Novos recursos chegam por trás de capacidades que um servidor lista em GET /warp.
Experimente o Warp SQL em um minuto
Instale o Hardcharger, inicie-o e aponte o curl para a porta 31337. Ou leia a especificação e construa o seu próprio servidor.
O Warp SQL é um projeto independente; não faz parte da Apache Software Foundation nem é endossado por ela. Apache Arrow, Arrow e Apache são marcas comerciais da The Apache Software Foundation. Hardcharger™ e GizmoData™ são marcas comerciais da GizmoData LLC.