Schema for Full-text.

Optional fields — what each one unlocks.

Add only the fields whose effect you need. Each one buys a specific capability — speed up a predicate, guard a write, or unlock a new query shape.

What you can call (no schema knob needed).

• POST /fts/:t/:f — index plain text
• POST /fts/:t/:f/json — JSON-aware index walks dotted paths
• POST /fts/:t/:f/doc — store text + facets (required for highlight + facet aggregation)
• POST /fts/:t/:f/synonyms — install per-(table, field) synonym map
• POST /fts/:t/:f/stopwords — install per-(table, field) stopword list
• GET /fts/:t/:f?q=… — boolean / bm25 / phrase search with optional fuzzy + highlight + facets

Abbreviation legend.

Worked example.

Schema TOML — copy + register via POST /v1/tenants/:t/schemas with Content-Type: text/plain.

# ──────────────────────────────────────────────────────────────────────
# Important: FTS indexes are NOT declared in the schema TOML.
# The grammar oc_schema::Manifest accepts does NOT have a [[extractions.fts]]
# block. FTS is a pure runtime endpoint: POST text to index, GET to query.
# The analyzer is fixed (Unicode tokenize + lowercase) — there is no
# tokenizer / stemmer / analyzer knob on the POST body or in the TOML.
#
# What the TOML IS for (FTS workflows): registering the ROW schema so the
# same row is reachable via SQL alongside FTS search. Same id keeps things
# aligned.
# ──────────────────────────────────────────────────────────────────────

namespace   = "shop"
table       = "products"
primary_key = ["id"]

[[columns]]
name = "id"          
ty = "str" 
required = true
[[columns]]
name = "name"        
ty = "str"
[[columns]]
name = "description" 
ty = "str"
[[columns]]
name = "category"    
ty = "str"

[[indexes]]
name    = "by_category"
columns = ["category"]

Runtime calls.

# ════════════════════════════════════════════════════════════════════
# INDEX — 3 ways to load text
# ════════════════════════════════════════════════════════════════════

# 1) Plain text per doc — simplest
curl -X POST $BASE/v1/tenants/$T/fts/shop.products/description -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "p001",
    "text":   "Wireless Bluetooth headphones with active noise cancellation"
  }'

# 2) JSON-aware — walks dotted paths inside a nested doc
curl -X POST $BASE/v1/tenants/$T/fts/shop.products/description/json -H "Authorization: Bearer $BEARER" \
  -d '{
    "doc_id": "p001",
    "json": {
      "name": "Wireless Headphones",
      "desc": { "short": "BT 5.3 ANC", "long": "Over-ear noise-cancelling..." },
      "tags": ["audio", "premium"]
    },
    "paths": ["name", "desc.short", "desc.long", "tags"]
  }'
# Omit "paths" to index every string leaf in the document.

# 3) Store doc text + facets — REQUIRED for highlight=true and facets= queries
curl -X POST $BASE/v1/tenants/$T/fts/shop.products/description/doc -H "Authorization: Bearer $BEARER" \
  -d '{
    "doc_id": "p001",
    "text":   "Wireless Bluetooth headphones with active noise cancellation",
    "facets": {
      "category":     ["electronics"],
      "brand":        ["acme"],
      "price_bucket": ["100-200"]
    }
  }'

# ════════════════════════════════════════════════════════════════════
# CONFIG — synonyms + stopwords (optional, per (table, field) pair)
# ════════════════════════════════════════════════════════════════════

# Install synonyms — each class is treated as equivalent at both index and query time
curl -X POST $BASE/v1/tenants/$T/fts/shop.products/description/synonyms -H "Authorization: Bearer $BEARER" \
  -d '{
    "synonyms": {
      "headphones": ["earbuds", "earphones", "cans"],
      "laptop":     ["notebook", "computer"],
      "tv":         ["television"]
    }
  }'

# Install stopwords — dropped at both index and query time
curl -X POST $BASE/v1/tenants/$T/fts/shop.products/description/stopwords -H "Authorization: Bearer $BEARER" \
  -d '{
    "stopwords": ["the", "a", "an", "and", "or", "of", "in", "with", "for"]
  }'

# ════════════════════════════════════════════════════════════════════
# SEARCH — 3 modes × query params
#
# :table and :field are OPAQUE path segments — not validated against any
# schema. They must match EXACTLY between the index POST and the search GET,
# or you index one place and query another and get a silent empty result.
#
# Response shapes (verified):
#   boolean / phrase  → bare JSON array of doc_id strings:  ["p001","p014"]
#   bm25 (plain)      → bare JSON array of {doc_id,score}:  [{"doc_id":"p001","score":9.42}]
#   bm25 + highlight/facets → object: {"hits":[...],"facets":{...}}
#   bm25 + explain    → BM25 scoring-breakdown object
#   index POST        → 201 Created, EMPTY body
# ════════════════════════════════════════════════════════════════════

# Boolean mode (DEFAULT — used when ?mode= is omitted) — AND of terms, no scoring
# → ["p001", "p014"]
curl "$BASE/v1/tenants/$T/fts/shop.products/description?q=wireless+headphones" \
  -H "Authorization: Bearer $BEARER"

# BM25 mode — ranked, top-k cap via k= → [{"doc_id":"p001","score":9.42}, ...]
curl "$BASE/v1/tenants/$T/fts/shop.products/description?q=wireless&mode=bm25&k=10" \
  -H "Authorization: Bearer $BEARER"

# Phrase mode — exact in-order match
curl "$BASE/v1/tenants/$T/fts/shop.products/description?q=noise+cancellation&mode=phrase&k=10" \
  -H "Authorization: Bearer $BEARER"

# Fuzzy — every BM25 term treated as term~N. fuzzy=1 catches single typos.
# Capped at MAX_EDIT_DISTANCE = 3.
curl "$BASE/v1/tenants/$T/fts/shop.products/description?q=wirless&mode=bm25&fuzzy=1&k=10" \
  -H "Authorization: Bearer $BEARER"

# Highlight — returns {highlights: {description: ["…<em>wireless</em>…"]}} per hit
# Requires the stored-text doc was set via POST /doc above. BM25 mode only.
curl "$BASE/v1/tenants/$T/fts/shop.products/description?q=wireless&mode=bm25&k=5&highlight=true" \
  -H "Authorization: Bearer $BEARER"

# Facets — comma-separated facet field names from the stored doc.
# Returns aggregated {category: {electronics: 5, books: 2}} alongside hits.
curl "$BASE/v1/tenants/$T/fts/shop.products/description?q=wireless&mode=bm25&k=5&facets=category,brand" \
  -H "Authorization: Bearer $BEARER"

# Kitchen-sink — fuzzy + highlight + facets in one call
curl "$BASE/v1/tenants/$T/fts/shop.products/description?q=wirless&mode=bm25&k=5&fuzzy=1&highlight=true&facets=category,brand,price_bucket" \
  -H "Authorization: Bearer $BEARER"