Skip to content

Facet Queries

Jump to bottom
hunterhacker edited this page Dec 1, 2011 · 17 revisions

Facet Queries

Facets generate a summary of the data that's in the database for any configured range index or bucketed range index. Let's say that we have a database of articles and a range index on the author's name. Facet queries allow us to see a unique list of authors along with how many articles each one has written.

Facet queries are executed by making a request to the facet endpoint /facet/<range-index-name>. For example, with our author range index, this request will return a unique list of authors from documents as well as how often each author occurs:

/facet/author

Such a request would return results like:

{"author":[
    {"value": "Noam Chomsky", "count": 96},
    {"value": "Aristotle", "count": 63},
    {"value": "George Orwell", "count": 26},
    …   
]}

Limiting facets with a query

The results can also be limited via a query. Queries can be submitted in either the string query format or the structured query format. For example:

/facet/author?stringQuery=title:"Manufacturing Consent"
/facet/author?structuredQuery={"range":{"name":"title","value":"Manufacturing Consent"}}

Doing so might limit your results to the following:

{"author":[
    {"value": "Noam Chomsky", "count": 1} 
]}

Limiting the number of results returned

If a given facet query will produce a large number of results, it can be limited with the limit parameter:

/facet/author?limit=10

Getting results from more than one facet

If the results from more than one facet are desired, a comma separated list of them can be supplied. The following request will return a facet summary from both the author and the decade range indexes for the given query:

/facet/author,decade?q=title:"Manufacturing Consent"

Outputting as XML or JSON

By default the output format for the results is JSON. This can be modified by using the outputFormat paramater:

/facet/author?outputFormat=xml

Will the results as XML:

<results xmlns="http://marklogic.com/corona">
    <facet name="author">
        <result>
            <value>Noam Chomsky</value>
            <count>96</count>
        </result>
        <result>
            <value>Aristotle</value>
            <count>63</count>
        </result>
        <result>
            <value>George Orwell</value>
            <count>26</count>
        </result>
    </facet>
</results>

Controlling how results are ordered

By default the facet results will be ordered by how often the value occurs (their frequency) in a descending fashion. That means that with our author example, if Chomsky has authored more books than Aristotle, Chomsky will be returned before Aristotle. But sometimes we'd like the results back in alphabetical order. This can be accomplished by supplying an order parameter. Valid values for the order parameter include: frequency (the default), ascending and descending (both alphabetical).

/facet/author?order=ascending

Our results would now look like:

{"author":[
    {"value": "Aristotle", "count": 63},
    {"value": "George Orwell", "count": 26},
    {"value": "Noam Chomsky", "count": 96}
]}

Discussion

Should standardize this page to match the usual template.

Should add discussion about buckets.

Clone this wiki locally