Prepare text for search
Index text explicitly, then keep it in sync with its source record.
Index a field once, then search its words and return matching record IDs.
- Save the order and notesKeep the order’s stable record ID.
- Index its note textSend the words under the same ID to the document index.
- Search for a known phraseInspect the matching document IDs.
- Read the matching orderUse its ID to open the source row.
Choose the text to index
- Pick a table and field name, such as
shop.ordersandnotes. - Use the source row's primary key as the search document's
doc_id. - Index the text through the full-text endpoint.
- Index it again when the source text changes.
Writing a row through SQL or the rows API does not add it to the full-text index. The table and field strings must match exactly between indexing and searching.
Optional source-row schema
# Nothing in the schema marks a field as full-text indexed - there is no
# such flag. An FTS index comes into existence the first time you POST a
# document to a (table, field) pair. Registering the row schema is still
# worth it: it is what lets you take a doc_id from a search hit and read
# the whole row back with SQL.
namespace = "shop"
table = "orders"
primary_key = ["id"]
[[columns]]
name = "id"
ty = "str"
required = true
[[columns]]
name = "customer"
ty = "str"
[[columns]]
name = "amount_cents"
ty = "i64"
[[columns]]
name = "status"
ty = "str"
[[columns]]
name = "notes" # the field we will full-text index
ty = "str"
[[columns]]
name = "placed_ms"
ty = "u64"Index the document
The example indexes one delivery note. A successful write returns 201 with no response body. Reusing the same doc_id replaces its indexed text.
Connection used in these examples
These examples use the tenant-scoped engine API and its older SDK methods. Use the connection details supplied for that interface. For the current Connect setup, see authentication. Do not combine the two URL formats.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes" \
-H "Authorization: Bearer $OC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"doc_id": "01JTRX9KQ3YH8K2WMX0F5JZAB7",
"text": "rush delivery, signed by recipient"
}'
# → 201 Created, empty bodyIndex text from a nested JSON document
Use the /json variant and list the dotted paths to include. Omit paths only when every string leaf should be indexed.
# Walk a nested document and index its string leaves.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes/json" \
-H "Authorization: Bearer $OC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"doc_id": "01JTRX9KQ3YH8K2WMX0F5JZAB7",
"json": {
"note": "rush delivery",
"shipping": { "instructions": "signed by recipient" },
"tags": ["priority", "insured"]
},
"paths": ["note", "shipping.instructions", "tags"]
}'
# Omit "paths" to index every string leaf in the document.Adjust how words match
| Setting | Effect |
|---|---|
| Default analysis | Splits text into Unicode words and lowercases them. |
| Synonyms | Treats configured terms as alternatives, such as delivery and shipment. |
| Stopwords | Removes configured common words from indexing and queries. |
There is no selectable stemming setting: deliver does not automatically match delivery. Use an appropriate search mode, prefix or synonym instead.
Configure synonyms and stopwords
# Synonym classes - applied at BOTH index and query time.
# Re-installing replaces the whole map.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes/synonyms" \
-H "Authorization: Bearer $OC_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "synonyms": { "delivery": ["shipment", "dispatch"] } }'
# Stopwords - dropped at BOTH index and query time.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes/stopwords" \
-H "Authorization: Bearer $OC_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "stopwords": ["the", "a", "an", "and", "by", "of", "with"] }'Installing either setting replaces its whole map or list. Both affect indexing and searching, so re-index existing documents after a change. A term supports at most 32 synonyms.
Verify the result
Search the same table and field for a word in the note. If you also saved the source row, use the returned doc_id to open it. Indexing text alone does not create that row.