Typesense Skill

Schema management, document operations, search queries, and LLM-ready context generation for Typesense.

Prerequisites

Set these environment variables (via .env or shell):

TYPESENSE_HOST=https://your-instance.typesense.net
TYPESENSE_API_KEY=your_admin_or_search_api_key
TYPESENSE_PORT=443        # optional, defaults to 443
TYPESENSE_PROTOCOL=https  # optional, defaults to https

Install dependencies:

cd scripts && npm install

Primary Workflow: Natural Language to Typesense Query

Step 1 -- Generate schema context for the target collections:

node scripts/generate_schema_context.js --collections products

This fetches collection schemas, identifies searchable/facetable/sortable fields, samples enum values via faceting, and formats output as a structured LLM prompt. Translated from the generate_schema_prompt function in natural_language_search_model_manager.cpp.

Step 2 -- Use the generated context in a prompt:

Given this Typesense schema:
[paste generated context]

Convert this natural language query to Typesense search parameters:
"Show me laptops under $1000 from Apple or Dell, sorted by rating"

Step 3 -- Execute the generated query:

node scripts/search.js products "laptop" \
  --filter "price:<1000 && brand:=[Apple,Dell]" \
  --sort "rating:desc"

Core Operations

Schema Introspection

# All collections
node scripts/generate_schema_context.js

# Specific collections with custom facet limit
node scripts/generate_schema_context.js \
  --collections products,articles \
  --max-facet-values 10

# Save to file
node scripts/generate_schema_context.js --output schema_context.txt

Document Search

node scripts/search.js products "wireless headphones"
node scripts/search.js products "laptop" --filter "price:[500..2000]" --sort "rating:desc"

Collection Management

# Create from schema file
node scripts/create_collection.js schema.json

# List collections
curl "${TYPESENSE_HOST}/collections" \
  -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

# Delete collection
curl -X DELETE "${TYPESENSE_HOST}/collections/{collection}" \
  -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

Document Import

# Bulk import (JSONL, one JSON object per line)
./scripts/import_documents.sh products products.jsonl

# Single document
curl -X POST "${TYPESENSE_HOST}/collections/products/documents" \
  -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"id":"prod-001","name":"Wireless Headphones","price":99.99}'

Helper Scripts

Debug Checklist

• Verify TYPESENSE_HOST includes protocol (https://)
• Confirm TYPESENSE_API_KEY has required permissions
• Check filter syntax (common: wrong operators, missing colons)
• Validate field names match schema exactly (case-sensitive)
• Ensure numeric fields use correct type (float vs int32 vs int64)
• For import errors, validate JSONL format (one object per line, no trailing commas)

Additional Resources

• For search parameters, filter syntax, field types, and best practices, see api-reference.md
• For workflow examples (autocomplete, faceted search, semantic search, multi-tenant), see examples.md
• Official docs: https://typesense.org/docs/