Product Search and Filtering
Discovery yang Cepat dan Aman

Pencarian produk bukan sekadar SELECT, tetapi pintu masuk customer ke seluruh funnel belanja.

Di React, halaman katalog punya search box, filter sidebar, sort dropdown, dan pagination. Di backend Go, semua itu harus menjadi satu kontrak query yang jelas, SQL yang aman, dan response yang stabil. Kalau discovery lambat atau salah, cart dan checkout di modul berikutnya tidak akan pernah terisi.

Di online shop skincare, customer jarang tahu nama produk persis. Mereka mengetik “toner”, lalu mempersempit: brand tertentu, untuk oily skin, dengan concern acne, di rentang harga tertentu, diurutkan dari termurah. API harus melayani perilaku itu sebagai satu endpoint yang bisa di-bookmark, di-cache, dan dilacak di analytics. Inilah fitur dengan bobot bisnis besar: produk yang tidak ditemukan sama dengan produk yang tidak terjual.

flowchart LR
  FE["React Product Listing"] -->|"GET /v1/products?q=...&sort=..."| H["Go Handler"]
  H -->|"parse + validasi"| SVC["Product Service"]
  SVC -->|"ProductFilter"| REPO["Product Repository"]
  REPO -->|"SQL parameterized + args"| DB[("PostgreSQL")]
  DB -->|"rows + total"| REPO
  REPO --> SVC
  SVC --> H
  H -->|"data[] + meta"| FE

Gambar 1. Alur discovery dari UI sampai response paginasi. Tiap lapis punya tanggung jawab tunggal: handler menerjemahkan HTTP, service memvalidasi aturan, repository menyusun SQL.

Rujukan resmi yang relevan: PostgreSQL pattern matching, array operators, GIN index, pg_trgm, serta Go strings.Builder dan pgxpool.

Mulai dari URL yang enak dipakai frontend, baru turunkan ke struct dan SQL.

Endpoint katalog harus stabil, mudah di-cache, dan mudah dibaca dari log. Desain URL-nya dulu, baru implementasi di belakangnya.

Parameter yang didukung modul ini:

Response memisahkan data (item listing) dari meta (state pagination), persis bentuk yang gampang dipakai komponen tabel atau infinite scroll di React.

GET /v1/products responseSalin
{
  "data": [
    {
      "id": 101,
      "name": "Wardah Hydrating Toner",
      "slug": "wardah-hydrating-toner",
      "brand_name": "Wardah",
      "category_name": "Toner",
      "price_min": 29000,
      "order_count": 184
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 87,
    "total_pages": 5
  }
}

Filter yang baik mengikuti bentuk data, jadi pahami dulu relasi tabelnya.

Sebelum menulis query, kunci dulu bentuk datanya. Discovery skincare menyentuh empat tabel inti dan satu tabel statistik ringkas.

erDiagram
  brands ||--o{ products : "memiliki"
  categories ||--o{ products : "memiliki"
  products ||--o{ product_variants : "punya ukuran"
  products ||--|| product_stats : "diringkas oleh"
  brands {
    bigint id PK
    text name
  }
  categories {
    bigint id PK
    text name
  }
  products {
    bigint id PK
    text name
    text slug
    text status
    bigint brand_id FK
    bigint category_id FK
    text_array skin_types
    text_array skin_concerns
    timestamptz created_at
  }
  product_variants {
    bigint id PK
    bigint product_id FK
    text status
    bigint price
  }
  product_stats {
    bigint product_id PK
    bigint order_count
  }

Gambar 2. Relasi data discovery. Harga hidup di product_variants (kolom price BIGINT rupiah), popularitas diringkas di product_stats, atribut skincare disimpan sebagai array di products.

Tiga keputusan desain yang langsung memengaruhi cara filter ditulis:

Pisahkan input filter, item listing, dan metadata pagination jadi tiga struct kecil.

Di Laravel, kamu mungkin menulis query langsung dari request()->query(). Di Go, lebih rapi memetakan query string ke struct dulu, sehingga validasi dan penyusunan SQL bekerja di atas data yang sudah bertipe.

internal/product/search_model.goSalin
package product

// Sort adalah tipe khusus agar nilai sorting tidak tertukar dengan string biasa.
type Sort string

const (
	SortNewest    Sort = "newest"
	SortPriceAsc  Sort = "price_asc"
	SortPriceDesc Sort = "price_desc"
	SortPopular   Sort = "popular"
)

// ProductFilter adalah input discovery yang sudah bertipe dan tervalidasi.
type ProductFilter struct {
	Search       string
	BrandID      int64
	CategoryID   int64
	SkinTypes    []string
	SkinConcerns []string
	PriceMin     *PriceRupiah // pointer: bedakan "0" yang valid dari "tidak dikirim"
	PriceMax     *PriceRupiah
	Sort         Sort
	Page         int
	PerPage      int
}

// PriceRupiah adalah tipe domain uang: rupiah bulat, bukan float, kolom SQL BIGINT.
type PriceRupiah int64

type ProductListItem struct {
	ID           int64
	Name         string
	Slug         string
	BrandName    string
	CategoryName string
	PriceMin     PriceRupiah
	OrderCount   int64
}

type PageMeta struct {
	Page       int
	PerPage    int
	Total      int
	TotalPages int
}

type ProductSearchResult struct {
	Items []ProductListItem
	Meta  PageMeta
}

Pilih operator berdasarkan bentuk data, bukan kebiasaan ORM.

PostgreSQL memberi beberapa cara berbeda untuk search dan filter. Yang menentukan kualitas (dan performa) adalah memilih operator yang sesuai bentuk datanya.

flowchart TD
  Q{"Jenis filter?"} -->|"nama produk (q)"| ILIKE["ILIKE '%kw%'<br/>(case-insensitive)"]
  Q -->|"brand / category (ID)"| EQ["= (equality)"]
  Q -->|"skin_type / concern (array)"| OVL["&& (array overlap)"]
  Q -->|"rentang harga (variant)"| RANGE["pv.price BETWEEN<br/>(JOIN + MIN)"]
  ILIKE -->|"index"| GIN1["GIN + gin_trgm_ops"]
  EQ -->|"index"| BTREE["B-tree (partial, status=active)"]
  OVL -->|"index"| GIN2["GIN (array)"]
  RANGE -->|"index"| BTREE2["B-tree (product_id, price)"]

Gambar 3. Peta keputusan operator. Tiap jenis filter punya operator dan jenis index yang berbeda. Memaksakan satu operator untuk semua adalah sumber utama query lambat.

Untuk search nama, ILIKE '%keyword%' sudah cukup untuk kebutuhan awal. Operator ini case-insensitive, jadi wardah, Wardah, dan WARDAH memberi hasil sama. Wildcard di depan (%toner%) perlu perhatian performa saat data besar, dan kita atasi dengan GIN trigram di section index.

search-by-name.sqlSalin
SELECT p.id, p.name, p.slug
FROM products p
WHERE p.status = 'active'
  AND p.name ILIKE '%toner%';

Brand dan category memakai equality berbasis ID, relasinya stabil dan murah di-index.

filter-brand-category.sqlSalin
SELECT p.id, p.name, p.slug
FROM products p
WHERE p.status = 'active'
  AND p.brand_id = 3
  AND p.category_id = 1;

Atribut skincare memakai operator overlap &&, yang berarti “punya minimal satu nilai yang sama”. Produk untuk ['oily', 'combination'] cocok ketika customer memfilter oily.

filter-skin-attributes.sqlSalin
SELECT p.id, p.name, p.slug
FROM products p
WHERE p.status = 'active'
  AND p.skin_types && ARRAY['oily']::text[]
  AND p.skin_concerns && ARRAY['acne', 'large_pores']::text[];

Harga harus membaca product_variants, bukan products. Satu produk bisa punya variant 100ml dan 200ml dengan harga berbeda, jadi filter menjawab “apakah ada variant aktif di rentang ini”, lalu menampilkan MIN(price).

filter-price-range.sqlSalin
SELECT p.id, p.name, MIN(pv.price) AS price_min
FROM products p
JOIN product_variants pv ON pv.product_id = p.id AND pv.status = 'active'
WHERE p.status = 'active'
  AND pv.price >= 25000
  AND pv.price <= 100000
GROUP BY p.id, p.name;

SQL boleh dinamis, tetapi nilai user tetap masuk lewat placeholder.

Filter yang opsional membuat SQL-nya dinamis: kadang ada WHERE name ILIKE, kadang tidak. Query builder di sini bukan ORM, hanya pola kecil untuk menyusun potongan SQL plus daftar argumen secara aman.

Inti polanya satu method kecil: addArg menambah nilai ke slice args lalu mengembalikan placeholder yang sesuai posisinya. Penomoran $N otomatis ikut jumlah argumen, jadi tidak ada risiko salah hitung.

internal/product/repository_search.goSalin
package product

import (
	"context"
	"errors"
	"fmt"
	"strings"

	"github.com/jackc/pgx/v5/pgxpool"
)

var ErrInvalidSort = errors.New("invalid product sort")

type Repository struct {
	pool *pgxpool.Pool
}

func NewRepository(pool *pgxpool.Pool) *Repository {
	return &Repository{pool: pool}
}

// queryParts mengumpulkan potongan SQL dinamis plus argumennya.
type queryParts struct {
	joins []string
	where []string
	args  []any
}

// addArg mendaftarkan satu nilai dan mengembalikan placeholder-nya ($1, $2, ...).
func (p *queryParts) addArg(value any) string {
	p.args = append(p.args, value)
	return fmt.Sprintf("$%d", len(p.args))
}

func (r *Repository) ListProducts(ctx context.Context, filter ProductFilter) (ProductSearchResult, error) {
	orderBy, err := orderByClause(filter.Sort)
	if err != nil {
		return ProductSearchResult{}, err
	}

	parts := buildQueryParts(filter)
	whereSQL := strings.Join(parts.where, "\n  AND ")
	joinSQL := strings.Join(parts.joins, "\n")

	// Hitung total produk unik yang cocok filter, SEBELUM limit/offset.
	countSQL := fmt.Sprintf(`
SELECT COUNT(DISTINCT p.id)
FROM products p
%s
WHERE %s`, joinSQL, whereSQL)

	var total int
	if err := r.pool.QueryRow(ctx, countSQL, parts.args...).Scan(&total); err != nil {
		return ProductSearchResult{}, fmt.Errorf("count products: %w", err)
	}

	// limit dan offset adalah nilai user juga: tetap lewat placeholder.
	limitPH := parts.addArg(filter.PerPage)
	offsetPH := parts.addArg((filter.Page - 1) * filter.PerPage)

	listSQL := fmt.Sprintf(`
SELECT
  p.id, p.name, p.slug,
  b.name AS brand_name,
  c.name AS category_name,
  MIN(pv.price) AS price_min,
  COALESCE(ps.order_count, 0) AS order_count
FROM products p
%s
WHERE %s
GROUP BY p.id, p.name, p.slug, b.name, c.name, ps.order_count, p.created_at
ORDER BY %s
LIMIT %s OFFSET %s`, joinSQL, whereSQL, orderBy, limitPH, offsetPH)

	rows, err := r.pool.Query(ctx, listSQL, parts.args...)
	if err != nil {
		return ProductSearchResult{}, fmt.Errorf("list products: %w", err)
	}
	defer rows.Close()

	items := make([]ProductListItem, 0, filter.PerPage)
	for rows.Next() {
		var item ProductListItem
		if err := rows.Scan(
			&item.ID, &item.Name, &item.Slug,
			&item.BrandName, &item.CategoryName,
			&item.PriceMin, &item.OrderCount,
		); err != nil {
			return ProductSearchResult{}, fmt.Errorf("scan product: %w", err)
		}
		items = append(items, item)
	}
	if err := rows.Err(); err != nil {
		return ProductSearchResult{}, fmt.Errorf("iterate products: %w", err)
	}

	return ProductSearchResult{
		Items: items,
		Meta: PageMeta{
			Page:       filter.Page,
			PerPage:    filter.PerPage,
			Total:      total,
			TotalPages: totalPages(total, filter.PerPage),
		},
	}, nil
}

buildQueryParts menambahkan klausa hanya untuk filter yang benar-benar dikirim. Perhatikan bahwa nilai array (SkinTypes, SkinConcerns) diserahkan langsung ke pgx sebagai []string: pgx v5 men-encode slice Go menjadi array PostgreSQL pada parameter, jadi tidak perlu merangkai string ARRAY[...] sendiri.

internal/product/repository_search.go (lanjutan)Salin
func buildQueryParts(filter ProductFilter) queryParts {
	parts := queryParts{
		joins: []string{
			"JOIN brands b ON b.id = p.brand_id",
			"JOIN categories c ON c.id = p.category_id",
			"JOIN product_variants pv ON pv.product_id = p.id AND pv.status = 'active'",
			"LEFT JOIN product_stats ps ON ps.product_id = p.id",
		},
		where: []string{"p.status = 'active'"},
	}

	if filter.Search != "" {
		// escapeLike menetralkan %, _, dan \ agar diperlakukan harfiah.
		pattern := "%" + escapeLike(filter.Search) + "%"
		parts.where = append(parts.where,
			"p.name ILIKE "+parts.addArg(pattern)+` ESCAPE '\'`)
	}
	if filter.BrandID > 0 {
		parts.where = append(parts.where, "p.brand_id = "+parts.addArg(filter.BrandID))
	}
	if filter.CategoryID > 0 {
		parts.where = append(parts.where, "p.category_id = "+parts.addArg(filter.CategoryID))
	}
	if len(filter.SkinTypes) > 0 {
		parts.where = append(parts.where, "p.skin_types && "+parts.addArg(filter.SkinTypes))
	}
	if len(filter.SkinConcerns) > 0 {
		parts.where = append(parts.where, "p.skin_concerns && "+parts.addArg(filter.SkinConcerns))
	}
	if filter.PriceMin != nil {
		parts.where = append(parts.where, "pv.price >= "+parts.addArg(int64(*filter.PriceMin)))
	}
	if filter.PriceMax != nil {
		parts.where = append(parts.where, "pv.price <= "+parts.addArg(int64(*filter.PriceMax)))
	}
	return parts
}

// escapeLike menetralkan karakter wildcard agar input customer diperlakukan harfiah.
// "50%" dicari sebagai teks "50%", bukan "apa saja yang diawali 50".
func escapeLike(value string) string {
	r := strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`)
	return r.Replace(value)
}

Sorting adalah kontrak bisnis, pagination adalah kontrak operasional.

Frontend butuh pilihan sorting yang terasa natural. Backend butuh sorting yang deterministik agar baris tidak lompat antar halaman. Kuncinya: selalu sertakan tie-breaker unik (id) di akhir ORDER BY.

Karena placeholder hanya bisa menggantikan nilai, bukan nama kolom atau arah sorting, ORDER BY harus dipilih dari daftar yang kita kontrol. Map sort ke klausa SQL lewat fungsi whitelist yang mengembalikan error untuk nilai tak dikenal.

internal/product/sort.goSalin
package product

// orderByClause memetakan Sort tervalidasi ke klausa ORDER BY.
// Setiap klausa diakhiri p.id agar urutan deterministik (tidak ada baris kembar
// yang bertukar posisi antar halaman saat nilai sort sama).
func orderByClause(sort Sort) (string, error) {
	switch sort {
	case SortNewest:
		return "p.created_at DESC, p.id DESC", nil
	case SortPriceAsc:
		return "price_min ASC, p.id ASC", nil
	case SortPriceDesc:
		return "price_min DESC, p.id DESC", nil
	case SortPopular:
		return "order_count DESC, p.created_at DESC, p.id DESC", nil
	default:
		return "", ErrInvalidSort
	}
}

Pagination memakai page dan per_page. Rumus offset sederhana: offset = (page - 1) * per_page. Response meta mengembalikan total dan total_pages agar React bisa membangun navigasi halaman.

internal/product/pagination.goSalin
package product

func totalPages(total, perPage int) int {
	if total == 0 || perPage <= 0 {
		return 0
	}
	// Pembagian membulat ke atas tanpa float: (a + b - 1) / b.
	return (total + perPage - 1) / perPage
}

db/migrations/051_product_stats.up.sqlSalin
CREATE TABLE product_stats (
  product_id BIGINT PRIMARY KEY REFERENCES products(id),
  order_count BIGINT NOT NULL DEFAULT 0,
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

Handler menerjemahkan HTTP, service memegang aturan, repository menyusun SQL.

Sesuai layering Roadmap 4, parsing query string dan validasi aturan tidak bercampur. Handler mengubah *http.Request menjadi ProductFilter mentah, service menormalkan dan memvalidasi, repository mengeksekusi.

Handler fokus pada satu hal: membaca query string. Ia tidak tahu aturan bisnis (batas per_page, sort default), hanya menerjemahkan tipe.

internal/product/handler_search.goSalin
package product

import (
	"net/http"
	"strconv"
)

func parseProductFilter(r *http.Request) (ProductFilter, error) {
	q := r.URL.Query()

	brandID, err := parseInt64(q.Get("brand_id"))
	if err != nil {
		return ProductFilter{}, err
	}
	categoryID, err := parseInt64(q.Get("category_id"))
	if err != nil {
		return ProductFilter{}, err
	}
	priceMin, err := parseOptionalPrice(q.Get("price_min"))
	if err != nil {
		return ProductFilter{}, err
	}
	priceMax, err := parseOptionalPrice(q.Get("price_max"))
	if err != nil {
		return ProductFilter{}, err
	}
	page, err := parseIntDefault(q.Get("page"), 1)
	if err != nil {
		return ProductFilter{}, err
	}
	perPage, err := parseIntDefault(q.Get("per_page"), 20)
	if err != nil {
		return ProductFilter{}, err
	}

	return ProductFilter{
		Search:       q.Get("q"),
		BrandID:      brandID,
		CategoryID:   categoryID,
		SkinTypes:    q["skin_type"], // boleh muncul berkali-kali
		SkinConcerns: q["concern"],
		PriceMin:     priceMin,
		PriceMax:     priceMax,
		Sort:         Sort(q.Get("sort")),
		Page:         page,
		PerPage:      perPage,
	}, nil
}

func parseInt64(value string) (int64, error) {
	if value == "" {
		return 0, nil
	}
	return strconv.ParseInt(value, 10, 64)
}

func parseIntDefault(value string, fallback int) (int, error) {
	if value == "" {
		return fallback, nil
	}
	return strconv.Atoi(value)
}

func parseOptionalPrice(value string) (*PriceRupiah, error) {
	if value == "" {
		return nil, nil // tidak dikirim, bukan nol
	}
	n, err := strconv.ParseInt(value, 10, 64)
	if err != nil {
		return nil, err
	}
	p := PriceRupiah(n)
	return &p, nil
}

Service menormalkan filter (default dan batas) lalu memanggil repository. Di sinilah aturan bisnis hidup, dan tempat yang paling mudah diuji tanpa database.

internal/product/service.goSalin
package product

import (
	"context"
	"strings"
)

// Lister adalah interface kecil di sisi pemakai: service hanya butuh ini.
type Lister interface {
	ListProducts(ctx context.Context, filter ProductFilter) (ProductSearchResult, error)
}

type Service struct {
	repo Lister
}

func NewService(repo Lister) *Service {
	return &Service{repo: repo}
}

func (s *Service) Search(ctx context.Context, filter ProductFilter) (ProductSearchResult, error) {
	filter = normalizeFilter(filter)
	return s.repo.ListProducts(ctx, filter)
}

// normalizeFilter menerapkan default dan batas yang sehat sebelum query dibangun.
func normalizeFilter(filter ProductFilter) ProductFilter {
	filter.Search = strings.TrimSpace(filter.Search)

	if filter.Page < 1 {
		filter.Page = 1
	}
	switch {
	case filter.PerPage < 1:
		filter.PerPage = 20
	case filter.PerPage > 100:
		filter.PerPage = 100 // batas atas: lindungi database
	}
	if filter.Sort == "" {
		filter.Sort = SortNewest
	}
	return filter
}

TerminalSalin
curl "http://localhost:8080/v1/products?category_id=1&skin_type=oily&concern=acne&sort=price_asc&page=1&per_page=20"

Index mengikuti pola query yang benar-benar dipakai, bukan semua kolom diberi index.

Discovery dipanggil sangat sering, kadang lebih sering dari checkout. Tanpa index yang tepat, endpoint ini jadi bottleneck pertama. Tetapi index yang asal banyak memperlambat write dan memakan storage, jadi setiap index harus punya query yang membenarkannya.

PostgreSQL memakai B-tree sebagai default, cocok untuk equality (brand_id, category_id) dan sorting (created_at). Untuk array overlap &&, GIN index yang cocok. Untuk ILIKE '%keyword%' dengan wildcard di depan, B-tree tidak terpakai sama sekali, jadi kita pasang extension pg_trgm dengan GIN index yang bisa mempercepat pencocokan substring.

db/migrations/052_product_search_indexes.up.sqlSalin
CREATE EXTENSION IF NOT EXISTS pg_trgm;

-- Search nama: trigram GIN mempercepat ILIKE '%kw%' (termasuk wildcard di depan).
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_products_name_trgm
ON products USING GIN (name gin_trgm_ops);

-- Equality filter, di-scope ke produk aktif (partial index lebih kecil dan tajam).
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_products_active_brand
ON products (brand_id) WHERE status = 'active';

CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_products_active_category
ON products (category_id) WHERE status = 'active';

-- Sorting newest: cocokkan arah dengan ORDER BY agar index langsung terpakai.
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_products_active_created
ON products (created_at DESC, id DESC) WHERE status = 'active';

-- Array overlap: GIN untuk &&.
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_products_skin_types_gin
ON products USING GIN (skin_types);

CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_products_skin_concerns_gin
ON products USING GIN (skin_concerns);

-- Filter harga + MIN: index gabungan di variant aktif.
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_variants_active_product_price
ON product_variants (product_id, price) WHERE status = 'active';

-- Sorting popular.
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_product_stats_order_count
ON product_stats (order_count DESC, product_id);

Jangan percaya feeling. Buktikan index dipakai dengan EXPLAIN ANALYZE, dan baca apakah planner memilih Bitmap Index Scan (index terpakai) atau Seq Scan (tabel dipindai penuh).

explain-product-search.sqlSalin
EXPLAIN ANALYZE
SELECT p.id, p.name
FROM products p
JOIN product_variants pv ON pv.product_id = p.id AND pv.status = 'active'
WHERE p.status = 'active'
  AND p.name ILIKE '%toner%'
  AND p.skin_types && ARRAY['oily']::text[]
ORDER BY p.created_at DESC, p.id DESC
LIMIT 20 OFFSET 0;

Mayoritas bug search bukan di SQL rumit, tetapi di detail kecil yang diremehkan.

Developer dari JS, PHP, atau ORM biasanya tersandung di tiga area: dynamic SQL, pagination, dan asumsi performa.

Search dan filter adalah fondasi pengalaman belanja sebelum cart dan checkout.

Katalog skincare yang baik memahami nama produk, brand, kategori, tipe kulit, concern, harga variant, popularitas, dan pagination, semua dalam satu endpoint yang aman dan ber-index.

Setelah modul ini, proyek online shop skincare punya API discovery yang realistis untuk halaman katalog React: customer bisa menemukan produk lewat search, filter, sort, dan pagination, dengan SQL yang aman dan cepat. Modul berikutnya di Roadmap 5 memakai produk yang ditemukan ini sebagai input ke cart, inventory, dan checkout, sehingga kualitas search langsung memengaruhi kualitas seluruh funnel belanja. Keyset pagination dan integrasi search engine khusus dibahas saat scaling di Roadmap 9.