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
Swiftype Documentation / api: Document Expiration

Document Expiration

If you have Documents which you do not want to be searchable after some time in the future, you can use Swiftype's document expiration feature to automatically delete them from your search engine.

Specifying document expiration when creating or updating documents

In order to create (or update) a Document with an expiration date, you must use the asynchronous bulk indexing API. Add an expires_after key to the Document object with the time to expire as a Unix Epoch timestamp as its value. The expires_after value must be in the future.

Example - Submitting a batch of Documents with an expiration date.
curl -X POST 'https://api.swiftype.com/api/v1/engines/bookstore/document_types/books/documents/async_bulk_create_or_update' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "documents":
          [
            {
              "external_id": "3",
              "fields": [{"name": "title", "value": "my title 1", "type": "string"},
                         {"name": "page_type", "value": "user", "type": "enum"}],
              "expires_after": 1450574556
            },
            {
              "external_id": "4",
              "fields": [{"name": "title", "value": "my title 2", "type": "enum"},
                         {"name": "page_type", "value": "user", "type": "enum"}],
              "expires_after": 1450574556
            }
          ]
      }'
  
Note: There is no guarantee that a Document will be removed exactly at its expires_after time. However, it is guaranteed that a Document will not not to be automatically deleted before its expires_after time.

Searching with precise expiration

As noted above, Documents are not guaranteed to be deleted exactly at their expiration time. Therefore, there is some period of time after a Document expires that it will still appear in search results. Depending on your use case, this may be fine. However, if you need to ensure that expired Documents do not appear in search, you can use the precise_expiration search option. This option is available for both the search and suggest API endpoints.

When the precise_expiration option is used, all Documents that are not not expired (e.g., have an expires_after value in the future) and those that don't have an expires_after value set set will be returned. In other words, it filters all expired Documents from the results.

The format of the precise_expiration option is as follows:

"precise_expiration": {
  "<document_type_1_slug>": true,
  "<document_type_2_slug>": true
}

The default value is false for all Document Types (that is, expired but not yet deleted Documents will be returned in the results).

Example - Specifying precise_expiration for a Document Type.
curl -XGET 'https://api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q": "brothers",
        "precise_expiration": {
          "books": true
        }
      }'