IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Search API precision (beta) Search API search fields »

› ›

Search API result fields

edit

Search API result fields

edit

Use Result Settings or the Search Settings API to add Result Fields to default search queries.

Change the fields which appear in search results and how their values are rendered.

Select from two ways to render text field values:

Raw: An exact representation of the value within a field. And it is exact! It is not HTML escaped.
Snippet: A snippet is an HTML escaped representation of the value within a field, where query matches are captured in  tags.

A raw field defaults to the full field with no character limit outside of max document size. A custom range must be at least 20 characters.

A snippet field defaults to 100 characters. A custom range must be between 20-1000 characters.

Only text fields provide these two options, as they are functions of the deep full-text search capabilities of App Search.

If the result_fields parameter is not given, the API will return the full, raw values for all fields.

Non-text fields are raw by default.

Raw Result Fields

edit

Learn about the XSS risks within the Sanitizaiton Guide.

Requests the exact value that was indexed.

Depending on the field type, results can be returned as either a string, number, or an array of both.

size (optional): Length of the return value. Only can be used on text fields. Must be at least 20; defaults to the entire text field. If given for a different field type other than text, it will be silently ignored.

Example - Specifying result_fields of title and description.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "everglade",
  "result_fields": {
    "title": {
      "raw": {}
    },
    "description": {
      "raw": {
        "size": 50
      }
    }
  }
}'

Example Response

{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 10
    },
    "request_id": "2442cc5b3bd956b0339d5e604b562060"
  },
  "results": [
    {
      "title": {
        "raw": "Everglades"
      },
      "description": {
        "raw": "The Everglades are the largest tropical wilderness"
      },
      "id": {
        "raw": "park_everglades"
      },
      "_meta": {
        "score": 1.0028129
      }
    },
    {
      "title": {
        "raw": "Voyageurs"
      },
      "description": {
        "raw": "This park protecting four lakes near the Canada–US"
      },
      "id": {
        "raw": "park_voyageurs"
      },
      "_meta": {
        "score": 0.0062864386
      }
    },
    {
      "title": {
        "raw": "Wrangell–St. Elias"
      },
      "description": {
        "raw": "An over 8 million acres (32,375 km2) plot of"
      },
      "id": {
        "raw": "park_wrangell–st.-elias"
      },
      "_meta": {
        "score": 0.00437395
      }
    }
  ]
}

Returning Result Fields as Snippets (Highlights)

edit

Requests a snippet of a text field.

The query match will be wrapped in  tags, for highlighting, if a match exists.

Use escaped quotations to highlight only on exact, case insensitive matches.

Matches are HTML escaped prior to inserting  tags. If you set fallback: true and there are no matches found, the raw field (no HTML escaping) will be returned in the response.

If requesting a snippet on a non-text field, the snippet field will be null.

If there is no match for your query, the snippet field will be null.

Snippets on an array value will return the first match or null. There is no fallback support.

On synonyms: If a search finds a synonym for a query, the synonym will not be highlighted.

For example, if "path" and "trail" are synonyms and a query is done for "path", the term "trail" will not be highlighted.

size (optional): Character length of the snippet returned. Must be at least 20; defaults to 100.
fallback (optional): If true, return the raw text field if no snippet is found. If false, only use snippets.

Example - Specifying result_fields snippets for title, description, and states.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "everglade",
  "result_fields": {
    "title": {
      "snippet": {
        "size": 20,
        "fallback": true
      }
    },
    "description": {
      "raw": {
        "size": 200
      },
      "snippet": {
        "size": 100
      }
    },
    "states": {
      "raw" : {},
      "snippet": {
        "size": 20,
        "fallback": true
      }
    }
  }
}'

Example Response

{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      ## Truncated!
    },
    "request_id": "2fd235c15c28a697d70f9a5dc0bdb0fb"
  },
  "results": [
    {
      "title": {
        "snippet": "<em>Everglades</em>"
      },
      "states": {
        "raw": [
          "Florida"
        ],
        "snippet": "Florida"
      },
      "description": {
        "raw": "The Everglades are the largest tropical wilderness in the United States. This mangrove and tropical rainforest ecosystem and marine estuary is home to 36 protected species, including the Florida",
        "snippet": "The <em>Everglades</em> are the largest tropical wilderness in the United States. This mangrove and tropical"
      },
      "id": {
        "raw": "park_everglades"
      },
      "_meta": {
        "score": 1.0028129
      }
    },
    {
      "title": {
        "snippet": "Voyageurs"
      },
      "states": {
        "raw": [
          "Minnesota"
        ],
        "snippet": "Minnesota"
      },
      "description": {
        "raw": "This park protecting four lakes near the Canada–US border is a site for canoeing, kayaking, and fishing. The park also preserves a history populated by Ojibwe Native Americans, French fur traders",
        "snippet": null
      },
      "id": {
        "raw": "park_voyageurs"
      },
      "_meta": {
        "score": 0.0062864386
      }
    },
    {
      "title": {
        "snippet": "Wrangell–St. Elias"
      },
      "states": {
        "raw": [
          "Alaska"
        ],
        "snippet": "Alaska"
      },
      "description": {
        "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include",
        "snippet": null
      },
      "id": {
        "raw": "park_wrangell–st.-elias"
      },
      "_meta": {
        "score": 0.00437395
      }
    }
  ]
}

Example - Highlight and match only an exact query: "Rocky Mountain". Will not match or highlight on "Rocky" or "Mountain" — only "Rocky Mountain".

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "\"Rocky Mountain\"",
  "result_fields": {
    "title": {
      "snippet": {
        "size": 20,
        "fallback": true
      }
    },
    "description": {
      "raw": {
        "size": 50
      }
    }
  }
}'

Example Response

{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 2,
      "size": 10
    },
    "request_id": "d8ec5ddbb24be9de77d0190139ec8a49"
  },
  "results": [
    {
      "title": {
        "snippet": "<em>Rocky</em> <em>Mountain</em>"
      },
      "description": {
        "raw": "Bisected north to south by the Continental Divide,"
      },
      "id": {
        "raw": "park_rocky-mountain"
      },
      "_meta": {
        "score": 108.32677
      }
    },
    {
      "title": {
        "snippet": "Glacier"
      },
      "description": {
        "raw": "The U.S. half of Waterton-Glacier International"
      },
      "id": {
        "raw": "park_glacier"
      },
      "_meta": {
        "score": 65.18001
      }
    }
  ]
}

Errors

edit

result_fields

If a result field requested does not exist in the current schema. If a request field JSON object is malformed. It must be an empty JSON object or have keys of raw and/or snippet and a value of a JSON object optionally containing keys of size and fallback (if requesting a snippet). If the requested raw size is less than 15. If a size is requested for a non text field. If the requested snippet size is not greater or equal to 20 and less than 1000. If the fallback parameter for a snippet is not a boolean.

« Search API precision (beta) Search API search fields »