Smart Search

Reference for the SearchService class in the Tybrite SDK.

The SearchService class (accessed via client.search) provides both traditional keyword-based search and advanced AI-powered semantic search capabilities.

Methods

searchProducts

Fast, keyword-based search optimized for exact matches, SKUs, and product names. It uses case-insensitive partial matching to find relevant results quickly.

const result = await client.search.searchProducts({
  q: 'iPhone 15', // You can use 'q' or 'query'
  limit: 10
});

console.log(`Found ${result.totalResults} results in ${result.searchTimeMs}ms`);

---

semanticSearch

Leverage LLM-powered semantic search that understands intent and context. This allows customers to find products using natural language descriptions even if they don’t know the exact product name.

Key Support: Both Secret Keys and Publishable Keys are supported for semantic search, allowing you to implement AI-powered search directly in your frontend.

const result = await client.search.semanticSearch({
  requestBody: {
    query: 'something waterproof for hiking in cold weather',
    limit: 5,
    minScore: 0.7 // Optional: tune relevance threshold
  }
});

Comparison: Text vs. Semantic

Feature	searchProducts (Text)	semanticSearch (AI)
Logic	ILIKE Pattern matching	Vector Cosine Similarity
Best For	SKUs, Model numbers, Exact names	Natural language, Intent, “Vibes”
Example	”MacBook Pro”, “SKU-990"	"a laptop for professional video editing”
Speed	Ultra-fast (< 50ms)	Fast (< 250ms)

---

Zero-Result Fallback: A powerful UX pattern is to first call searchProducts. If totalResults is 0, gracefully fallback to semanticSearch to suggest products that might still interest the user.

---

Why is semanticSearch a POST? POST /v1/search is intentionally accessible to publishable keys despite using the POST verb. It is a read-only operation — POST is used purely to support complex JSON request bodies (query, minScore, filters). No state is mutated and no 403 is returned for publishable keys.

Response Codes

Both methods accept publishable and secret keys. searchProducts is GET; semanticSearch is POST (read-only).

Code	Meaning
200	Search results returned (may be empty — check totalResults).
400	Missing query/q parameter, invalid limit, or malformed request body.
401	Invalid or missing API key.
429	Rate limit exceeded.
500	Internal server error or upstream Gemini embedding failure (semantic search only).