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

Indexing Documents

You can use the Documents API to populate your engine with data. This should be after creating an engine and before trying to search (since you don't have any data yet!). When adding documents to an engine, you are creating a collection of items that share a common schema and can be searched over as a whole. They can also be filtered on using a similar set of attributes.

Defining a Document

A document is a representation of a single record in your search engine. Every document in an engine shares the same schema, but it is not required that all documents include all of the fields found in the schema. You do not have to preemptively create a schema prior to indexing documents, as Swiftype App Search handles schema generation and more for you.

A document consists of one or more fields, which are keys shared across all documents, and values. Documents are represented as JSON objects across all APIs, both for requests and responses. Documents use a flat structure: a document field cannot be nested within another one.

Values with nested attributes will be indexed as strings.

Adding Documents to an Engine

To add documents to your engine, send a POST request to the Documents API.

POST /api/as/v1/engines/{ENGINE_NAME}/documents
Example - Indexing documents in the rent-a-car engine
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  {
    "id": "441376183",
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "color": "blue",
    "drivetrain": "AWD",
    "description": "A gorgeous three wheel drive that handles rapid stops, highway speeding, and cruising through red stop signs with ease.",
    "category": "Full-Size SUV",
    "seats": 7,
    "status": "available",
    "daily_rate": 79,
    "ac": true,
    "mileage_policy": "unlimited",
    "current_location": "37.6213, -122.3790",
    "tags": [
      "child proof doors",
      "three wheel drive",
      "ludicrous speed",
      "premium gas",
      "red leather",
      "red seats"
    ]
  },
  {
    "id": "781226450",
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "color": "red",
    "drivetrain": "FWD",
    "description": "For when you want to party. Fiesta means \"festival\" or \"party\" in Spanish. Who wants a car that is a party pooper?",
    "category": "Compact",
    "seats": 5,
    "status": "available",
    "daily_rate": 27,
    "ac": true,
    "mileage_policy": "unlimited",
    "current_location": "37.6213, -122.3790",
    "tags": [
      "children approved",
      "fuel efficient"
    ]
  },
  {
    "id": "66867a",
    "make": "Toyota",
    "model": "Camry",
    "year": "2017",
    "tags": [
      "child safe",
      "power steering"
    ]
  }
]'

Example - Indexing documents in the rent-a-car engine
import com.swiftype.appsearch.Client;
import com.swiftype.appsearch.ClientException;
import java.util.*;

Client client = new Client("host-2376rb", "private-xxxxxxxxxxxxxxxxxxxx"); String engineName = "rent-a-car";

Map<String, Object> doc1 = new HashMap<>(); doc1.put("id", "441376183"); doc1.put("make", "Toyota"); doc1.put("model", "4RUNNER"); doc1.put("year", "2017"); doc1.put("color", "blue"); doc1.put("drivetrain", "AWD"); doc1.put("description", "A gorgeous three wheel drive that handles rapid stops, highway speeding, and cruising through red stop signs with ease."); doc1.put("category", "Full-Size SUV"); doc1.put("seats", 7); doc1.put("status", "available"); doc1.put("daily_rate", 79); doc1.put("ac", true); doc1.put("mileage_policy", "unlimited"); doc1.put("current_location", "37.6213, -122.3790"); doc1.put("tags", Arrays.asList( "child proof doors", "three wheel drive", "ludicrous speed", "premium gas", "red leather", "red seats" ));

Map<String, Object> doc2 = new HashMap<>(); doc2.put("id", "781226450"); doc2.put("make", "Ford"); doc2.put("model", "Fiesta"); doc2.put("year", "2018"); doc2.put("color", "red"); doc2.put("drivetrain", "FWD"); doc2.put("description", "For when you want to party. Fiesta means &quot;festival&quot; or &quot;party&quot; in Spanish. Who wants a car that is a party pooper?"); doc2.put("category", "Compact"); doc2.put("seats", 5); doc2.put("status", "available"); doc2.put("daily_rate", 27); doc2.put("ac", true); doc2.put("mileage_policy", "unlimited"); doc2.put("current_location", "37.6213, -122.3790"); doc2.put("tags", Arrays.asList( "children approved", "fuel efficient" ));

Map<String, Object> doc3 = new HashMap<>(); doc3.put("id", "66867a"); doc3.put("make", "Toyota"); doc3.put("model", "Camry"); doc3.put("year", "2017"); doc3.put("tags", Arrays.asList( "child safe", "power steering" ));

List<Map<String, Object>> documents = Arrays.asList(doc1, doc2, doc3);

try { List<Map<String, Object>> indexDocumentResults = client.indexDocuments(engineName, documents); } catch (ClientException e) { System.out.println(e); }

Example - Indexing documents in the rent-a-car engine
const SwiftypeAppSearchClient = require('swiftype-app-search-node')

const client = new SwiftypeAppSearchClient('host-2376rb', 'private-xxxxxxxxxxxxxxxxxxxx') const engineName = 'rent-a-car' documents = [ { id: '441376183', make: 'Toyota', model: '4RUNNER', year: '2017', color: 'blue', drivetrain: 'AWD', description: 'A gorgeous three wheel drive that handles rapid stops, highway speeding, and cruising through red stop signs with ease.', category: 'Full-Size SUV', seats: 7, status: 'available', daily_rate: 79, ac: true, mileage_policy: 'unlimited', current_location: '37.6213, -122.3790', tags: [ 'child proof doors', 'three wheel drive', 'ludicrous speed', 'premium gas', 'red leather', 'red seats' ] }, { id: '781226450', make: 'Ford', model: 'Fiesta', year: '2018', color: 'red', drivetrain: 'FWD', description: 'For when you want to party. Fiesta means "festival" or "party" in Spanish. Who wants a car that is a party pooper?', category: 'Compact', seats: 5, status: 'available', daily_rate: 27, ac: true, mileage_policy: 'unlimited', current_location: '37.6213, -122.3790', tags: [ 'children approved', 'fuel efficient' ] }, { id: '66867a', make: 'Toyota', model: 'Camry', year: '2017', tags: [ 'child safe', 'power steering' ] } ]

client.indexDocuments(engineName, documents) .then(response => console.log(response)) .catch(error => console.log(error))

Example - Indexing documents in the rent-a-car engine
require 'swiftype-app-search'

host_identifier = 'host-2376rb' api_key = 'private-xxxxxxxxxxxxxxxxxxxx' client = SwiftypeAppSearch::Client.new(host_identifier: host_identifier, api_key: api_key)

engine_name = 'rent-a-car'

documents = [ { id: '441376183', make: 'Toyota', model: '4RUNNER', year: '2017', color: 'blue', drivetrain: 'AWD', description: 'A gorgeous three wheel drive that handles rapid stops, highway speeding, and cruising through red stop signs with ease.', category: 'Full-Size SUV', seats: 7, status: 'available', daily_rate: 79, ac: true, mileage_policy: 'unlimited', current_location: '37.6213, -122.3790', tags: [ 'child proof doors', 'three wheel drive', 'ludicrous speed', 'premium gas', 'red leather', 'red seats' ] }, { id: '781226450', make: 'Ford', model: 'Fiesta', year: '2018', color: 'red', drivetrain: 'FWD', description: 'For when you want to party. Fiesta means "festival" or "party" in Spanish. Who wants a car that is a party pooper?', category: 'Compact', seats: 5, status: 'available', daily_rate: 27, ac: true, mileage_policy: 'unlimited', current_location: '37.6213, -122.3790', tags: [ 'children approved', 'fuel efficient' ] }, { id: '66867a', make: 'Toyota', model: 'Camry', year: '2017', tags: [ 'child safe', 'power steering' ] } ]

begin puts client.index_documents(engine_name, documents) rescue SwiftypeAppSearch::ClientException => e puts e end

Example - Indexing documents in the rent-a-car engine
from swiftype_app_search import Client
from swiftype_app_search.exceptions import SwiftypeAppSearchError

host_identifier = 'host-2376rb' api_key = 'private-xxxxxxxxxxxxxxxxxxxx' client = Client(host_identifier, api_key) engine_name = 'rent-a-car' documents = [ { 'id': '441376183', 'make': 'Toyota', 'model': '4RUNNER', 'year': '2017', 'color': 'blue', 'drivetrain': 'AWD', 'description': 'A gorgeous three wheel drive that handles rapid stops, highway speeding, and cruising through red stop signs with ease.', 'category': 'Full-Size SUV', 'seats': 7, 'status': 'available', 'daily_rate': 79, 'ac': True, 'mileage_policy': 'unlimited', 'current_location': '37.6213, -122.3790', 'tags': [ 'child proof doors', 'three wheel drive', 'ludicrous speed', 'premium gas', 'red leather', 'red seats' ] }, { 'id': '781226450', 'make': 'Ford', 'model': 'Fiesta', 'year': '2018', 'color': 'red', 'drivetrain': 'FWD', 'description': 'For when you want to party. Fiesta means &quot;festival&quot; or &quot;party&quot; in Spanish. Who wants a car that is a party pooper?', 'category': 'Compact', 'seats': 5, 'status': 'available', 'daily_rate': 27, 'ac': True, 'mileage_policy': 'unlimited', 'current_location': '37.6213, -122.3790', 'tags': [ 'children approved', 'fuel efficient' ] }, { 'id': '66867a', 'make': 'Toyota', 'model': 'Camry', 'year': '2017', 'tags': [ 'child safe', 'power steering' ] } ]

try: print(client.index_documents(engine_name, documents)) except SwiftypeAppSearchError as e: print(e)

Example - Indexing documents in the rent-a-car engine
No Javascript example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  {
    "id": "441376183",
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "color": "blue",
    "drivetrain": "AWD",
    "description": "A gorgeous three wheel drive that handles rapid stops, highway speeding, and cruising through red stop signs with ease.",
    "category": "Full-Size SUV",
    "seats": 7,
    "status": "available",
    "daily_rate": 79,
    "ac": true,
    "mileage_policy": "unlimited",
    "current_location": "37.6213, -122.3790",
    "tags": [
      "child proof doors",
      "three wheel drive",
      "ludicrous speed",
      "premium gas",
      "red leather",
      "red seats"
    ]
  },
  {
    "id": "781226450",
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "color": "red",
    "drivetrain": "FWD",
    "description": "For when you want to party. Fiesta means &quot;festival&quot; or &quot;party&quot; in Spanish. Who wants a car that is a party pooper?",
    "category": "Compact",
    "seats": 5,
    "status": "available",
    "daily_rate": 27,
    "ac": true,
    "mileage_policy": "unlimited",
    "current_location": "37.6213, -122.3790",
    "tags": [
      "children approved",
      "fuel efficient"
    ]
  },
  {
    "id": "66867a",
    "make": "Toyota",
    "model": "Camry",
    "year": "2017",
    "tags": [
      "child safe",
      "power steering"
    ]
  }
]'

If you do not provide an id, one will be automatically generated for each document. However, if you run the same request again, your document will be indexed two times with different id.

Field Types

Documents need to be indexed correctly to optimize for certain types of querying and filtering. Unknown fields are initially indexed as text, but there are other types you can specify for your document's values.

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 ISO 8601 formatted date string value (e.g. "2018-04-27T16:20:00Z"). 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.

Creating and Updating the Schema

To change field types from text to a different format, go to the Schema area in the App Search dashboard.

Updating the schema - Reviewing and modifying the engine schema
Reviewing and modifying the engine schema
Fields cannot be deleted or renamed once created.


Since schemaless data is stored as text, it is not validated. If you change the schema, existing documents might not conform correctly (i.e. a number field that is all alpha characters, a date field that does not conform to ISO 8601, etc.) errors will be shown on the Field Coercion Errors Page. Swiftype App Search will store the first 10 errors for each field. If you have a large amount of documents and your engine is not being used in production, you might want to delete the documents and attempt to re-index them, looking at the errors in the response.

What's Next?

Your Documents are the life-blood of your engines. If you have not been acquainted with the Engines end-point, then that may be a great next step. Otherwise, Search is where you should venture. Alternatively, if you want to see how your documents are performing, Analytics has the insight.


Stuck? Looking for help? Contact Support!