Typesense Search Engine

# Typesense Search Engine

You are an expert in Typesense, a fast, typo-tolerant search engine that is an open-source alternative to Algolia.

## Key Principles
- Define collection schemas with proper field types
- Configure typo tolerance and ranking
- Implement faceted search with filtering
- Use geo search for location-based queries
- Secure with scoped API keys

## Collection Schema Design
```javascript
const Typesense = require("typesense");

const client = new Typesense.Client({
  nodes: [{ host: "localhost", port: "8108", protocol: "http" }],
  apiKey: "xyz123",
  connectionTimeoutSeconds: 2
});

// Create collection with schema
const productsSchema = {
  name: "products",
  fields: [
    { name: "id", type: "string" },
    { name: "name", type: "string", facet: false, infix: true },
    { name: "description", type: "string", optional: true },
    { name: "brand", type: "string", facet: true },
    { name: "categories", type: "string[]", facet: true },
    { name: "price", type: "float", facet: true },
    { name: "rating", type: "float", optional: true },
    { name: "reviews_count", type: "int32", optional: true },
    { name: "in_stock", type: "bool", facet: true },
    { name: "tags", type: "string[]", facet: true, optional: true },
    { name: "color", type: "string", facet: true, optional: true },
    { name: "popularity_score", type: "int32" },
    { name: "created_at", type: "int64" },
    { name: "location", type: "geopoint", optional: true },
    { name: "embedding", type: "float[]", num_dim: 384, optional: true }
  ],
  default_sorting_field: "popularity_score",
  token_separators: ["-", "_"],
  symbols_to_index: ["#", "+"]
};

await client.collections().create(productsSchema);
```

## Document Indexing
```javascript
// Single document
await client.collections("products").documents().create({
  id: "prod-123",
  name: "Wireless Bluetooth Headphones",
  description: "Premium noise-canceling headphones with 30-hour battery",
  brand: "AudioMax",
  categories: ["Electronics", "Audio", "Headphones"],
  price: 199.99,
  rating: 4.7,
  reviews_count: 1234,
  in_stock: true,
  tags: ["wireless", "noise-canceling", "premium"],
  color: "black",
  popularity_score: 9500,
  created_at: Date.now()
});

// Bulk import
const documents = [/* array of products */];

await client.collections("products").documents().import(documents, {
  action: "upsert",
  batch_size: 100,
  return_doc: false,
  return_id: true
});

// Import from JSONL file
const fs = require("fs");
const jsonlData = fs.readFileSync("products.jsonl");
await client.collections("products").documents().import(jsonlData, {
  action: "upsert"
});
```

## Search Queries
```javascript
// Basic search with filters
const searchResults = await client.collections("products").documents().search({
  q: "wireless headphones",
  query_by: "name,description,brand,tags",
  query_by_weights: "4,2,3,1",
  
  // Filtering
  filter_by: "categories:=[Electronics] && price:>=50 && price:<=300 && in_stock:=true",
  
  // Faceting
  facet_by: "brand,categories,color,price(0:50, 50:100, 100:200, 200:500)",
  max_facet_values: 20,
  
  // Sorting
  sort_by: "_text_match:desc,popularity_score:desc,rating:desc",
  
  // Pagination
  page: 1,
  per_page: 20,
  
  // Typo tolerance
  num_typos: 2,
  typo_tokens_threshold: 3,
  
  // Highlighting
  highlight_full_fields: "name",
  highlight_affix_num_tokens: 4,
  highlight_start_tag: "<mark>",
  highlight_end_tag: "</mark>",
  
  // Snippeting
  snippet_threshold: 30,
  
  // Grouping
  group_by: "brand",
  group_limit: 3,
  
  // Pinning specific results
  pinned_hits: "prod-featured:1,prod-sale:2",
  hidden_hits: "prod-discontinued"
});

// Process results
console.log(`Found ${searchResults.found} results in ${searchResults.search_time_ms}ms`);

searchResults.hits.forEach(hit => {
  console.log(hit.document.name);
  console.log(hit.highlights);
});

searchResults.facet_counts.forEach(facet => {
  console.log(`${facet.field_name}:`, facet.counts);
});
```

## Geo Search
```javascript
// Search with location
const geoResults = await client.collections("stores").documents().search({
  q: "*",
  query_by: "name",
  filter_by: "location:(40.7128, -74.0060, 10 km)",
  sort_by: "location(40.7128, -74.0060):asc",
  per_page: 20
});

// Polygon geo-fence
const polygonResults = await client.collections("stores").documents().search({
  q: "*",
  query_by: "name",
  filter_by: "location:(40.71, -74.01, 40.73, -74.01, 40.73, -73.99, 40.71, -73.99)"
});
```

## Vector/Semantic Search
```javascript
// Create collection with vector field
const semanticSchema = {
  name: "articles",
  fields: [
    { name: "title", type: "string" },
    { name: "content", type: "string" },
    { name: "embedding", type: "float[]", num_dim: 384 }
  ]
};

// Hybrid search (keyword + vector)
const hybridResults = await client.collections("articles").documents().search({
  q: "machine learning trends",
  query_by: "title,content",
  vector_query: "embedding:([0.12, 0.45, ...], k:100, distance_threshold: 0.5)",
  
  // Blend keyword and vector scores
  prefix: false,
  exclude_fields: "embedding"
});
```

## Scoped API Keys
```javascript
// Create search-only key with filters
const scopedKey = client.keys().generateScopedSearchKey(
  "main_search_key",
  {
    filter_by: "tenant_id:=tenant-123",
    expires_at: Math.floor(Date.now() / 1000) + 3600,
    cache_ttl: 60
  }
);

// Create key with specific permissions
await client.keys().create({
  description: "Search only key for tenant",
  actions: ["documents:search"],
  collections: ["products"],
  expires_at: Math.floor(Date.now() / 1000) + 86400
});
```

## InstantSearch Adapter
```javascript
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";
import { InstantSearch, SearchBox, Hits } from "react-instantsearch";

const typesenseAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "search-only-key",
    nodes: [{ host: "localhost", port: "8108", protocol: "http" }]
  },
  additionalSearchParameters: {
    query_by: "name,description,brand",
    query_by_weights: "4,2,1"
  }
});

function App() {
  return (
    <InstantSearch
      indexName="products"
      searchClient={typesenseAdapter.searchClient}
    >
      <SearchBox />
      <Hits />
    </InstantSearch>
  );
}
```

## Best Practices
- Use infix search for partial matching needs
- Configure query_by_weights for relevance tuning
- Implement synonyms for domain-specific terms
- Use curation rules for merchandising
- Enable analytics for search insights
- Set up replica collections for A/B testing