search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Schema

Adjusting your Schema begins a reindex of your data. Your Schema can not be changed during a reindex.


App Search will create a Schema for you when you first ingest your documents. You can also choose to create your Schema first, then fit your application data to match. Either way, the Schema is the blue-print that your Engine will use to search through your documents. Why? Uniformity through field type is helpful for search algorithms. It allows them to be much more expedient.

A Schema contains Fields with various Types. This endpoint allows you to return the Schema, add new Fields and change the Type of any Field.

Your Fields are the keys that coincide with your documents.

The Type is the format of the Field.

# An example JSON object for the Schema endpoint... "field": "type"
{
  "fruit": "text",
  "quantity": "number",
  "location": "geolocation",
  "expiry": "date"
}

By default, Fields are created as text. App Search supports four different Field Types...

textA full-text, deeply analyzed string value. This is the default type for all new fields. Supports full-text search, highlighting, filtering, faceting, value boosting and sorting.
numberA finite double-precision floating point value (e.g. 3.14 or 42). Supports filtering, faceting, functional boosting, value boosting and numeric sorting.
dateAn RFC3339 formatted date string value (e.g. "2018-04-27T16:20:00Z"). The time parameters may be omitted: YYYY-MM-DD. Supports filtering, faceting, functional boosting, value boosting and time based sorting.
geolocationA lat/long formatted string value (e.g. "37.7894758,-122.3940638"). Supports filtering, geo distance faceting and functional boosting.

Authentication

For authentication, the Schema endpoint requires your unique Host Identifier, the name of your Engine and a Private API Key. The key begins with private- and was created for you upon account creation. You can find it, along with your Host Identifier, within the Credentials menu.

They fit into your requests like so:

curl -X GET 'https://[HOST_IDENTIFIER].api.swiftype.com/api/as/v1/engines/[ENGINE]/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [PRIVATE_API_KEY]'

Request / Response Examples

Below you will find examples for the following operations:

List Schema

GET /api/as/v1/engines/{ENGINE_NAME}/schema
Example - A GET request to return the whole schema.
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx'
Example Response
{
  "name": "text",
  "authors": "text",
  "downloads": "text",
  "info": "text"
}

Example - A GET request to return the whole schema.
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx'
Example Response
No Java example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "text",
  "info": "text"
}

Example - A GET request to return the whole schema.
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx'
Example Response
No Node example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "text",
  "info": "text"
}

Example - A GET request to return the whole schema.
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx'
Example Response
No Ruby example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "text",
  "info": "text"
}

Example - A GET request to return the whole schema.
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx'
Example Response
No Python example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "text",
  "info": "text"
}

Example - A GET request to return the whole schema.
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "text",
  "info": "text"
}

Update Schema

Adjusting your Schema begins a reindex of your data. Your Schema can not be changed during a reindex.


When updating a Schema, you can either...

Updates an Existing Schema

POST /api/as/v1/engines/{ENGINE_NAME}/schema
Example - A POST request that changes the downloads field from text to number.
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}'
Example Response
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}

Example - A POST request that changes the downloads field from text to number.
No Java example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}'
Example Response
No Java example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}

Example - A POST request that changes the downloads field from text to number.
No Node example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}'
Example Response
No Node example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}

Example - A POST request that changes the downloads field from text to number.
No Ruby example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}'
Example Response
No Ruby example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}

Example - A POST request that changes the downloads field from text to number.
No Python example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}'
Example Response
No Python example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}

Example - A POST request that changes the downloads field from text to number.
No Javascript example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}'
Example Response
No Javascript example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text"
}

Creates a new Schema Field

Example - A POST request to add a new date field, uploaded.
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}'
Example Response
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}

Example - A POST request to add a new date field, uploaded.
No Java example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}'
Example Response
No Java example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}

Example - A POST request to add a new date field, uploaded.
No Node example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}'
Example Response
No Node example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}

Example - A POST request to add a new date field, uploaded.
No Ruby example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}'
Example Response
No Ruby example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}

Example - A POST request to add a new date field, uploaded.
No Python example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}'
Example Response
No Python example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}

Example - A POST request to add a new date field, uploaded.
No Javascript example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/ruby-gems/schema' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}'
Example Response
No Javascript example available, showing cURL
{
  "name": "text",
  "authors": "text",
  "downloads": "number",
  "info": "text",
  "created": "date"
}

Errors!

If one field fails validation then the entire set will fail. The errors are straightforward, although you might enjoy some additional context to help you troubleshoot. Name indicates the name of the field. Type indicates the type of the field.

400 Error MessageSolution
"Type is not included in the list"The allowed types are: text, number, date, geolocation". Ensure that no spaces are included and only one of the four types is present. Watch out for integer, which will not work - expects number.
"Engine is reindexing."You may proceed with Schema changes once reindexing is complete. Time varies based on size of Engine.
"Name cannot contain whitespace"Can not contain any whitespace characters like 'my field'
"Name cannot have a leading underscore"Can not start with a leading underscore like '_myfield'.
"Name cannot contain more than 64 characters"Very long field names are not allowed.
"Name cannot be a reserved field (external_id, engine_id, highlight, or, and, not, any, all, none)"These field names are reserved for your safety :). For example, trying to define an 'all' filter for a field called 'all' would be very difficult to understand.
"Name can only contain lowercase letters, numbers, and underscores"No dashes, capitals, strange characters or other such silliness!
"Name must contain a lowercase letter"You can not have a field with only capital letters.
"Name must be unique"Each field name must be unique.

What's Next?

The Schema endpoint is how you adjust your foundational data model. Now that you know how to make Schema changes via the API, you may be interested in exploring deeper into Indexing Documents. Alternatively, you may be into some of the deeper analytics presented by Curations and Clickthrough.


Stuck? Looking for help? Contact Support!