Quick Guide
Facets will give you summary information about fields by listing all possible values of a field for a subset of Series defined by a Queries:
- Some clients have helper functions for retrieving facets. For example, Excel has =SJFacet().
- In lieu of a helper function, refer to the facets parameter of the /series endpoint in the API Reference .
- The result of a facet is always filtered by a Queries.
- Facets are written as field names, optionally followed by @operators
The simplest facet:
unit
will return all values of unit and the number series that has each values.
Use the @ to add operators:
unit@sort:term.desc
Use @@ to add sub-facets.
unit@sort:term.desc@@country
Facet Operator Reference
Note that operators don't carry across subfacets (@@). So
country@@province@sort:term.asc
only sorts the province
field.Operator | Example | Notes |
@filter:<string to filter> | unit@filter:kg* | only applies to text-based fields (not one ending in _num, _date, _geo, _obj) |
@sort:<sort style> | unit@sort:term.desc | Prefix is one of: term.asc, term.desc, count.asc, count.desc; default is count.desc |
@ranges:<#>|<#>|... | val_num@ranges:10|20 | buckets series into ranges by the cutoffs in arguments; only applies to _num and _date fields |
@tree:<prefix> | category_tree@tree: | retrieves direct children under prefix; use blank for root; only applies to _tree fields |
@period:<period letter> | forecast_date@period:M | aggregates to specified period; refer to Date Input Notation for period letters; only applies to _date fields |
@agg:<agg style> | unit@@val_num@agg:sum | one of sum, count, min, max, avg, or cardinality (approximate count of distinct values); applies to _num and _date fields |
@max_values:<max number of facets> | country@max_values:2 | this controls the max number of facet values returned. In the example to the left, this will return two countries. Note that this overrides request-level setting max_facet_values |
@cached:<cache-ttl>(,invalidate,resetTtl) | country@@product@cached:10h | See Caching for usage
Note: only works on complete facets ie. correct usage is <facet@@subfacet@op>@cached . |
@@<other facet> | unit@@country | sub-facetting allows for multiple facets. Example full syntax: <field>(@<operator:argument>)@@<field>(@<operator:argument>). Operators are optional. |