Models

A model defines the structure of your records — similar to a table in a relational database.

What is a Model?

In SearchAPI, a model describes what your data looks like. Each model has a name and a set of fields, where every field has a name, a type, and optional configuration flags. Once you have a model, you can expose it through an endpoint so consumers can search or retrieve your records.

Create a model

1. In the sidebar, click Models.
2. Click the + New Model button.
3. Fill in the model name.
4. Add at least one field.
   New model form
5. Click Save.

Self-referencing models (tree structure)

Some data is hierarchical — categories with subcategories, folders, org charts. Check Self-referencing (tree structure) in the model form to let each record point to another record of the same model as its parent.

Self-referencing option and the system fields it adds

Enabling it adds three system fields to the model. Their names are fixed and they cannot be renamed or deleted:

• parent_id — the primary key of the parent record, with the same type as the model's primary key. Leave it empty (or send null / 0) for a root record. This is the only tree field you write.
• ancestors — the chain of parent records from the root down to the direct parent (the record itself is not included). Each entry contains the ancestor's primary key and its fields marked Visible In The Related Model, so a breadcrumb can be shown without extra requests.
• depth — the record's level in the tree: 0 for a root record, 1 for its children, and so on.

ancestors and depth are calculated automatically and are read-only — sending them in a write request is rejected. For example, a record in a categories model looks like this:

{
  "id": 3,
  "name": "Smartphones",
  "parent_id": 2,
  "depth": 2,
  "ancestors": [
    { "id": 1, "name": "Electronics" },
    { "id": 2, "name": "Phones" }
  ]
}

Rules

• At least one field other than the primary key must be marked Visible In The Related Model before self-referencing can be enabled, and at least one must stay marked while it's on; these fields provide the labels stored in ancestors.
• Regular fields named parent_id, ancestors or depth must be renamed or removed before enabling it.
• The option can be turned on and off freely until the model is locked. After that it stays enabled permanently.
• A record cannot be its own parent, the parent must exist, and a record cannot be moved under one of its own descendants — such writes are rejected.
• When a record's parent_id or one of its visible fields changes, the ancestors and depth of all its descendants are updated automatically in the background.
• A record that still has children cannot be deleted. Move or delete its children first.

Save vs Save and Continue

When creating a new model you have two save options:

• Save — saves the model and returns you to the Models list
• Save and Continue — saves the model and immediately clears the form so you can create another model without navigating away

Manage models

All your models are listed on the Models page. Each row shows the model name and its field names as badges. From the action buttons you can:

• Mappings — view the raw Elasticsearch mapping JSON generated for this model
• Edit — open the model editor; if the model is locked changes are saved as a new copy via Save As

Models list

Reference

Model name

The model name must follow these rules:

• Only lowercase letters, numbers, - and _ are allowed
• Must start with a lowercase letter or number
• Cannot consist of only numbers
• Maximum 50 bytes

Fields

Each model must have at least one field. Click Add Field to append a new row. Every field row contains the following inputs:

Field Name

The internal identifier for the field. Rules:

• Only lowercase letters, numbers and _ are allowed — hyphens (-) are not permitted
• Must start with a lowercase letter or number
• Cannot consist of only numbers
• Maximum 80 bytes
• Cannot be a reserved name: aggs_fields, sort_fields, q, sort, includes, excludes

Field Type

Select the Elasticsearch data type for this field. Available types include integer, long, float, keyword, text, boolean, date, nested, and object.

Field Type Format

Visible only when the field type is date. Select date (yyyy-MM-dd) or date_time (ISO 8601) to match how your values are stored.

Example Value

An optional sample value shown in the generated Swagger documentation. Maximum 250 bytes. Not available for nested and object fields.

Model (for nested / object fields)

When the field type is nested or object, a Model dropdown replaces the Example Value input. Select the related model whose structure this field embeds.

Field flags

Each field row also has the following checkboxes and options:

• Primary Key — exactly one field per model must be marked as the primary key. Only integer, long and keyword fields can be a primary key. Use long for ids that may exceed 2,147,483,647 (e.g. a MySQL BIGINT id). Setting a field as the primary key automatically marks it as Required.
• Required — when checked, the field must be present in every record. Always enabled for the primary key field.
• Searchable — includes this field in full-text search performed via the q parameter on endpoints. The q search also covers the searchable fields of any referenced nested or object models. Available only for text and keyword fields: a text field matches words inside its value, a keyword field matches only its exact value. Not available for the primary key.
• Visible In The Related Model — when another model references this model via a nested or object field, this flag controls which fields appear in the parent model's response. The primary key is always visible: its checkbox is selected and can't be cleared. If no other field is marked visible, only the primary key will appear. Additionally, if you want a Searchable field of the referenced model to be matched by the q parameter, it must also be marked as visible. Not available for nested / object fields.

Locking

Required is the one exception: it doesn't affect how records are indexed, so you can turn it on or off for a field of a locked model, even after the API version is deployed. Change the checkbox, then click the save icon next to the field. The change also applies to endpoints that already use the model. This doesn't apply to the primary key, which is always required, or to the reserved tree fields.

A model stays locked after you delete the API that uses it, for the API's 30-day recovery window, so a recovered API finds its models unchanged. After the window ends, the model can be edited again.

A model that another model's object or nested field points to is partly locked, even before any endpoint uses it. You can't change the name, type or Primary Key of its existing fields. You can still add fields, delete fields and change their flags.

Last updated: November 3, 2026