Typesense 2026: 하루 100만 건 처리하는 오픈소스 인스턴트 검색 API — 셀프 호스팅 설정 가이드

mkdir -p /tmp/typesense-data

# API 키 생성
export TYPESENSE_API_KEY=$(openssl rand -hex 24)
echo "Your API key: $TYPESENSE_API_KEY"

# Typesense 27.1 실행
docker run -d \
  --name typesense \
  --restart unless-stopped \
  -p 8108:8108 \
  -v /tmp/typesense-data:/data \
  typesense/typesense:27.1 \
  --data-dir /data \
  --api-key=$TYPESENSE_API_KEY \
  --enable-cors

curl -s "http://localhost:8108/health" | jq .
# 예상 출력: { "ok": true }

# 전자상거래 제품 카탈로그 스키마 정의
curl -s "http://localhost:8108/collections" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  -d '{
    "name": "products",
    "fields": [
      { "name": "name", "type": "string", "facet": false },
      { "name": "description", "type": "string", "facet": false },
      { "name": "price", "type": "float", "facet": true, "sort": true },
      { "name": "category", "type": "string", "facet": true },
      { "name": "rating", "type": "float", "facet": true, "sort": true },
      { "name": "in_stock", "type": "bool", "facet": true },
      { "name": "location", "type": "geopoint" }
    ],
    "default_sorting_field": "rating"
  }' | jq .

# 가져오기 엔드포인트를 사용한 문서 가져오기
curl -s "http://localhost:8108/collections/products/documents/import?action=create" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  -d '
  {"name": "Wireless Bluetooth Headphones", "description": "Noise cancelling over-ear headphones", "price": 79.99, "category": "Electronics", "rating": 4.5, "in_stock": true, "location": [40.7128, -74.0060]}
  {"name": "Mechanical Keyboard", "description": "RGB backlit mechanical keyboard with blue switches", "price": 129.99, "category": "Electronics", "rating": 4.7, "in_stock": true, "location": [37.7749, -122.4194]}
  {"name": "Running Shoes", "description": "Lightweight running shoes for marathon training", "price": 89.50, "category": "Sports", "rating": 4.2, "in_stock": false, "location": [51.5074, -0.1278]}
  {"name": "Yoga Mat", "description": "Non-slip eco-friendly yoga mat", "price": 29.99, "category": "Sports", "rating": 4.8, "in_stock": true, "location": [48.8566, 2.3522]}
  '

# 오타 허용 검색
curl -s "http://localhost:8108/collections/products/documents/search?\
q=headphons&\
query_by=name,description&\
filter_by=price:>=50&&<=150&\
sort_by=rating:desc&\
facet_by=category&\
page=1&\
per_page=10" \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" | jq .

npm install typesense

const Typesense = require('typesense');

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

// 검색
async function searchProducts(query) {
  const results = await client.collections('products')
    .documents()
    .search({
      'q': query,
      'query_by': 'name,description',
      'filter_by': 'in_stock:true',
      'sort_by': 'rating:desc',
      'per_page': 10
    });
  
  console.log(`Found ${results.found} results`);
  results.hits.forEach(hit => {
    console.log(`- ${hit.document.name} ($${hit.document.price})`);
  });
}

searchProducts('headphons'); // 오타도 작동함

pip install typesense

import typesense
import os

client = typesense.Client({
    'nodes': [{'host': 'localhost', 'port': '8108', 'protocol': 'http'}],
    'api_key': os.environ['TYPESENSE_API_KEY'],
    'connection_timeout_seconds': 2
})

# 패싯이 포함된 검색
results = client.collections['products'].documents.search({
    'q': 'keyboard',
    'query_by': 'name,description',
    'facet_by': 'category,price',
    'sort_by': 'rating:desc',
    'per_page': 10
})

print(f"Total: {results['found']}")
for hit in results['hits']:
    print(f"  {hit['document']['name']} - ${hit['document']['price']}")

npm install typesense-instantsearch-adapter react-instantsearch-dom

import React from 'react';
import { InstantSearch, SearchBox, Hits, RefinementList } from 'react-instantsearch-dom';
import TypesenseInstantsearchAdapter from 'typesense-instantsearch-adapter';

const typesenseAdapter = new TypesenseInstantsearchAdapter({
  server: {
    apiKey: process.env.REACT_APP_TYPESENSE_API_KEY,
    nodes: [{ host: 'localhost', port: '8108', protocol: 'http' }]
  },
  additionalSearchParameters: {
    query_by: 'name,description',
    facet_by: 'category,in_stock',
    sort_by: 'rating:desc'
  }
});

const searchClient = typesenseAdapter.searchClient;

function App() {
  return (
    <InstantSearch searchClient={searchClient} indexName="products">
      <SearchBox />
      <RefinementList attribute="category" />
      <Hits hitComponent={ProductHit} />
    </InstantSearch>
  );
}

function ProductHit({ hit }) {
  return (
    <div>
      <h3>{hit.name}</h3>
      <p>${hit.price} — Rating: {hit.rating}</p>
    </div>
  );
}

export default App;

require 'typesense'

client = Typesense::Client.new(
  nodes: [{ host: 'localhost', port: 8108, protocol: 'http' }],
  api_key: ENV['TYPESENSE_API_KEY'],
  connection_timeout_seconds: 2
)

results = client.collections['products'].documents.search(
  q: 'running shoes',
  query_by: 'name,description',
  filter_by: 'in_stock:true',
  sort_by: 'price:asc'
)

puts "Found #{results['found']} results"
results['hits'].each { |hit| puts "- #{hit['document']['name']}" }

package main

import (
    "fmt"
    "os"
    "github.com/typesense/typesense-go/v2/typesense"
    "github.com/typesense/typesense-go/v2/typesense/api"
)

func main() {
    client := typesense.NewClient(
        typesense.WithServer("http://localhost:8108"),
        typesense.WithAPIKey(os.Getenv("TYPESENSE_API_KEY")),
    )

    searchParams := &api.SearchCollectionParams{
        Q:        "keyboard",
        QueryBy:  "name,description",
        FilterBy: "in_stock:true",
        SortBy:   "rating:desc",
    }

    results, err := client.Collection("products").Documents().Search(searchParams)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Found: %d\n", *results.Found)
    for _, hit := range *results.Hits {
        doc := *hit.Document
        fmt.Printf("- %s ($%.2f)\n", doc["name"], doc["price"])
    }
}

# /etc/nginx/sites-available/typesense
server {
    listen 443 ssl http2;
    server_name search.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8108;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 30s;
    }
}

# docker-compose.yml
version: '3.8'

services:
  typesense:
    image: typesense/typesense:27.1
    restart: unless-stopped
    ports:
      - "127.0.0.1:8108:8108"
    volumes:
      - typesense-data:/data
    environment:
      TYPESENSE_API_KEY: ${TYPESENSE_API_KEY}
    command: >
      --data-dir /data
      --api-key ${TYPESENSE_API_KEY}
      --enable-cors
      --ssl-refresh-interval-seconds 86400
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 1G

  # 선택사항: Caddy를 통한 자동 HTTPS
  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy-data:/data

volumes:
  typesense-data:
  caddy-data:

// 'Electronics' 카테고리만 볼 수 있는 범위 지정 API 키 생성
const typesense = require('typesense');

const client = new Typesense.Client({
  nodes: [{ host: 'localhost', port: '8108', protocol: 'http' }],
  apiKey: 'master-api-key',
  connectionTimeoutSeconds: 2
});

// 임베디드 필터가 있는 키 생성
const scopedKey = client.keys().generateScopedSearchKey(
  'master-api-key',
  { filter_by: 'category:=Electronics' }
);

console.log('Electronics용 범위 키:', scopedKey);
// 이 키는 Electronics 제품만 검색할 수 있음

# 노드 1
docker run -d -p 8108:8108 \
  -v typesense-data:/data \
  typesense/typesense:27.1 \
  --data-dir /data \
  --api-key=$API_KEY \
  --nodes=/data/nodes \
  --peering-subnet=10.0.0.0/16 \
  --peering-port=8107

# 노드 2와 3: 동일 명령, --nodes에 모든 IP 업데이트

# 동의어 생성: "laptop" = "notebook"
curl -s "http://localhost:8108/collections/products/synonyms" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  -d '{"synonyms": ["laptop", "notebook"]}'

# 큐레이션: "deals" 쿼리 시 제품 ID 123을 항상 1위로 표시
curl -s "http://localhost:8108/collections/products/overrides" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  -d '{
    "rule": {"query": "deals", "match": "contains"},
    "includes": [{"id": "123", "position": 1}]
  }'