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 that can be searched over as a whole, and can 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 share the same schema, but it is not required that all document include all 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.

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-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '[
    {
      "id": "441376183",
      "make": "Toyota",
      "model": "4RUNNER",
      "year": "2017",
      "color": "blue",
      "drivetrain": "AWD",
      "category": "Full-Size SUV",
      "seats": 7,
      "status": "available",
      "daily_rate": 79,
      "ac": true,
      "mileage_policy": "unlimited",
      "current_location": "37.6213, -122.3790"
    },
    {
      "id": "781226450",
      "make": "Ford",
      "model": "Fiesta",
      "year": "2018",
      "color": "red",
      "drivetrain": "FWD",
      "category": "Compact",
      "seats": 5,
      "status": "available",
      "daily_rate": 27,
      "ac": true,
      "mileage_policy": "unlimited",
      "current_location": "37.6213, -122.3790"
    }
  ]'

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-7s23ap", "api-3958sdlfjadsf");
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("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");

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("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");

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

try {
  List<Map<String, Object>> indexDocumentResults = client.indexDocuments(engineName, documents);
} catch (ClientException e) {
  // handle error
}

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

const client = new SwiftypeAppSearchClient('host-7s23ap', 'api-3958sdlfjadsf')
const engineName = 'rent-a-car'
documents = [
    {
        id: '441376183',
        make: 'Toyota',
        model: '4RUNNER',
        year: '2017',
        color: 'blue',
        drivetrain: 'AWD',
        category: 'Full-Size SUV',
        seats: 7,
        status: 'available',
        daily_rate: 79,
        ac: true,
        mileage_policy: 'unlimited',
        current_location: '37.6213, -122.3790'
    },
    {
        id: '781226450',
        make: 'Ford',
        model: 'Fiesta',
        year: '2018',
        color: 'red',
        drivetrain: 'FWD',
        category: 'Compact',
        seats: 5,
        status: 'available',
        daily_rate: 27,
        ac: true,
        mileage_policy: 'unlimited',
        current_location: '37.6213, -122.3790'
    }
]

client.indexDocuments(engineName, documents)
  .then((indexDocumentResults) => {
    // handle index document results
  })
  .catch((error) => {
    // handle error
  })

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

client = SwiftypeAppSearch::Client.new(:account_host_key => 'host-7s23ap', :api_key => 'api-3958sdlfjadsf')
engine_name = 'rent-a-car'
documents = [
  {
    'id': '441376183',
    'make': 'Toyota',
    'model': '4RUNNER',
    'year': '2017',
    'color': 'blue',
    'drivetrain': 'AWD',
    'category': 'Full-Size SUV',
    'seats': 7,
    'status': 'available',
    'daily_rate': 79,
    'ac': true,
    'mileage_policy': 'unlimited',
    'current_location': '37.6213, -122.3790'
  },
  {
    'id': '781226450',
    'make': 'Ford',
    'model': 'Fiesta',
    'year': '2018',
    'color': 'red',
    'drivetrain': 'FWD',
    'category': 'Compact',
    'seats': 5,
    'status': 'available',
    'daily_rate': 27,
    'ac': true,
    'mileage_policy': 'unlimited',
    'current_location': '37.6213, -122.3790'
  }
]

begin
  index_document_results = client.index_documents(engine_name, documents)
  # handle index document results
rescue SwiftypeAppSearch::ClientException => e
  # handle error
end

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

client = Client('host-7s23ap', 'api-3958sdlfjadsf')
engine_name = 'rent-a-car'
documents = [
    {
        'id': '441376183',
        'make': 'Toyota',
        'model': '4RUNNER',
        'year': '2017',
        'color': 'blue',
        'drivetrain': 'AWD',
        'category': 'Full-Size SUV',
        'seats': 7,
        'status': 'available',
        'daily_rate': 79,
        'ac': True,
        'mileage_policy': 'unlimited',
        'current_location': '37.6213, -122.3790'
    },
    {
        'id': '781226450',
        'make': 'Ford',
        'model': 'Fiesta',
        'year': '2018',
        'color': 'red',
        'drivetrain': 'FWD',
        'category': 'Compact',
        'seats': 5,
        'status': 'available',
        'daily_rate': 27,
        'ac': True,
        'mileage_policy': 'unlimited',
        'current_location': '37.6213, -122.3790'
    }
]

try:
    index_document_results = client.index_documents(engine_name, documents)
except SwiftypeAppSearchError:
    # handle exception
    pass

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.

IdAn identifier string value. Only used for the id field. Supports exact-match searching, filtering, faceting, value boosting, and sorting.
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.
Geo LocationA 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.