Python SDK

La clase LensClient proporciona acceso programatico a todas las capacidades de Lens desde codigo Python. Se conecta a tus buckets registrados, monta vistas DuckDB y expone operaciones de consulta, IA y cache como llamadas a metodos.

Importar

from dataspoc_lens import LensClient

Uso basico

from dataspoc_lens import LensClient

client = LensClient()

# List tables
tables = client.tables()
print(tables)  # ['customers', 'orders', 'products']

# Run a query
result = client.query("SELECT COUNT(*) as total FROM orders")
print(result["rows"])  # [[48680]]

# Clean up
client.close()

Context manager

Usa LensClient como context manager para asegurar que la conexion se cierre automaticamente:

from dataspoc_lens import LensClient

with LensClient() as client:
    tables = client.tables()
    result = client.query("SELECT * FROM orders LIMIT 5")
    print(result["columns"])
    print(result["rows"])

Metodos

tables()

Retorna la lista de nombres de tablas montadas.

tables = client.tables()
# ['customers', 'orders', 'products']

Retorna: list[str]

schema(table)

Retorna metadatos de columnas para una tabla.

columns = client.schema("orders")
# [
#     {"column_name": "order_id", "data_type": "INTEGER"},
#     {"column_name": "customer_id", "data_type": "INTEGER"},
#     {"column_name": "order_date", "data_type": "DATE"},
#     {"column_name": "total", "data_type": "DOUBLE"},
#     {"column_name": "status", "data_type": "VARCHAR"},
# ]

Parametros: table (str) — nombre de la tabla

Retorna: list[dict] — cada dict tiene column_name y data_type

query(sql)

Ejecuta una consulta SQL y retorna los resultados.

result = client.query("SELECT status, COUNT(*) as cnt FROM orders GROUP BY status")
print(result["columns"])   # ['status', 'cnt']
print(result["rows"])      # [['completed', 32100], ['pending', 8450], ...]
print(result["row_count"]) # 3
print(result["duration"])  # 0.089

Parametros: sql (str) — consulta SQL a ejecutar

Retorna: dict con claves:

• columns — lista de nombres de columnas
• rows — lista de listas de filas
• row_count — numero de filas retornadas
• duration — tiempo de consulta en segundos

ask(question, **kwargs)

Traduce una pregunta en lenguaje natural a SQL, la ejecuta y retorna el resultado.

result = client.ask("What are the top 5 customers by spending?")
print(result["sql"])       # 'SELECT c.name, SUM(o.total) ...'
print(result["columns"])   # ['name', 'total_spent']
print(result["rows"])      # [['Alice Smith', 15420.5], ...]
print(result["error"])     # None

Parametros:

• question (str) — pregunta en lenguaje natural
• **kwargs — reenviados al modulo de IA (ej., provider, api_key, model, debug)

Retorna: dict con claves:

• sql — consulta SQL generada
• columns — lista de nombres de columnas
• rows — lista de listas de filas
• duration — tiempo total en segundos
• error — mensaje de error o None

cache_status()

Retorna metadatos de todas las tablas cacheadas.

cached = client.cache_status()
# [
#     {
#         "table": "orders",
#         "status": "fresh",
#         "cached_at": "2026-04-15T10:30:00",
#         "size_bytes": 12902400,
#     }
# ]

Retorna: list[dict] — cada dict tiene table, status, cached_at, size_bytes

cache_refresh(table)

Fuerza la actualizacion del cache local para una tabla.

info = client.cache_refresh("orders")
print(info)
# {"cached_at": "2026-04-15T14:00:00", "size_bytes": 12902400, "file_count": 4}

Parametros: table (str) — nombre de la tabla

Retorna: dict con cached_at, size_bytes, file_count

Lanza: ValueError si la tabla no se encuentra en ningun bucket registrado.

cache_refresh_stale()

Actualiza todas las tablas con cache desactualizado.

refreshed = client.cache_refresh_stale()
# [{"table": "customers", "cached_at": "...", "size_bytes": 2200000, "file_count": 1}]

Retorna: list[dict] — una entrada por tabla actualizada

cache_clear(table=None)

Limpia los datos cacheados. Si se proporciona table, solo esa tabla se limpia. De lo contrario se eliminan todos los caches.

# Clear specific table
cleared = client.cache_clear("orders")
# ['orders']

# Clear all
cleared = client.cache_clear()
# ['orders', 'customers', 'products']

Parametros: table (str | None) — nombre opcional de la tabla

Retorna: list[str] — nombres de las tablas limpiadas

close()

Cierra la conexion DuckDB subyacente.

client.close()

Se llama automaticamente al usar el context manager.

Ejemplo completo

from dataspoc_lens import LensClient

with LensClient() as client:
    # Explore
    for table in client.tables():
        cols = client.schema(table)
        print(f"{table}: {len(cols)} columns")

    # Query
    result = client.query("""
        SELECT
            c.name,
            COUNT(o.order_id) as orders,
            SUM(o.total) as revenue
        FROM customers c
        JOIN orders o ON c.id = o.customer_id
        GROUP BY c.name
        ORDER BY revenue DESC
        LIMIT 10
    """)

    for row in result["rows"]:
        print(f"{row[0]}: {row[2]:,.2f}")

    # AI
    answer = client.ask("Which product category has the highest return rate?")
    if answer["error"] is None:
        print(f"SQL: {answer['sql']}")
        for row in answer["rows"]:
            print(row)

    # Cache management
    client.cache_refresh("orders")
    status = client.cache_status()
    for entry in status:
        print(f"{entry['table']}: {entry['status']}")