Pendahuluan

Satu kueri di seluruh proyek Anda - produk, halaman, blok, formulir, pesanan, dan lainnya, dikelompokkan berdasarkan jenis entitas.

---

🎯 Apa yang dilakukan modul ini?

Modul Search membungkus endpoint pencarian lintas-entitas publik. Anda mengirimkan kueri teks dan mendapatkan kembali setiap catatan yang nama atau nilai atributnya cocok, dari 18 jenis entitas sekaligus, dikelompokkan per jenis dan dianotasi dengan bagaimana setiap catatan cocok.

Gunakan ini untuk menggerakkan kotak "cari semuanya" global - jenis yang menunjukkan beberapa produk, beberapa halaman, dan formulir yang cocok dalam satu dropdown - dan kemudian menyelami satu jenis ketika pengguna meminta lebih banyak.

Ini adalah pencarian kata kunci: ini mencocokkan pada teks literal dari judul, pengidentifikasi, URL, dan nilai atribut. Untuk pencarian berbasis makna (kueri seperti "jaket hangat untuk musim dingin" yang cocok dengan produk bernama "parka berisolasi"), gunakan pencarian semantik dari modul individu - lihat Pencarian vektor vs pencarian global di bawah.

🚀 Panduan Cepat

Inisialisasi modul dari defineOneEntry:

const { Search } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Cari semuanya, lalu telusuri grup:

// Search every entity type for "winter".
const result = await Search.globalSearch('winter');

console.log(result.query); // "winter"

result.groups.forEach((group) => {
  console.log(group.type, group.items.length, group.hasMore);

  group.items.forEach((item) => {
    console.log(item.id, item.title, item.matchKind, item.fragment);
  });
});

✨ Konsep Kunci

Grup

Responsnya bukan daftar datar. Ini adalah { query, groups }, di mana setiap grup menyimpan catatan dari satu jenis entitas:

{
  query: "winter",
  groups: [
    { type: "products", items: [ /* … */ ], hasMore: false },
    { type: "pages",    items: [ /* … */ ], hasMore: false }
  ]
}

hasMore memberi tahu Anda apakah ada lebih banyak catatan dari jenis itu yang ada di luar halaman yang dikembalikan - petunjuk untuk menawarkan tautan "tampilkan semua produk" yang menjalankan ulang kueri dalam mode drilldown.

Konteks kecocokan

Setiap item membawa konteks tentang bagaimana ia cocok, sehingga Anda dapat merender baris hasil yang bermakna alih-alih hanya judul kosong:

Field	Apa yang diberitahukan kepada Anda
matchKind	Jenis peringkat kecocokan: exact, title, attributeName, atau attributeValue
matchedField	Bidang konkret yang cocok: id, title, identifier, url, attributeName, attributeValue, importId, nodeName
matchedAttribute	Atribut tempat kecocokan terjadi (ketika kecocokan berasal dari atribut)
fragment	Konteks teks biasa di sekitar kecocokan, tanpa markup - sorot sendiri
langCode	Bahasa dari nilai yang cocok, sehingga Anda dapat memberi label pada hasil lintas-bahasa
parent	Catatan pemilik untuk entitas yang tidak memiliki halaman sendiri (sebuah slide → bloknya, sebuah pesanan → penyimpanannya)

Jenis entitas

types mempersempit pencarian. Kirimkan salah satu dari ini, dan SDK mengirimkannya terpisah dengan koma:

products, pages, blocks, slides, templates, discounts, user_groups, users, admins, menus, forms, attributes_sets, attributes, orders, workflows, events, subscriptions, collections.

Hapus types untuk mencari semuanya.

Mode drilldown

offset dan limit mengalihkan endpoint ke mode drilldown - paging melalui satu jenis entitas alih-alih menampilkan semua dari mereka.

⚠️ Mereka diterima hanya bersama dengan tepat satu jenis yang dapat diakses dalam types. Kombinasi lain akan menjawab 400 - Mode drilldown (limit/offset) memerlukan tepat satu jenis yang dapat diakses dalam types.

SDK tidak mengatur default: hapus keduanya dan setiap grup kembali dalam keadaan penuh.

// Overview: every type, every group complete.
const overview = await Search.globalSearch('winter');

// Drilldown: page 1 of the products only.
const products = await Search.globalSearch('winter', ['products'], 'visible', 0, 20);

Visibilitas

visibility menyaring catatan yang dicari: 'all' (default), 'visible', atau 'hidden'.

📋 Apa yang Perlu Anda Ketahui

• id adalah angka untuk sebagian besar jenis, string untuk workflows dan atribut - number | string, jadi jangan menganggap id numerik saat membangun kunci atau URL.
• title bersifat opsional: catatan tanpa nama sendiri (pesanan, pengguna tanpa login) kembali tanpa itu. Kembali ke identifier atau subtitle.
• subtitle membawa baris sekunder yang kebetulan dimiliki jenis tersebut - URL halaman, penyimpanan pesanan, nama node.
• attributeSetId hanya ada untuk type: "attributes", menunjuk pada set yang dimiliki atribut tersebut.
• Hanya catatan yang dapat dilihat oleh pemanggil saat ini yang dikembalikan; pencarian menghormati aturan akses yang sama seperti sisa API.

---

📊 Tabel Referensi Cepat

Metode	Deskripsi
globalSearch()	Mencari nama dan nilai atribut di semua jenis entitas

Pencarian vektor vs pencarian global

Keduanya menemukan catatan dari kueri teks, tetapi mereka menjawab pertanyaan yang berbeda:

	globalSearch	get…ByVectorSearch
Mencocokkan pada	Teks literal dari judul, pengidentifikasi, URL, dan nilai atribut	Makna - kesamaan semantik (vektor)
Lingkup	18 jenis entitas dalam satu panggilan	Satu modul per panggilan
Mengembalikan	{ query, groups[] } - dikelompokkan berdasarkan jenis	{ items, total } - wadah datar
Penggunaan khas	Kotak pencarian global / palet perintah	"Temukan sesuatu yang mirip dengan ini" di satu entitas

Rekan-rekan semantik hidup di modul itu sendiri: products, pages, users, orders, discounts, admins dan form data.

❓ Pertanyaan Umum (FAQ)

Mengapa offset / limit saya dijawab dengan 400?

Karena mereka hanya berfungsi dalam mode drilldown. Kirimkan tepat satu jenis entitas yang dapat diakses dalam types bersamaan dengan mereka, atau hapus sepenuhnya.

---

Bagaimana cara saya menyoroti kecocokan di UI?

Gunakan fragment - itu adalah konteks teks biasa di sekitar kecocokan, sengaja bebas dari markup, sehingga Anda dapat menyoroti kueri di dalamnya sendiri tanpa mensterilkan apa pun.

---

Sebuah item tidak memiliki title. Apakah itu bug?

Tidak. Pesanan dan pengguna tanpa login tidak memiliki nama sendiri, jadi title tidak ada. Render identifier, subtitle, atau label spesifik jenis sebagai gantinya.

---

Bisakah saya mencari catatan yang tersembunyi?

Kirimkan visibility: 'hidden' (atau 'all') - tergantung pada aturan akses yang berlaku untuk pemanggil.

---

🎓 Praktik Terbaik

• Debounce kueri dalam kotak pencarian saat Anda mengetik: setiap ketukan adalah permintaan.
• Tampilkan panggilan ringkasan terlebih dahulu (tanpa offset/limit), lalu beralih ke drilldown ketika pengguna memilih jenis - itulah tepatnya fungsi hasMore.
• Persempit types ke apa yang benar-benar dapat dirender UI Anda; mencari 18 jenis untuk menampilkan 2 adalah pekerjaan yang terbuang.
• Perlakukan id sebagai number | string saat membangun tautan dan kunci React.

---

🔗 Dokumentasi Terkait

• Modul Produk - Pencarian produk semantik dan katalog produk
• Modul Halaman - Halaman yang dikembalikan dalam grup pages
• Modul Filter - Pohon filter yang dikurasi untuk navigasi terfasilitasi

---