Datasources

O servidor expõe endpoints para resolver e introspectar datasources remotos, permitindo executar queries e descobrir schemas sem precisar gerar um relatório completo.

Resolver — POST /api/v1/datasources/resolve

Permissão: canGenerate

Executa a query do datasource e retorna os dados resultantes.

Body:

{
  "dataSource": {
    "id": "ds1",
    "type": "list",
    "source": "external",
    "driver": "postgres",
    "connectionRef": "my-postgres",
    "query": "SELECT * FROM sales WHERE region = {{region}}"
  },
  "params": { "region": "Sul" }
}

Campo	Obrigatório	Descrição
dataSource	Sim	Definição do datasource
params	Não	Parâmetros para substituição na query

Resposta 200:

{
  "data": [
    { "id": 1, "product": "Widget A", "amount": 150 },
    { "id": 2, "product": "Widget B", "amount": 230 }
  ],
  "rowCount": 2
}

Timeout: 30 segundos.

Status	Erro	Quando
400	missing_datasource	dataSource ausente no body
400	dangerous_query	Query contém SQL perigoso (DDL/DML)
403	forbidden_host	SSRF guard bloqueou o destino
422	no_resolver	Nenhum resolver para o driver informado
422	unresolved_connection	connectionRef não encontrada
422	resolve_failed	Erro genérico de resolução
504	resolve_timeout	Timeout (30s)

Introspectar — POST /api/v1/datasources/introspect

Permissão: canSettings

Retorna o schema dos campos e uma amostra de dados. Útil para o designer de relatórios.

Body: Mesmo formato do resolve.

Resposta 200:

{
  "fields": [
    { "name": "id", "type": "int" },
    { "name": "product", "type": "String" },
    { "name": "amount", "type": "int" }
  ],
  "sample": [
    { "id": 1, "product": "Widget A", "amount": 150 }
  ]
}

Status	Erro	Quando
400	missing_datasource	dataSource ausente
400	dangerous_query	Query contém SQL perigoso
403	forbidden_host	SSRF guard bloqueou
422	no_resolver	Driver não suportado
422	unresolved_connection	Conexão não encontrada
422	introspect_failed	Erro de introspecção
504	introspect_timeout	Timeout

Drivers suportados

Driver	Tipo de conexão	Resolver
postgres	database	PostgresDataSourceResolver
postgrest	http	PostgRestDataSourceResolver
rest	http	RestDataSourceResolver

Sanitização de queries

Para drivers SQL (postgres, postgrest), as queries passam por um sanitizador que bloqueia:

• DDL: DROP, ALTER, TRUNCATE, CREATE
• DML de escrita: INSERT INTO, UPDATE ... SET, DELETE FROM
• Privilégios: GRANT, REVOKE
• Execução de código: COPY ... TO/FROM
• Multi-statement: ;
• Tamanho máximo: 10 KB

Apenas queries de leitura (SELECT, WITH) são permitidas.