Defining Your Schema

A schema defines the structure of your searchable documents. It specifies the fields, their data types, and how each field should be treated during search, faceting, and sorting. You must define a schema before indexing documents.

Authentication

Header	Required For	Description
x-storeid	All requests	Your store identifier
x-storesecret	Read operations	Read-only API secret
x-store-write-secret	Write operations	Write API secret

Retrieve Current Schema

curl -X GET "https://api.seekora.ai/api/v1/stores/{id}/schema" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret"

Example Response

{
  "fields": [
    { "name": "title", "type": "string", "searchable": true, "facet": false, "sort": false },
    { "name": "price", "type": "float", "searchable": false, "facet": false, "sort": true },
    { "name": "category", "type": "string", "searchable": false, "facet": true, "sort": false },
    { "name": "image_url", "type": "string", "searchable": false, "facet": false, "sort": false },
    { "name": "description", "type": "string", "searchable": true, "facet": false, "sort": false }
  ]
}

Create or Update Schema

curl -X POST "https://api.seekora.ai/api/v1/stores/{id}/schema" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-store-write-secret: your-write-secret" \
  -d '{
    "mode": "additive",
    "fields": [
      { "name": "title", "type": "string", "searchable": true },
      { "name": "price", "type": "float", "sort": true },
      { "name": "category", "type": "string", "facet": true },
      { "name": "image_url", "type": "string" },
      { "name": "description", "type": "string", "searchable": true },
      { "name": "brand", "type": "string", "facet": true },
      { "name": "in_stock", "type": "bool", "facet": true },
      { "name": "rating", "type": "float", "sort": true }
    ]
  }'

Example Response

{
  "message": "Schema updated successfully",
  "fields_added": ["brand", "in_stock", "rating"],
  "fields_unchanged": ["title", "price", "category", "image_url", "description"],
  "mode": "additive"
}

Schema Modes

The mode field controls how the update is applied to your existing schema.

Additive Mode

"mode": "additive" adds new fields to the existing schema without modifying or removing existing fields. Indexed documents are preserved. This is the safe default for production use.

• New fields are appended to the schema.
• Existing fields remain unchanged even if redefined with different options.
• No data loss occurs.

Replace Mode

"mode": "replace" drops the existing index and recreates it with the new schema. This is a destructive operation. All indexed documents are deleted and must be re-indexed.

Use replace mode when you need to change field types, remove fields, or fundamentally restructure your schema.

curl -X POST "https://api.seekora.ai/api/v1/stores/{id}/schema" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-store-write-secret: your-write-secret" \
  -d '{
    "mode": "replace",
    "fields": [
      { "name": "title", "type": "string", "searchable": true },
      { "name": "price", "type": "float", "sort": true },
      { "name": "category", "type": "string", "facet": true }
    ]
  }'

danger

Replace mode deletes all indexed documents. You must re-index your data after a replace operation.

Field Types

Type	Description	Example Values
string	Text data	"Wireless Headphones"
int32	32-bit integer	42
int64	64-bit integer	9876543210
float	Floating-point number	29.99
bool	Boolean value	true, false
string[]	Array of strings	["red", "blue", "green"]
int32[]	Array of 32-bit integers	[1, 2, 3]
float[]	Array of floats	[4.5, 3.2]

Field Options

Option	Type	Default	Description
searchable	boolean	false	Include this field in full-text search queries
facet	boolean	false	Enable filtering and aggregation on this field
sort	boolean	false	Allow sorting results by this field

Example: E-Commerce Product Schema

A typical product catalog schema covering search, filtering, and sorting needs:

{
  "mode": "additive",
  "fields": [
    { "name": "title", "type": "string", "searchable": true },
    { "name": "description", "type": "string", "searchable": true },
    { "name": "price", "type": "float", "sort": true, "facet": true },
    { "name": "sale_price", "type": "float", "sort": true },
    { "name": "category", "type": "string", "facet": true },
    { "name": "brand", "type": "string", "facet": true },
    { "name": "tags", "type": "string[]", "facet": true },
    { "name": "color", "type": "string[]", "facet": true },
    { "name": "size", "type": "string[]", "facet": true },
    { "name": "rating", "type": "float", "sort": true },
    { "name": "review_count", "type": "int32", "sort": true },
    { "name": "in_stock", "type": "bool", "facet": true },
    { "name": "image_url", "type": "string" },
    { "name": "sku", "type": "string" }
  ]
}

Best Practices

• Mark only relevant fields as searchable. Adding every field to the search index increases index size and can reduce relevance. Titles, descriptions, and tags are good candidates. URLs and IDs are not.
• Use facet for fields users filter by. Category, brand, color, and size are common facet fields in e-commerce.
• Use sort for numeric ranking fields. Price, rating, and popularity scores are typical sort fields.
• Start with additive mode. Only use replace when you need to change field types or remove fields, and always re-index afterward.
• Keep field names consistent. Use snake_case for field names to maintain consistency across your schema and indexed documents.