> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/spanish/function-blocks/blocks-reference/input-output/communication/sql-db-operations.md).

# SQL-DB Operations

Este bloque de función te permite realizar tareas comunes de SQL (INSERT, QUERY, UPDATE, DELETE, EXECUTE) contra una base de datos conectada. Ofrece una interfaz sencilla para seleccionar la operación, indicar el nombre de la tabla cuando hace falta y alimentar las entradas necesarias mediante sockets. Las operaciones se ejecutan en segundo plano para que la interfaz siga respondiendo.

## 📥 Entradas (sockets)

Según la operación SQL seleccionada, el bloque expone distintos sockets de entrada. Cada nombre listado es un socket que puedes conectar a otros bloques.

Sockets comunes a todos los métodos

* `Enable`\
  Debe recibir `true` para ejecutar la operación seleccionada.
* `DB Client`\
  Referencia al cliente de la base de datos, proporcionada por un bloque de conexión separado (ver Consejos y Trucos).

Sockets por método

* INSERT
  * `JSON Data`\
    Datos a insertar en la tabla seleccionada (JSON/diccionario).
* QUERY
  * `Query String`\
    Cadena SQL SELECT u otra consulta a ejecutar.
* UPDATE
  * `JSON Data`\
    Valores a actualizar (JSON/diccionario).
  * `JSON Data(Where Conditions)`\
    Condiciones WHERE para seleccionar las filas a actualizar.
* DELETE
  * `JSON Data(Where Conditions)`\
    Condiciones WHERE para seleccionar las filas a eliminar.
* EXECUTE
  * `Statement String`\
    Sentencia SQL cruda para ejecutar (usar con precaución).

Nota: El bloque mostrará u ocultará el control `Table Name` según la operación elegida.

## 📤 Salidas (sockets)

* `Output Data`\
  Devuelve el resultado de la operación (por ejemplo filas de una consulta, información de filas afectadas, u otros datos específicos).
* `Success?`\
  Booleano que indica si la operación se completó con éxito.

## 🕹️ Controles (widgets)

* `Select SQL Operation`\
  Menú desplegable para elegir una de: INSERT / QUERY / UPDATE / DELETE / EXECUTE. Al cambiar la operación, los sockets de entrada disponibles se ajustan automáticamente.
* `Table Name`\
  Campo de texto para el nombre de la tabla objetivo. Se oculta automáticamente cuando no es necesario (por ejemplo con `EXECUTE`).

## ⚙️ Mecanismo de ejecución

* El bloque sólo se ejecuta cuando el socket `Enable` recibe `true`.
* Requiere un `DB Client` válido conectado (normalmente suministrado por un bloque de conexión).
* Al activarse, el bloque ejecuta la operación seleccionada en segundo plano y devuelve `Output Data` y `Success?` cuando termina.
* Cualquier problema (entradas inválidas, cliente faltante, JSON mal formado o errores SQL) se mostrará en el área de mensajes/log del bloque.

## ✨ Características clave

* Sockets dinámicos que se adaptan a la operación SQL elegida para mantener la UI limpia.
* Ejecución en segundo plano para que la interfaz siga respondiendo mientras se realizan llamadas largas a la base de datos.
* Entradas sencillas basadas en JSON para INSERT y UPDATE, facilitando el envío de datos tabulares.
* Indicador claro de éxito y datos devueltos para continuar el procesamiento en el escenario.

## 📝 Instrucciones de uso

1. Proporciona un cliente de base de datos al socket `DB Client` (ver Consejos y Trucos).
2. Elige la operación deseada con `Select SQL Operation`.
3. Si corresponde, escribe la tabla objetivo en `Table Name`.
4. Conecta los sockets de datos necesarios para la operación elegida (por ejemplo `JSON Data` para INSERT).
5. Envía una señal `true` al socket `Enable` para ejecutar la operación.
6. Revisa `Output Data` y `Success?` para continuar con el flujo de tu escenario.

## 💡 Consejos y Trucos

* Para establecer conexiones, usa `SQL-DB Client Connect` para crear y suministrar el socket `DB Client`.
* Prepara payloads para INSERT/UPDATE usando `Data to JSON` para que el formato coincida con JSON/diccionario esperado.
* Si construyes cadenas SQL dinámicamente, usa `String Input` o `String Merge` para componer la `Query String` o `Statement String` antes de conectarlas.
* Guarda o comparte clientes/resultado frecuentes usando `Data Write Local` / `Data Read Local` o sus variantes globales para acceso entre escenarios.
* Usa `Parse Data Dictionary` para extraer campos de las filas devueltas y alimentarlos a otros bloques.
* Emplea `Debug Input` para registrar e inspeccionar datos intermedios al depurar.
* Si necesitas guardar resultados para más tarde, combínalo con `CSV Export` para escribir `Output Data` en un archivo.

## 🛠️ Solución de problemas

* `DB Client` no es válido\
  Asegúrate de conectar un cliente de base de datos correcto (usa `SQL-DB Client Connect`). El bloque mostrará un error si el cliente falta o es inválido.
* La operación devuelve error\
  Revisa el JSON o la cadena SQL proporcionada. Usa `Debug Input` o `Parse Data Dictionary` para inspeccionar entradas y salidas.
* Sin respuesta o espera larga\
  Aunque el bloque corre en segundo plano, las consultas largas pueden tardar. Mantén las consultas pequeñas o verifica que la base de datos esté accesible y respondiendo.
* JSON mal formado\
  Cuando uses entradas JSON, valida el JSON con `Data to JSON` o comprueba el contenido con bloques de logging antes de conectar.

Si los problemas continúan, revisa los mensajes/log del bloque para pistas y ajusta las entradas o la configuración de la base de datos según sea necesario.