---
name: query_osint_db
kind: function
lang: py
domain: datascience
version: "1.0.0"
purity: impure
signature: "def query_osint_db(sql: str, base_url: str = 'http://127.0.0.1:8771', timeout: int = 30) -> dict"
description: "Ejecuta un SELECT contra el service osint_db (DuckDB, FastAPI single-writer en 127.0.0.1:8771) por HTTP POST a /api/query y devuelve {status, columns, rows, row_count} sin lanzar. Normaliza service caido a un error claro."
tags: [duckdb, osint, http, query, readonly]
params:
  - name: sql
    desc: "Sentencia SQL a ejecutar. Pensada para SELECT read-only; el osint_db la corre con una conexion DuckDB en modo solo lectura, asi que una escritura falla a nivel de service."
  - name: base_url
    desc: "URL base del service osint_db. Default 'http://127.0.0.1:8771'. Se le anade '/api/query' al hacer el POST."
  - name: timeout
    desc: "Timeout por peticion en segundos (default 30). El osint_db es local (loopback): si tarda mas, mejor degradar que colgar al llamante."
output: "dict. En exito reenvia el cuerpo del service: {status:'ok', columns:[str,...], rows:[{col:val,...},...], row_count:int, truncated:bool}. En error (sin lanzar): {status:'error', error:str}. Service inalcanzable -> error 'osint_db service not reachable on <url>: <detalle>'."
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
tested: true
tests: ["test_query_ok_devuelve_cuerpo_del_service", "test_query_error_de_dominio_se_reenvia", "test_service_caido_devuelve_error_claro", "test_base_url_custom_se_respeta", "test_http_error_con_cuerpo_json_se_reenvia"]
test_file_path: "python/functions/datascience/query_osint_db_test.py"
file_path: "python/functions/datascience/query_osint_db.py"
---

## Ejemplo

```python
import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from datascience.query_osint_db import query_osint_db

res = query_osint_db("SELECT COUNT(*) FROM personas")
# {'status': 'ok', 'columns': ['count_star()'], 'rows': [{'count_star()': 545}],
#  'row_count': 1, 'truncated': False}
print(res["rows"])
```

Lanzable directo:

```bash
./fn run query_osint_db_py_datascience
# o pasandole el SQL como arg:
python/.venv/bin/python3 python/functions/datascience/query_osint_db.py "SELECT COUNT(*) FROM personas"
```

## Cuando usarla

Cuando necesites leer la verdad OSINT que vive en el service osint_db (DuckDB, fuente
de verdad del proyecto osint: personas, dominios, network_scans, etc.). Sustituye el
patron inline repetido `curl -s -X POST 127.0.0.1:8771/api/query ...` por una sola
llamada con retorno estructurado. Usala antes de escribir un heredoc/curl a mano
contra ese endpoint.

## Gotchas

- El service `osint_db` debe estar arriba (escucha en `127.0.0.1:8771`). Si esta
  caido, la funcion NO lanza: devuelve `{status:'error', error:'osint_db service not
  reachable on <url>: ...'}`. Comprueba el status antes de leer `rows`.
- `osint_db` es **single-writer**: el endpoint `/api/query` es estrictamente
  read-only (abre una conexion DuckDB read_only separada). Desde aqui usa **solo
  SELECT** — una escritura fallara a nivel de service.
- El service responde **siempre HTTP 200**; el status real del dominio viaja en el
  cuerpo (`status: 'ok'|'error'`). La funcion reenvia ese cuerpo tal cual en exito.
- El `max_rows` del service tiene tope (default 500, max 10000); para volcados
  grandes pagina o usa la maestra directamente.

## Notas

Solo stdlib (urllib, json): wrapper de transporte puro, sin dependencias de runtime.
Sigue la convencion de retorno de `pg_query_py_infra` y `duckdb_query_readonly`
(`{status:'ok'|'error', ...}`). El service osint_db vive en
`projects/osint/apps/osint_db/` y su `/api/query` delega en `duckdb_query_readonly`.