Nuestro viaje para crear un índice de búsqueda con Algolia y NodeJS

Me asocié con Soma Osvay, ingeniero de Starschema Full Stack, para escribir sobre un proyecto cercano a mí: la documentación para desarrolladores. Soma y yo esperamos que disfrute este artículo donde cubrimos el caso de uso y los desafíos y la implementación que se le ocurrió a Soma.

Aquí en Starschema, tenemos muchos proyectos que hemos realizado como parte de una consulta con documentación de rebajas . Cuando apoyamos estas soluciones existentes o queremos desarrollar un nuevo proyecto, a menudo queremos buscar en toda la documentación. Actualmente no tenemos una solución, lo que nos cuesta horas-hombre ya que tenemos que hacer este trabajo manualmente.

Caso de uso

Necesitamos poder buscar proyectos relacionados con temas específicos para verificar detalles de implementación, obtener ideas del código y mucho más. El equipo de ventas también necesita una solución para determinar qué tipo de proyectos ha completado nuestro equipo para ciertos temas y poder comunicarlo rápidamente a los clientes potenciales.

También sería genial tener algo como un desbordamiento de pila interno para nuestros desarrolladores, ya que estamos haciendo mucho trabajo técnico profundo en Tableau. Los gerentes de proyecto también deben poder determinar qué empleados han trabajado con ciertas tecnologías para que puedan obtener respuestas a sus preguntas de manera rápida y sencilla.

En resumen, necesitamos poder buscar nuestros propios proyectos en función de los siguientes atributos:

1. Tecnologías utilizadas (lenguajes de codificación, bases de datos, etc.)
2. Palabras clave del proyecto (etiquetas)
3. La propia documentación del proyecto, como instrucciones de instalación, documentación técnica, etc.
4. Periodo de tiempo de cuando ocurrió el proyecto

Todos estos atributos existen dentro de los archivos de rebajas de documentación interna; solo necesitamos una forma de buscarlos.

Plan de IMPLEMENTACION

El plan es utilizar una CLI de NodeJS como prueba de concepto que:

1. Raspe los principales repositorios públicos de GitHub y tome el archivo de descuento README (que en última instancia representará nuestros proyectos internos)
2. Almacena los archivos de documentación en Algolia junto con la información básica del proyecto (título, lenguaje(s) de programación, etiquetas, etc.)

La CLI contendrá argumentos avanzados de registro y línea de comandos para facilitar su uso. También queremos alojarlo en la web para que la gente pueda probarlo.

Desafío

El mayor desafío en cuestión es el tamaño del registro: Algolia solo permite que nuestros registros tengan un máximo de 100 KB. Sin embargo, la mayoría de los archivos de documentación de rebajas son mucho más grandes. La solución es que necesitamos dividir los archivos de rebajas en varias piezas dentro del Índice. También debemos asegurarnos de que cuando buscamos algo, un solo proyecto solo aparece una vez, aunque esté dividido en varios registros.

Afortunadamente, Algolia tiene una función distinta, por lo que podemos desduplicar estos resultados muy fácilmente.

Implementación del indexador

Para que el uso de Indexer sea lo más fácil posible, opté por crear una CLI como se mencionó anteriormente. Después de proporcionar los argumentos necesarios, la herramienta inicializará automáticamente el repositorio, eliminará los registros existentes y configurará los ajustes de relevancia.

El motor de la herramienta es una API de GitHub sencilla que toma la cantidad solicitada de repositorios principales y extrae todos sus metadatos y descarga el archivo README. También filtrará los repositorios a los que les falta un propietario o un archivo README, lo que nos brinda los mejores resultados. Finalmente, también convertirá el contenido de rebajas a HTML para una representación más sencilla en la interfaz.

Para mantener el tamaño del registro bajo control, la herramienta dividirá automáticamente los LÉAME de más de 50 000 caracteres en registros adicionales. De esta forma, los registros no serán demasiado grandes, pero un solo registro debería seguir sirviendo a casi todos los repositorios. Luego sincronizará esta información con los registros de Algolia 100 a la vez para que podamos cumplir con sus recomendaciones de procesamiento por lotes como se describe aquí en la documentación.

Implementación Frontend

Como punto de partida, aproveché la biblioteca create-instantsearch-app lanzada por Algolia y lancé un modelo InstantSearch.js. Desde aquí, pude agregar widgets adicionales proporcionados por InstantSearch.js, como la paginación y el selector de tamaño de página, que funcionaron muy bien.

Como también recopilamos metadatos del repositorio con el descuento, también necesitábamos personalizar el componente de visitas para incluir esta información adicional. A menudo, los metadatos son tan importantes como la descripción de la biblioteca para que los desarrolladores puedan ver de un vistazo si es una biblioteca popular, quién la lanzó, las etiquetas y mucho más. También agregué facetas para que los usuarios pudieran filtrar por lenguaje de programación, etiquetas o cuántas veces se ha bifurcado.

La pieza final del rompecabezas fue agregar el botón 'Abrir documentación' que le permite leer rápida y fácilmente el contenido de rebajas para el repositorio en una ventana emergente sin salir de la aplicación. Si el registro en el que estamos haciendo clic tiene varias filas, cargará automáticamente los registros adicionales y los concatenará en la pantalla, ¡genial!

Conclusión

Este proyecto fue una prueba divertida y realmente me mostró cuán flexible es Algolia para diferentes casos de uso como el nuestro. Los widgets listos para usar me ahorraron mucho tiempo durante la creación de prototipos y tener resultados relevantes desde las primeras pulsaciones de teclas es muy impresionante. También creo que sería muy interesante si pudiéramos aprovechar el poder de Algolia Recommend si pudiéramos generar suficientes eventos de usuarios que hacen clic en proyectos internamente.

Puede ver una demostración en vivo del proyecto de prueba de GitHub aquí , con un botón que lo configurará con las credenciales de demostración predeterminadas para ver nuestro índice. ¿Está interesado en el código de indexación de backend? ¡Puedes encontrar eso aquí en GitHub!

También publicado aquí.