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.

Creating a Model

In the dashboard sidebar, navigate to Models and click the + New Model button. Fill in the model name, add at least one field, and click Save.

New model form screenshot New model form screenshot

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

Field Type

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

Field Type Format

Visible only when the field type is date or time. Select the format that matches how your date/time 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 and keyword fields can be a primary key. 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. Not available for the primary key or for nested / object fields themselves.
  • 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 of the referenced model is always included by default; 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 the primary key or for nested / object fields.

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

Managing 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 screenshot Models list screenshot

Locking

Once a published API version that uses this model exists, the model is locked and can no longer be edited directly. In this state the save button changes to Save As — entering a new name creates a fresh copy of the model that you can modify freely, leaving the original published model intact.