Saltearse al contenido
Nappai Documentation

Astra DB

Astra DB es un componente de Nappai que permite almacenar, buscar y recuperar datos en forma de vectores dentro de una base de datos Astra. Con él puedes añadir documentos, hacer búsquedas por similitud y obtener un objeto “retriever” que se puede usar en otras partes de tu flujo de trabajo.

¿Cómo funciona?

El componente se conecta a tu cuenta de Astra DB a través de una credencial que ya has configurado en Nappai. Cuando seleccionas la operación Add, el componente convierte cada entrada de datos en un documento vectorizado y los guarda en la colección que indiques.
Con la operación Search envía tu consulta de texto a Astra DB y devuelve los documentos más similares, según el tipo de búsqueda y los filtros que hayas configurado.
La operación Retriever crea un objeto que puede ser usado por otros componentes de Nappai para recuperar datos de forma automática, sin necesidad de escribir código adicional.

Internamente el componente usa la librería langchain-astradb para comunicarse con la API de Astra DB. Los vectores se generan con el modelo de embeddings que le pases (puede ser un modelo de LangChain o la función de vectorización de Astra). Los parámetros de concurrencia y tamaño de lote permiten optimizar la carga de datos cuando trabajas con grandes volúmenes.

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: Añade documentos a la colección de Astra DB.
  • Search: Busca documentos similares a una consulta de texto.
  • Retriever: Crea un objeto “retriever” que puede ser usado por otros componentes para obtener datos automáticamente.

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

Entradas

Campos de Entrada

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

  • Embedding or Astra Vectorize: Permite usar un modelo de embeddings o la configuración de vectorización de Astra.

    • Visible en: Add, Search, Retriever

  • Ingest Data: Datos que se añadirán a la colección.

    • Visible en: Add

  • Operation: Selecciona la operación que quieres ejecutar.

    • Visible en: Add, Search, Retriever

  • Batch Size: Número opcional de datos a procesar en un solo lote.

    • Visible en: Add, Search, Retriever

  • Bulk Delete Concurrency: Nivel de concurrencia para operaciones de borrado masivo.

    • Visible en: Add, Search, Retriever

  • Bulk Insert Batch Concurrency: Nivel de concurrencia para inserciones masivas.

    • Visible en: Add, Search, Retriever

  • Bulk Insert Overwrite Concurrency: Nivel de concurrencia para inserciones masivas que sobrescriben datos existentes.

    • Visible en: Add, Search, Retriever

  • Collection Indexing Policy: Diccionario opcional que define la política de indexación de la colección.

    • Visible en: Add, Search, Retriever

  • Collection Name: Nombre de la colección dentro de Astra DB donde se almacenarán los vectores.

    • Visible en: Add, Search, Retriever

  • Metadata Indexing Exclude: Lista opcional de campos de metadatos a excluir de la indexación.

    • Visible en: Add, Search, Retriever

  • Metadata Indexing Include: Lista opcional de campos de metadatos a incluir en la indexación.

    • Visible en: Add, Search, Retriever

  • Metric: Métrica de distancia opcional para comparar vectores (cosine, dot_product, euclidean).

    • Visible en: Add, Search, Retriever

  • Namespace: Espacio de nombres opcional dentro de Astra DB para usar en la colección.

    • Visible en: Add, Search, Retriever

  • Number of Results: Número de resultados que se devolverán.

    • Visible en: Add, Search, Retriever

  • Pre Delete Collection: Si se debe eliminar la colección antes de crear una nueva.

    • Visible en: Add, Search, Retriever

  • Search Metadata Filter: Diccionario opcional de filtros a aplicar a la búsqueda.

    • Visible en: Add, Search, Retriever

  • Search Query: Consulta de búsqueda. Deja vacío para recuperar todos los documentos.

    • Visible en: Search

  • Search Score Threshold: Umbral mínimo de similitud para los resultados (solo cuando se usa “Similarity with score threshold”).

    • Visible en: Add, Search, Retriever

  • Search Type: Tipo de búsqueda a usar (Similarity, Similarity with score threshold, MMR).

    • Visible en: Add, Search, Retriever

  • Setup Mode: Modo de configuración para la creación de la colección (Sync, Async, Off).

    • Visible en: Add, Search, Retriever

  • Credential: Selecciona la credencial Astra DB API que ya has configurado en Nappai.

    • Visible en: Add, Search, Retriever

Nota: Los campos relacionados con la credencial (token, endpoint, etc.) no aparecen aquí porque ya están incluidos en la credencial que seleccionas.

Salidas

  • Retriever: Objeto de tipo Retriever que puede ser usado por otros componentes para obtener datos automáticamente.
  • Results: Lista de datos devueltos por la búsqueda.
  • Vector Store: Objeto VectorStore que representa la colección en Astra DB.

Ejemplo de Uso

1. Añadir documentos (Add)

  1. Selecciona la operación Add.
  2. Configura la Credential con la credencial “Astra DB API”.
  3. Ingresa el Collection Name (ej. my_documents).
  4. Conecta el flujo de datos que quieres almacenar en el campo Ingest Data.
  5. (Opcional) Ajusta Batch Size, Bulk Insert Batch Concurrency y Metadata Indexing Include según tus necesidades.
  6. Ejecuta el flujo. Los documentos se guardarán en la colección y el componente mostrará el objeto Vector Store en la salida.
  1. Selecciona la operación Search.
  2. Configura la Credential y el Collection Name.
  3. Escribe una Search Query (ej. “machine learning”).
  4. Ajusta Number of Results y Search Type si lo deseas.
  5. Ejecuta el flujo. Los resultados aparecerán en la salida Results y también tendrás acceso al Vector Store y al Retriever.

Componentes Relacionados

  • Embedding: Modelo que genera los vectores que se almacenan en Astra DB.
  • Retriever: Componente que utiliza el objeto Retriever generado por Astra DB para recuperar datos en flujos posteriores.
  • Vector Store: Representa la colección de vectores dentro de Astra DB y puede ser usado directamente en otros componentes de Nappai.

Consejos y Mejores Prácticas

  • Usa credenciales seguras: Configura la credencial “Astra DB API” en la sección de credenciales de Nappai y no compartas el token ni el endpoint.
  • Optimiza el rendimiento: Ajusta los parámetros de concurrencia (Bulk Insert/ Delete) cuando trabajes con grandes volúmenes de datos.
  • Controla la indexación: Si solo necesitas buscar por ciertos campos de metadatos, usa Metadata Indexing Include para reducir el tamaño del índice.
  • Prueba con pequeñas colecciones: Antes de cargar millones de documentos, prueba con una colección pequeña para asegurarte de que la configuración es correcta.
  • Revisa los logs: El componente escribe en el log de Nappai; revisa los mensajes de error para depurar problemas de conexión o de datos.

Consideraciones de Seguridad

  • Credenciales: La credencial “Astra DB API” contiene el token de aplicación y el endpoint. Asegúrate de que solo usuarios autorizados tengan acceso a esta credencial.
  • Datos sensibles: Si tus documentos contienen información confidencial, considera usar la opción de cifrado de Astra DB o aplicar filtros de metadatos para limitar la exposición.
  • Acceso a la API: Limita el acceso a la API de Astra DB a las IPs o redes que necesiten interactuar con el componente, reduciendo el riesgo de accesos no autorizados.