Understanding ultimus, unique and accuracy-index in fact searches

[David Tauriello]

A Member writes:

I’m trying to understand why a query using fact.ultimus=true reports different results when I add the unique attribute (checkbox on XBRL Filed Data spreadsheet extension, or &unique directly in the XBRL API query). Here’s the query without the &unique or &fact.ultimus=true attributes:

https://api.xbrl.us/api/v1/fact/search?entity.code=0000940944&period.fiscal-year=2022&period.fiscal-period=Y&concept.local-name=NetIncomeLoss&fact.has-dimensions=false&fields=concept.local-name,fact.value,period.fiscal-period,period.fiscal-year,report.document-type,report.id

1. The unique filter qualifies the request as “if this fact appears more than once in the results, just show it one time”.

   The phrase in the results is an essential characteristic of unique, which parses each row and drops all matches to leave a single case. If you add fact.id to the fields displayed these values will be different for each and every fact, making the result set similar to the ALL results query. Note: unique will not drop instances where the spelling of a company name has changed across reports (eg. Nathan’s Famous Inc and Nathan’s Famous Inc. are two different spellings).

2. The fact.accuracy-index=1 filter operates on the report level to show the first instance of a fact meeting the query conditions.

3. The fact.ultimus=true filter says “show me the latest facts for this query” but does not respect the report (it evaluates all reports), so if the query excludes reports like DEF-14A because you’re looking only at 10-Ks, the results might not include the latest value.

The view below summarizes these distinctions. The left side of the worksheet applies unique and ultimus with unique. In the latter case, the DEF-14A report matches the query.

On the right side, additional display fields for ultimus and accuracy-index help illustrate why accuracy-index would be a better choice to get results if the query was restricted to 10-K reports.

[Author]

Posts