Merge pull request #14 from nmdra/9-full-text-search-endpoint

9 full text search endpoint

Author: nmdra

README.md

@@ -58,14 +58,24 @@ C4Context
 
 ### API Endpoints
 
-* **`POST /books`**
-  Add a new book by providing its title and description. The service generates and stores a semantic embedding of the description in the database.
+#### `POST /books`
 
-* **`GET /search?q=your+query`**
-  Perform a semantic search on the stored books using the query text. Returns a list of matching books ranked by relevance.
+Add a new book by providing its title, description, and ISBN.
+The service generates and stores a **semantic embedding** and full-text index.
 
-* **`GET /ping`**
-  Simple health check endpoint to verify if the service is running.
+#### `GET /search/vector?q=your+query`
+
+Perform a **semantic search** on stored books using vector similarity with the query.
+Returns books ranked by **cosine similarity** of embeddings.
+
+#### `GET /search/text?q=your+query`
+
+Perform a **full-text search** using PostgreSQL’s full-text index on title and description.
+Returns books ranked by **textual relevance (ts\_rank)**.
+
+#### `GET /ping`
+
+Health check endpoint to verify if the service is running.
 
 #### Example Usage
 

api/handlers.go

@@ -17,6 +17,7 @@ type AddBookRequest struct {
 	Isbn        string `json:"isbn"`
 }
 
+// POST /books
 func (h *BookHandler) AddBook(c echo.Context) error {
 	ctx := c.Request().Context()
 	var req AddBookRequest
@@ -30,14 +31,15 @@ func (h *BookHandler) AddBook(c echo.Context) error {
 	default:
 	}
 
-	err := h.Service.AddBook(c.Request().Context(), req.Isbn, req.Title, req.Description)
+	err := h.Service.AddBook(ctx, req.Isbn, req.Title, req.Description)
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, echo.Map{"error": err.Error()})
 	}
 
 	return c.JSON(http.StatusCreated, echo.Map{"status": "book added"})
 }
 
+// GET /search/vector?q=
 func (h *BookHandler) SearchBooks(c echo.Context) error {
 	ctx := c.Request().Context()
 	query := c.QueryParam("q")
@@ -61,3 +63,28 @@ func (h *BookHandler) SearchBooks(c echo.Context) error {
 
 	return c.JSON(http.StatusOK, results)
 }
+
+// GET /search/text?q=
+func (h *BookHandler) FullTextSearch(c echo.Context) error {
+	ctx := c.Request().Context()
+	query := c.QueryParam("q")
+	if query == "" {
+		return c.JSON(http.StatusBadRequest, echo.Map{"error": "missing query"})
+	}
+
+	select {
+	case <-ctx.Done():
+		return c.JSON(http.StatusRequestTimeout, echo.Map{"error": "request canceled or timed out"})
+	default:
+	}
+
+	results, err := h.Service.FullTextSearch(ctx, query)
+	if err != nil {
+		if ctx.Err() != nil {
+			return c.JSON(http.StatusRequestTimeout, echo.Map{"error": "request timed out"})
+		}
+		return c.JSON(http.StatusInternalServerError, echo.Map{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, results)
+}

cmd/main.go

@@ -98,7 +98,8 @@ func main() {
 	e.GET("/ping", func(c echo.Context) error {
 		return c.String(200, "pong")
 	})
-	e.GET("/search", bookHandler.SearchBooks)
+	e.GET("/search/semantic", bookHandler.SearchBooks)
+	e.GET("/search/text", bookHandler.FullTextSearch)
 	e.POST("/books", bookHandler.AddBook)
 
 	// e.Logger.Fatal(e.Start(fmt.Sprintf(":%d", cfg.port)))

db/books.sql

@@ -11,4 +11,11 @@ LIMIT 5;
 -- name: GetBookByISBN :one
 SELECT id, isbn
 FROM books
-WHERE isbn = $1;
+WHERE isbn = $1;
+
+-- name: SearchBooksByText :many
+SELECT id, isbn, title, description
+FROM books
+WHERE tsv @@ plainto_tsquery('english', $1)
+ORDER BY ts_rank(tsv, plainto_tsquery('english', $1)) DESC
+LIMIT 10;

db/migrations/000005_full-text-search.down.sql

@@ -0,0 +1,4 @@
+DROP INDEX IF EXISTS idx_books_tsv;
+
+ALTER TABLE books
+DROP COLUMN IF EXISTS tsv;

db/migrations/000005_full-text-search.up.sql

@@ -0,0 +1,6 @@
+ALTER TABLE books
+ADD COLUMN tsv tsvector GENERATED ALWAYS AS (
+    to_tsvector('english', coalesce(title, '') || ' ' || coalesce(description, ''))
+) STORED;
+
+CREATE INDEX idx_books_tsv ON books USING GIN (tsv);

internal/repository/books.sql.go

@@ -124,3 +124,23 @@ func cosineSimilarity(a, b []float32) (float64, error) {
 
 	return dot / (math.Sqrt(normA) * math.Sqrt(normB)), nil
 }
+
+func (s *BookService) FullTextSearch(ctx context.Context, query string) ([]repository.SearchBooksByTextRow, error) {
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	default:
+	}
+
+	if query == "" {
+		return nil, fmt.Errorf("search query cannot be empty")
+	}
+
+	books, err := s.Repository.SearchBooksByText(ctx, query)
+	if err != nil {
+		s.Logger.Error("Full-text search failed", "query", query, "error", err)
+		return nil, fmt.Errorf("full-text search failed: %w", err)
+	}
+
+	return books, nil
+}