Indexing
Document schema
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
A document is one searchable record: a product, a post, a page or anything else. Documents are largely free-form. A few fields are recognised and handled specially, and everything else you send is stored and returned as it is.
Required fields
Every document must include:
| Field | Type | Notes |
|---|---|---|
id |
string (≤ 255) | Your stable identifier. Sending it again replaces the document. For PUT, the id is in the URL, not the body. |
type |
string (≤ 255) | Content type (product, post, page, …). Used for filtering and boosts. |
title |
string | The primary display field. Powers autocomplete. |
Recognised optional fields
These fields are indexed in a dedicated way, which gives better relevance and behaviour:
| Field | Type | Behaviour |
|---|---|---|
content |
text | Full-text body, matched without regard to accents or case. |
url |
keyword | The canonical link to show in results. Exact match only. |
image |
keyword | Image URL. Stored but not indexed, for display only. |
published_at |
date | When the content was first published, in ISO 8601 (2026-11-01T08:00:00Z). Orders a search sent with sort=newest. |
indexed_at |
date | Set automatically by Searcio when the document is indexed. Do not send it. |
Custom fields
Any other JSON fields you include are indexed dynamically and returned in
source, for example price, sku, brand, category, in_stock or rating.
in_stock also affects ranking: a product sent with in_stock: false is moved
down in the results rather than hidden.
{
"id": "p-42",
"type": "product",
"title": "Wireless Headphones",
"content": "Over-ear, 30h battery, noise cancelling",
"url": "/products/wireless-headphones",
"image": "https://cdn.example.com/wh.jpg",
"price": 129.00,
"sku": "WH-42",
"brand": "Acme",
"in_stock": true
}Tip: keep custom field names consistent across documents and sites if you want to search or filter on them. To make a custom field searchable, add it with a weight under the site's Search settings in the Searcio dashboard, or send the whole configuration from your plugin through the search configuration endpoint.
Variants
A product whose variants differ in colour, size or another attribute can send
them as variants, a list with one object per variant:
{
"id": "p-1",
"type": "product",
"title": "Down jacket Summit",
"attr_color": ["Red", "Blue"],
"attr_size": ["M", "XL"],
"variants": [
{ "attr_color": "Red", "attr_size": "M", "in_stock": true },
{ "attr_color": "Blue", "attr_size": "XL", "in_stock": true },
{ "attr_color": "Red", "attr_size": "XL", "in_stock": false }
]
}Keep the product's own fields as well: they power the facet counts and the
filters of a site that does not use variants. List the attributes in
variant_fields, and a search filtered by
red and XL then skips this jacket, since its red XL is sold out. A variant
without in_stock, or with in_stock: true, counts as available.
Purchase price and margin
Send one of these with a product to use profit ranking (set up under
Search settings > Ranking in the Searcio dashboard, or through
profit_ranking):
| Field | Type | Meaning |
|---|---|---|
cost_price |
number | What the product costs you, in the same currency as price. |
margin_percent |
number | The margin in percent of price (35 for 35%), for a shop that would rather not send purchase prices. Ignored when cost_price is sent. |
price_excluding_tax |
number | The selling price without tax, for a shop whose price includes it. Optional. With it, the profit per sale is counted without tax. |
Send price and cost_price on one basis, both with tax or both without: the
margin is then the same either way. The profit per sale that a minimum profit
is compared with is the margin times the price without tax when you send
price_excluding_tax (the price at which the document is indexed, a sale price
included), so tax is never counted as profit. Without it, it is price minus
cost_price in the prices you send, and tax counts as profit when your prices
include it. A value that is not a number, or above price, is ignored.
Both need price. Searcio works out the margin at the price the document is
indexed with, so a sale price lowers it until the next sync after the sale.
None of these fields is stored as sent, and the margin Searcio works out from them
never leaves Searcio: it is not returned in source, in suggestions, by
the shopping assistant, through MCP or in exports, and it cannot be made a
searchable, facet or suggest field. The field names profit_amount_cents and
profit_ratio_bp are reserved for it; a document that sends them has them
replaced.
How fields are indexed
flowchart LR
subgraph Doc["Your document"]
T[title] --- C[content] --- U[url] --- I[image] --- X["price, sku, ... (dynamic)"]
end
T --> TM["text (folding)<br/>+ .keyword<br/>+ .autocomplete (edge-ngram)"]
C --> CM["text (folding)"]
U --> UM["keyword"]
I --> IM["keyword, not indexed"]
X --> XM["dynamic mapping"]titleis indexed three ways: as typo-tolerant full text, as an exactkeyword, and as anautocompletefield for suggestions while the shopper types.contentis matched without regard to accents or case, for forgiving full-text search.typeis akeyword, which makes it ideal for filters and facets.- A field ending in
_paths, such ascategory_paths, holds a tree: each category as its path from the top, levels joined by>, plus every level above it. See Category trees. indexed_atis added for you: the time of the last sync, not of the content. Sendpublished_atto order results by date.- A field of your own takes its type from the first value it receives.
A number sent as text (
"5", as WordPress stores every custom field) makes it a text field, where a range compares text. List such a field innumeric_fieldsto map it as a number.
Identity and replacement
- The pair (site, id) uniquely identifies a document.
- Replacement: sending an existing id (in a
POSTbatch or withPUT) replaces the whole document. Send the complete object, not a partial update. - Deletion: remove a document by id with
DELETE, or leave it out of the next full sync and then remove the documents that sync did not include (see Building a plugin).
Sizes and limits
| Constraint | Value |
|---|---|
Documents per POST batch |
1 to 1000 |
id length |
≤ 255 characters |
type length |
≤ 255 characters |
| Total documents | Your plan's max_documents |
A batch with more than 1000 documents is rejected with 422. Split large
catalogues into several batches; see Documents.