Page tree
Skip to end of metadata
Go to start of metadata


A scope query lets us search for entities of a specific type that occur within a specific field.  For instance, the advanced query "title:scope(location)" matches any location entity that occurs in the title field.  The text:location scope facet displays the locations that matched the query. 

The ScopeFacetRequest    Java class lets us compile a facet list of the entities that matched the query.  For instance, this is how SAIL displays a facet list of location entities that were found in the title field:

A scope facet request (&facet=title:location ) is meaningless without a paired scope-search pattern for the same field (&q=title:scope(location) ).


View incoming links.

Scope Queries and Scope Facets

When the query contains a single scope query phrase, such as "title:scope(location)", the corresponding scope facet displays all of the entities that matched the query.  For instance, you can run the FactBook (Quick Start) demo and paste this URL into the browser's address field:

Browser address field

The resulting scope facet of locations matched in the title field looks like this:

Similarly, you can execute a different scope query and get a different facet of matching entities. 

Browser address field

This is the list of "people" that AIE recognized in the country text fields. 

However, if you ask AIE to find all documents that contain locations in the title field AND people in the text field, and then show you the corresponding scope facets, you get the following:

Browser address field

The scope facets show the entities in the final result set that matched the scope-search phrases.   The smaller the result set, the fewer entities you should expect to see.

Java Client API

It is very simple to add this behavior to a Java Client API project like the Search Application Example, which contains optional code for demonstrating a scope query and scope facet.

These are the relevant code snippets from that example:

    // Create query request using a scope query:
    QueryRequest request = new QueryRequest("text:scope(location)", QueryLanguages.ADVANCED);


    // Request a ScopeFacet of locations matched in the text field.
    request.addFacet(new ScopeFacetRequest("text","location"));


    // Execute search request, get response
    QueryResponse response =;


    // Print out scope facet
    System.out.println("Facet: " + response.getFacet("text:location").getField());
    for (FacetBucket bucket : response.getFacet("text:location")) {
        System.out.println("    " + bucket);

This example assumes that you have posed a scope query, which requires the Advanced Query Language.

To see the full example file in context, consult the scope search optional feature of the Search Application Example.

REST Syntax

Scope facets can be generated through the JSON REST API using this syntax:


  • FIELDNAME - The field containing the matching scopes.
  • PARAMETERS - optional comma-separated list of parameters to apply to matching fields function

Supported Parameters:

The parameters for scope facets are:

  • depth - The number of result rows to process for facet values. Limiting this number to 100 lines, for instance, created a "shallow" facet.
  • maxmemory - Maximum memory to allocate to building the facet list.
  • shallowmode - Mode for executing facets that support shallow computations.
    • ALL_DOCS - Facet is computed over the entire result set.

    • SAMPLE - Facet is computed over a sample of the result set.

    • TOP_ROWS - Facet is computed over the first N rows of the result set. 



There are other examples of using the JSON REST API above on this page. This one includes the parameters.






  • No labels