WVUPress/supafolio-api-docs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
supafolio-api-docs/typesense-api-complete.md

19 KiB
Raw Blame History

TypeSense API Complete Documentation

Overview

TypeSense is an open-source, typo-tolerant search engine designed for fast, instant search experiences. Built from the ground up in C++, it offers millisecond response times with intelligent default behaviors for search-as-you-type experiences.

Key Features

  • Open Source: Free to use and modify (besides infrastructure costs)
  • RAM-Based Indexing: Entire dataset should fit in RAM for optimal performance
  • Typo Tolerance: Built-in fuzzy matching and typo correction
  • Instant Search: Millisecond response times for typical queries
  • Privacy-Friendly: Does not collect usage analytics or personal data
  • No Record Limits: Only constrained by available RAM (up to 24 TB)

Authentication

API Key Authentication

TypeSense uses API key authentication for secure access control.

Method: Header-Based

curl -H "X-TYPESENSE-API-KEY: {api_key}" \
  "https://{host}/collections/{collection}/documents/search"

Configuration in Supapress Plugin

function supapress_set_typesense_client() {
    $apiKey = (string)get_option('typesense_api_key');
    $host = (string)get_option('typesense_host');
    
    $client = new Client([
        'nodes' => [
            [
                'host' => $host, 
                'port' => '',
                'protocol' => 'https'  
            ]
        ],
        'api_key' => $apiKey,
        'connection_timeout_seconds' => 2
    ]);
    
    return $client;
}

Required Settings

  • typesense_api_key: API authentication key
  • typesense_host: TypeSense server URL (without protocol)
  • typesense_catalog: Collection name for book data

Activation

define('TYPESENSE_API', true); // Enable TypeSense in Supapress

Complete API Endpoints Reference

1. Search Endpoint

Endpoint: GET /collections/{collection}/documents/search

Purpose: Primary search operation for finding documents based on text queries, filters, and faceting.

Complete Parameter Reference

Query Parameters
Parameter Required Description Default Example
q yes The query text to search for "javascript programming"
query_by yes Fields to search within "title,description"
prefix no Enable prefix searching true
infix no Enable infix search false
pre_segmented_query no Handle query segmentation manually false
num_typos no Max typographical errors tolerated 2
min_len_1typo no Min word length for 1 typo 4
min_len_2typo no Min word length for 2 typos 7
drop_tokens_threshold no Drop words if insufficient results 1
typo_tokens_threshold no Start typo correction after N results 1
enable_typos_for_numerical_tokens no Enable typos on numerical tokens true
enable_typos_for_alpha_numerical_tokens no Enable typos on alphanumerical tokens true
synonym_num_typos no Allow synonym resolution on typos 0
split_join_tokens no Treat space as typo fallback
drop_tokens_mode no Direction of word dropping right_to_left
max_candidates no Similar words considered for prefix/typo 4
max_extra_prefix no Max symbols before/after query 4
max_extra_suffix no Max symbols before/after query 4
preset no Preset configuration name
vector_query no Vector search query
voice_query no Base64 encoded speech
stopwords no Comma-separated stopword sets
validate_field_names no Validate field existence true
Filter Parameters
Parameter Description Example
filter_by Complex filtering expressions country: USA
Exact match vs non-exact
Multiple values
Negation
Numeric ranges
Multiple conditions
OR conditions
Array filtering
Nested object filtering
Prefix filtering
enable_lazy_filter no Incremental filtering
max_filter_by_candidates no Similar words for fuzzy filter
validate_field_names no Validate filtered fields
Ranking & Sorting Parameters
Parameter Description Example
sort_by Primary sorting control publicationDate:desc,title:asc
Multiple fields with tie-breaking
Special _text_match field
Conditional sorting
query_by_weights Field importance weighting title:2,description:1,author:1
text_match_type Text match scoring max_score (default)
prioritize_exact_match Exact match priority true
prioritize_token_position Word position priority false
prioritize_num_matching_fields Multiple field match priority true
Pagination Parameters
Parameter Description Default
page Page number 1
per_page Results per page (max 250) 10
offset Starting point 0
limit Maximum hits No limit
Faceting Parameters
Parameter Description Example
facet_by Fields to facet on category,brand,price_range
facet_strategy Facet calculation method exhaustive
max_facet_values Max facet values returned 10
facet_query Filter facet values facet_query=category:shoe
facet_query_num_typos Facet query fuzziness 2
facet_return_parent Return parent objects color.name
facet_sample_percent Sampling percentage 100
facet_sample_threshold Min hits for sampling 0
Grouping Parameters
Parameter Description Example
group_by Field to group by category,company_name
group_limit Max hits per group 3
group_missing_values Include null values in groups true
Results Parameters
Parameter Description Example
include_fields Fields to include title,author,price
exclude_fields Fields to exclude search_time_ms,out_of
highlight_fields Fields to highlight title,description
highlight_full_fields Full field highlighting title,description
highlight_affix_num_tokens Tokens around highlight 4
highlight_start_tag Highlight start tag <mark>
highlight_end_tag Highlight end tag </mark>
snippet_threshold Full field highlight length 30
limit_hits Maximum hits 200
search_cutoff_ms Search timeout No cutoff
exhaustive_search Consider all variations false
use_cache Enable server caching false
cache_ttl Cache duration in seconds 60
Curation Parameters
Parameter Description
pinned_hits Promote specific hits
hidden_hits Hide specific hits
enable_overrides Enable curation rules
override_tags Trigger specific rules

Sample Request

curl -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books/documents/search?q=javascript&query_by=title,description&sort_by=publicationDate:desc&facet_by=category,author&per_page=20"

Sample Response

{
  "hits": [
    {
      "document": {
        "id": "421",
        "title": "JavaScript: The Good Parts",
        "authors": ["Douglas Crockford"],
        "publicationDate": 1640995200,
        "categories": ["Programming", "Web Development"],
        "prices": {
          "USD": {"amount": 29.99, "discount": 5.00},
          "GBP": {"amount": 24.99, "discount": 4.00}
        },
        "image": "https://example.com/covers/js-good-parts.jpg"
      },
      "highlights": {
        "title": [
          {"value": "<mark>JavaScript</mark>", "matched_tokens": ["javascript"]}
        ]
      }
    }
  ],
  "facet_counts": [
    {
      "field_name": "categories",
      "counts": [
        {"value": "Programming", "count": 156},
        {"value": "Web Development", "count": 89},
        {"value": "Fiction", "count": 234}
      ]
    }
  ],
  "found": 1250,
  "out_of": 5000,
  "page": 1,
  "request_params": {
    "per_page": 20,
    "q": "javascript"
  },
  "search_cutoff_ms": true,
  "search_time_ms": 12
}

2. Documents Endpoint

Endpoint: POST /collections/{collection}/documents

Indexing Single Document

curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  -H "Content-Type: application/json" \
  -d '{"id": "123", "title": "New Book", "author": "Author Name"}' \
  "https://typesense.example.com/collections/books/documents"

Indexing Multiple Documents

curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  -H "Content-Type: application/jsonl" \
  --data-binary @books.jsonl \
  "https://typesense.example.com/collections/books/documents/import"

Retrieving Single Document

Endpoint: GET /collections/{collection}/documents/{id}

curl -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books/documents/123"

Updating Document

Endpoint: PATCH /collections/{collection}/documents/{id}

curl -X PATCH \
  -H "X-TYPESENSE-API-KEY: xyz" \
  -H "Content-Type: application/json" \
  -d '{"price": 19.99}' \
  "https://typesense.example.com/collections/books/documents/123"

Deleting Document

Endpoint: DELETE /collections/{collection}/documents/{id}

curl -X DELETE \
  -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books/documents/123"

3. Collections Endpoint

Endpoint: POST /collections

Create Collection

curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "books",
    "fields": [
      {"name": "title", "type": "string", "facet": true},
      {"name": "author", "type": "string", "facet": false},
      {"name": "publicationDate", "type": "int64", "facet": false},
      {"name": "price", "type": "float", "facet": true},
      {"name": "categories", "type": "string[]", "facet": true, "optional": false}
    ],
    "default_sorting_field": "publicationDate",
    "token_separators": " "
  }' \
  "https://typesense.example.com/collections"

Retrieve Collection Schema

Endpoint: GET /collections/{collection}

curl -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books"

Delete Collection

Endpoint: DELETE /collections/{collection}

curl -X DELETE \
  -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books"

4. Vector Search Endpoint

Endpoint: POST /collections/{collection}/documents/search

Vector Query

curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "vector_query": {
      "vector": [0.1, 0.2, 0.3, 0.4, 0.5],
      "k": 10
    },
    "query_by": "title"
  }' \
  "https://typesense.example.com/collections/books/documents/search"

5. Geo Search Endpoint

Endpoint: GET /collections/{collection}/documents/search

Location-based Search

curl -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books/documents/search?q=*&filter_by=location:(48.853,2.344,5.1)&sort_by=location_field_name(48.853,2.344,5.1):asc"

Geo-filtered Search

curl -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books/documents/search?q=coffee&filter_by=location:(48.853,2.344,5.1,10km)"

6. API Keys Endpoint

Generate Scoped Search Key

Endpoint: POST /keys

curl -X POST \
  -H "X-TYPESENSE-API-KEY: master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Public search key for website",
    "actions": ["documents:search"],
    "collections": ["books"],
    "expires_at": 1735689599
  }' \
  "https://typesense.example.com/keys"

List API Keys

Endpoint: GET /keys

curl -H "X-TYPESENSE-API-KEY: master_key" \
  "https://typesense.example.com/keys"

Delete API Key

Endpoint: DELETE /keys/{id}

curl -X DELETE \
  -H "X-TYPESENSE-API-KEY: master_key" \
  "https://typesense.example.com/keys/123"

7. Cluster Operations

Create Snapshot

Endpoint: POST /operations/snapshot

curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/operations/snapshot"

Compact Database

Endpoint: POST /operations/db/compact

curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/operations/db/compact"

Clear Cache

Endpoint: POST /operations/cache/clear

curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/operations/cache/clear"

Data Schema for Book Collections

Core Fields

{
  "id": "string (unique identifier)",
  "title": "string (full title)",
  "subtitle": "string (subtitle/edition)",
  "description": "string (full description)",
  "summary": "string (brief summary)",
  "authors": ["string array (author names)"],
  "publicationDate": "timestamp (Unix epoch)",
  "saleDate": "timestamp (Unix epoch)",
  "publisher": "string (publisher name)",
  "imprint": "string (imprint name)",
  "isbn13": "string (ISBN-13)",
  "isbn10": "string (ISBN-10)",
  "pages": "integer (page count)",
  "language": "string (language code)",
  "categories": ["string array (subject categories)"],
  "collections": ["string array (series collections)"],
  "formats": [
    {
      "format": {"name": "string", "format_id": "number"},
      "isbn": "string"
    }
  ],
  "prices": {
    "USD": {"amount": "number", "discount": "number"},
    "GBP": {"amount": "number", "discount": "number"},
    "CAD": {"amount": "number", "discount": "number"},
    "EUR": {"amount": "number", "discount": "number"}
  },
  "image": "url (cover image URL)",
  "assets": [
    {
      "asset": {
        "type": "string",
        "sub_type": "string",
        "path": "url",
        "width": "number",
        "height": "number"
      }
    }
  ],
  "trim": {
    "width": "number",
    "height": "number", 
    "depth": "number",
    "unit": "string"
  },
  "weight": {
    "weight": "number",
    "weight_unit": "string"
  },
  "edition": "string",
  "awards": [
    {
      "award": {"name": "string", "id": "number"}
    }
  ],
  "reviews": [
    {
      "review": {"description": "string"}
    }
  ],
  "retailers": [
    {
      "label": "string",
      "path": "string", 
      "seo": "string"
    }
  ]
}

Faceted Fields Configuration

{
  "fields": [
    {
      "name": "categories",
      "type": "string[]",
      "facet": true,
      "optional": false
    },
    {
      "name": "author",
      "type": "string",
      "facet": true
    },
    {
      "name": "publicationDate",
      "type": "int64",
      "facet": false
    },
    {
      "name": "price",
      "type": "float",
      "facet": true,
      "optional": false
    }
  ]
}

Advanced Features

Typo Tolerance

  • Damerau-Levenshtein distance for calculating edit distance
  • Configurable tolerance levels (0, 1, 2 typos)
  • Prefix/Infix search for autocomplete scenarios
  • Split join tokens for space-as-typo handling

Faceting Capabilities

  • Exhaustive vs Top Values strategies for performance
  • Numerical range faceting with custom labels
  • Nested object faceting for complex data structures
  • Facet query filtering for drill-down scenarios

Sorting Options

  • Multi-field sorting with tie-breaking
  • Text match score sorting by relevance
  • Conditional expressions for dynamic sorting
  • Decay functions for time-based relevance
  • Random sorting with seed control

Caching & Performance

  • Query result caching with TTL control
  • RAM-based indexing for instant search
  • Connection pooling for high throughput
  • Lazy filtering for large datasets

Error Handling

Common Error Responses

{
  "message": "No such collection found.",
  "code": 404
}

{
  "message": "Bad request.", 
  "code": 400
}

Error Codes Reference

Code Description Solution
400 Bad Request Check JSON syntax, required parameters
401 Unauthorized Verify API key in headers
404 Not Found Check collection/document existence
409 Conflict Document ID already exists
422 Unprocessable Validate field types/values
429 Too Many Requests Implement rate limiting
500 Internal Error Contact TypeSense support

Performance Optimization

Indexing Strategy

  • RAM allocation: Plan for 2x dataset size
  • Field selection: Search only relevant fields
  • Schema optimization: Enable sorting on frequently filtered fields
  • Tokenizer configuration: Custom separators for content

Query Optimization

  • Prefix queries: Use prefix=true for autocomplete
  • Field weighting: Prioritize important fields
  • Filter early: Apply filter_by before full text search
  • Limit results: Use per_page appropriately

Caching Strategy

  • Server-side: Enable use_cache=true for repeated queries
  • Client-side: Implement application-level caching
  • TTL management: Set appropriate cache_ttl values

Integration Examples

Basic Search Implementation

const client = new TypesenseClient({
  nodes: [{
    host: 'typesense.example.com',
    port: '443',
    protocol: 'https'
  }],
  apiKey: 'xyz',
  connectionTimeoutSeconds: 2
});

const searchResults = await client.collections('books')
  .documents()
  .search({
    q: 'javascript programming',
    query_by: 'title,description',
    facet_by: 'categories,author',
    sort_by: 'publicationDate:desc',
    per_page: 20
  });

Faceted Search with Filters

const results = await client.collections('books')
  .documents()
  .search({
    q: '*',
    filter_by: 'categories:[Programming,Web Development] && price:[20..50]',
    facet_by: 'categories,author,publicationYear',
    max_facet_values: 15,
    sort_by: 'price:asc,title:asc'
  });

Auto-complete Implementation

const suggestions = await client.collections('books')
  .documents()
  .search({
    q: userQuery,
    query_by: 'title,author',
    prefix: true,
    per_page: 8,
    highlight_fields: 'title',
    highlight_affix_num_tokens: 2
  });

Generated: 2026-01-24
TypeSense Version: v29.0
Supapress Plugin: v2.26.2