libSQL

libSQL es un componente que te permite trabajar con bases de datos Turso (libSQL) directamente desde tu dashboard de Nappai. Con él puedes insertar datos, ejecutar consultas SQL, crear buscadores de similitud y obtener información sobre la base de datos sin salir de la plataforma.

¿Cómo funciona?

El componente se conecta a tu base de datos Turso mediante una credencial que has configurado previamente en Nappai. Cuando seleccionas una operación, el componente envía la petición correspondiente a la API de Turso y devuelve los resultados en el formato que necesitas (datos, buscador, información de la base o esquema). Todo el proceso se gestiona automáticamente, por lo que no necesitas escribir código.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

• Add: Inserta datos en una tabla de la base de datos. Puedes elegir si quieres borrar la tabla antes de insertar.
• SQL: Ejecuta una consulta SQL personalizada y devuelve los resultados.
• Retriever: Crea un buscador de similitud que permite encontrar registros similares a un texto dado.
• DatabaseInfo: Obtiene información básica sobre la base de datos, como el número de tablas y el tamaño.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

• Embedding: Embedding to generate vector from text or to use similarity search.
  • Visible en: Add, SQL, Retriever
• Ingest Data: Insert data into the database table.
  • Visible en: Add
• Operation: Tipo de operación que quieres ejecutar.
  • Visible en: Add, SQL, Retriever, DatabaseInfo
• Number of Results: Número de resultados a devolver.
  • Visible en: Add, SQL, Retriever, DatabaseInfo
• Search Query: SQL query to execute.
  • Visible en: SQL
• Search Score Threshold: If value is distinct to 0.0, it will filter the results with distance score lower than the threshold.
  • Visible en: Add, SQL, Retriever, DatabaseInfo
• Table Name: Name of the table in the database.
  • Visible en: Add
• Drop Table: Drop the table if it exists before inserting data.
  • Visible en: Add, DatabaseInfo

Credencial
Este componente necesita una credencial de tipo libSQL / Turso.

1. Ve a la sección de credenciales de Nappai y crea una nueva credencial de tipo libSQL / Turso, proporcionando la URL y el Token.
2. En el campo “Credential” del componente, selecciona la credencial que acabas de crear.
   Los datos de la credencial (URL, Token) no aparecen en la lista de entradas porque ya están gestionados por Nappai.

Salidas

• Data: Resultado de una consulta SQL o de la inserción de datos.
• Retriever: Objeto que permite buscar registros similares a un texto.
• Database Info: Información sobre la base de datos (tablas, tamaño, etc.).
• Database Schema: Esquema de la base de datos (estructura de las tablas).

Ejemplo de Uso

Operación Add

1. Selecciona Add en el campo “Operation”.
2. En Table Name escribe customers.
3. Marca Drop Table si quieres borrar la tabla antes de insertar.
4. En Ingest Data pega un JSON con los registros que quieres insertar.
5. Ajusta Number of Results si quieres limitar la respuesta.
6. Haz clic en “Run”.
   El componente devolverá los datos insertados en la salida Data.

Operación SQL

1. Selecciona SQL en el campo “Operation”.
2. En Search Query escribe:

   SELECT * FROM customers WHERE country = 'Spain';

3. Ajusta Number of Results para limitar la cantidad de filas devueltas.
4. Haz clic en “Run”.
   El resultado aparecerá en la salida Data.

Componentes Relacionados

• Data Ingest – Inserta datos en bases de datos externas.
• SQL Query – Ejecuta consultas SQL en bases de datos SQL tradicionales.
• Retriever Builder – Crea buscadores de similitud a partir de embeddings.

Consejos y Mejores Prácticas

• Usa “Drop Table” con precaución: Si la tabla contiene datos importantes, desactiva esta opción.
• Limita “Number of Results”: Evita devolver demasiados registros a la vez para mantener el rendimiento.
• Revisa el “Search Score Threshold”: Si lo estableces a un valor distinto de 0.0, solo obtendrás resultados con mayor similitud.

Consideraciones de Seguridad

• Asegúrate de que la credencial de libSQL / Turso esté protegida y solo sea accesible para usuarios autorizados.
• Evita exponer datos sensibles en la salida Data; si es necesario, filtra la información antes de usarla en otros componentes.