Skip to main content

Search Overrides API

Search overrides allow you to customize search behavior for specific queries, enabling you to promote, hide, or replace results for particular search terms.

Overview​

Search overrides give you fine-grained control over search results:

  • Promote documents: Boost specific documents for certain queries
  • Hide documents: Exclude documents from results for specific queries
  • Replace results: Return custom results for specific queries

List Overrides​

Get all search overrides for a collection.

Endpoint: GET /collections/{name}/overrides

Example Request:

curl http://localhost:9200/collections/products/overrides

Example Response:

{
  "overrides": [
    {
      "id": "override1",
      "rule": {
        "query": "laptop",
        "match": "exact"
      },
      "includes": [
        {"id": "product1", "position": 1}
      ]
    }
  ]
}

Create Override​

Create a new search override.

Endpoint: POST /collections/{name}/overrides/{id}

Request Body:

{
  "rule": {
    "query": "search query",
    "match": "exact|contains"
  },
  "includes": [
    {"id": "document_id", "position": 1}
  ],
  "excludes": ["document_id"]
}

Example Request - Promote Document:

curl -X POST http://localhost:9200/collections/products/overrides/promote_laptop \
  -H "Content-Type: application/json" \
  -d '{
    "rule": {
      "query": "laptop",
      "match": "exact"
    },
    "includes": [
      {"id": "product1", "position": 1}
    ]
  }'

Example Request - Hide Document:

curl -X POST http://localhost:9200/collections/products/overrides/hide_out_of_stock \
  -H "Content-Type: application/json" \
  -d '{
    "rule": {
      "query": "*",
      "match": "contains"
    },
    "excludes": ["out_of_stock_product"]
  }'

Example Response:

{
  "message": "Override created successfully",
  "id": "promote_laptop"
}

Get Override​

Get details about a specific override.

Endpoint: GET /collections/{name}/overrides/{id}

Example Request:

curl http://localhost:9200/collections/products/overrides/promote_laptop

Example Response:

{
  "id": "promote_laptop",
  "rule": {
    "query": "laptop",
    "match": "exact"
  },
  "includes": [
    {"id": "product1", "position": 1}
  ]
}

Update Override​

Update an existing override (same as create - upsert behavior).

Endpoint: POST /collections/{name}/overrides/{id} or PUT /collections/{name}/overrides/{id}

Example Request:

curl -X POST http://localhost:9200/collections/products/overrides/promote_laptop \
  -H "Content-Type: application/json" \
  -d '{
    "rule": {
      "query": "laptop",
      "match": "exact"
    },
    "includes": [
      {"id": "product1", "position": 1},
      {"id": "product2", "position": 2}
    ]
  }'

Delete Override​

Delete a search override.

Endpoint: DELETE /collections/{name}/overrides/{id}

Example Request:

curl -X DELETE http://localhost:9200/collections/products/overrides/promote_laptop

Example Response:

{
  "message": "Override deleted successfully",
  "id": "promote_laptop"
}

Override Rules​

Match Types​

  • exact: Match exact query string
  • contains: Match if query contains the rule query

Includes​

Promote specific documents to certain positions:

{
  "includes": [
    {"id": "product1", "position": 1},
    {"id": "product2", "position": 2}
  ]
}

Excludes​

Hide specific documents from results:

{
  "excludes": ["product1", "product2"]
}

Use Cases​

Promote featured products for brand searches:

{
  "rule": {
    "query": "apple",
    "match": "exact"
  },
  "includes": [
    {"id": "featured_iphone", "position": 1},
    {"id": "featured_macbook", "position": 2}
  ]
}

Hide Out of Stock Items​

Hide out-of-stock products from all searches:

{
  "rule": {
    "query": "*",
    "match": "contains"
  },
  "excludes": ["out_of_stock_product1", "out_of_stock_product2"]
}

Custom Landing Pages​

Return specific results for marketing campaigns:

{
  "rule": {
    "query": "black friday",
    "match": "exact"
  },
  "includes": [
    {"id": "black_friday_deal1", "position": 1},
    {"id": "black_friday_deal2", "position": 2}
  ]
}

Best Practices​

  1. Use sparingly: Overrides can affect search quality if overused
  2. Test thoroughly: Verify overrides improve user experience
  3. Monitor performance: Track how overrides affect search metrics
  4. Update regularly: Review and update overrides as needed
  5. Document purpose: Keep track of why each override exists

Next Steps​

  • Learn about Synonyms for equivalent terms
  • Explore Search API to see overrides in action
  • Check out Stopwords for filtering common words